castle-web-cli 0.4.72 → 0.4.74

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

@@ -1,8 +1,11 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { renderSpriteFrame } from '../engine/pxart';
 import { basename, formatJson, parseJsonFile } from '../engine/files';
 import { TouchControls } from '../engine/TouchControls';
 import {
   addActor,
+  arrangeActors,
+  cardSize,
   configureSceneCanvas,
   duplicateActors,
   makeScene,
@@ -28,34 +31,62 @@ import {
 } from '../engine/ui';
 import { AutoInspector } from '../engine/autoInspector';
 import { SceneUI } from '../engine/SceneUI';
+import { SelectionOverlay } from './SelectionOverlay';
 import { behaviorClasses, findBehaviorClass } from './behaviorRegistry';
-import { useEditHistory } from './editorHistory';
+import { useEditHistory, useUndoRedoShortcuts } from './editorHistory';
 const LONG_PRESS_MS = 500;
 const DRAG_THRESHOLD = 4;
 const DEFAULT_GRID_SIZE = 25;
+const EDIT_VIEWPORT = {
+  width: cardSize.width * 3,
+  height: cardSize.height * 3,
+  originX: cardSize.width,
+  originY: cardSize.height,
+};
+// Edit-camera zoom bounds. zoom > 1 magnifies (the visible viewport shrinks);
+// zoom < 1 pulls back to show more around the card.
+const MIN_EDIT_ZOOM = 0.4;
+const MAX_EDIT_ZOOM = 6;
+// Wheel-delta -> zoom-factor sensitivity for trackpad pinch (ctrl+wheel).
+const ZOOM_WHEEL_SPEED = 0.01;
+const clampZoom = (zoom) =>
+  Math.min(MAX_EDIT_ZOOM, Math.max(MIN_EDIT_ZOOM, Number(zoom) || 1));
+// Derive the effective edit viewport for a zoom level. Both extent and origin
+// scale by 1/zoom, which keeps the canvas draw path, `screenToCard`, and the
+// SelectionOverlay's `sx = box/card` projection mutually consistent (the overlay
+// just multiplies its scale by the same zoom).
+function editViewportForZoom(zoom) {
+  const z = clampZoom(zoom);
+  return {
+    width: EDIT_VIEWPORT.width / z,
+    height: EDIT_VIEWPORT.height / z,
+    originX: EDIT_VIEWPORT.originX / z,
+    originY: EDIT_VIEWPORT.originY / z,
+  };
+}
 export function SceneEditor({
   path,
   text,
   files,
-  drawings,
+  sprites,
   onChange,
   onToggleFiles,
   filesOpen,
+  headerHost,
   selectedActorIds,
   onSelectActorIds,
   multiSelectMode,
   onSetMultiSelectMode,
-  bare = false,
 }) {
   const canvasRef = useRef(null);
   const runtimeRef = useRef(null);
   const marqueeRef = useRef(null);
-  const editCameraRef = useRef({ x: 0, y: 0 });
+  const editCameraRef = useRef({ x: 0, y: 0, zoom: 1 });
   const selectedActorIdsRef = useRef(selectedActorIds);
   selectedActorIdsRef.current = selectedActorIds;
   const [isPlaying, setIsPlaying] = useState(false);
-  const [panMode, setPanMode] = useState(false);
   const history = useEditHistory(text, onChange);
+  useUndoRedoShortcuts(history);
   const showMulti = selectedActorIds.length > 1 || multiSelectMode;
   const inspectorSheet = useSelectionInspectorSheet(true);
   const { value: sceneData, error } = parseJsonFile(path, text);
@@ -63,21 +94,21 @@ export function SceneEditor({
   const getRuntime = useCallback(() => runtimeRef.current, []);
   useScenePlayLoop({
     sceneData,
-    drawings,
+    sprites,
     isPlaying,
     text,
     canvasRef,
     runtimeRef,
     editCameraRef,
-    selectedActorIds,
     marqueeRef,
+    selectedActorIdsRef,
   });
-  const panGesture = usePanGesture({ canvasRef, editCameraRef, enabled: panMode && !isPlaying });
-  useScenePlayKeys(runtimeRef, setIsPlaying);
+  const panGesture = usePanGesture({ canvasRef, editCameraRef, isPlaying });
+  useScenePlayKeys(runtimeRef);
   const gesture = useSelectionGesture({
     canvasRef,
     sceneData,
-    drawings,
+    sprites,
     isPlaying,
     selectedActorIds,
     onSelectActorIds,
@@ -101,9 +132,12 @@ export function SceneEditor({
   if (!sceneData) {
     return (
       <>
-        {bare ? null : (
-          <EditorHeader title={basename(path)} onToggleFiles={onToggleFiles} filesOpen={filesOpen} />
-        )}
+        <EditorHeader
+          title={basename(path)}
+          onToggleFiles={onToggleFiles}
+          filesOpen={filesOpen}
+          headerHost={headerHost}
+        />
         <EditorBody>
           <div className={styles.inspector}>{error}</div>
         </EditorBody>
@@ -121,6 +155,9 @@ export function SceneEditor({
     onSelectActorIds,
   });
   const snapSettings = getSnapSettings(sceneData);
+  const stageWrapStyle = {
+    backgroundColor: darkenSceneBackground(sceneData.background),
+  };
   const updateSceneSettings = (nextScene) => {
     history.commit(formatJson(setSceneSettings(sceneData, nextScene)));
   };
@@ -133,85 +170,89 @@ export function SceneEditor({
     : selectedActor
       ? `actor ${selectedActor.id}`
       : 'scene settings';
-  const playbackButtons = (
-    <PlaybackButtons
-      isPlaying={isPlaying}
-      setIsPlaying={setIsPlaying}
-      history={history}
-      panMode={panMode}
-      setPanMode={setPanMode}
-    />
-  );
-  const actorButtons = (
-    <ActorToolButtons
-      sceneData={sceneData}
-      files={files}
-      drawings={drawings}
-      selectedActorIds={selectedActorIds}
-      onSelectActorIds={onSelectActorIds}
-      isPlaying={isPlaying}
-      onChange={onChange}
-      history={history}
-    />
-  );
   return (
     <>
-      {bare ? null : (
-        <EditorHeader
-          title={sceneData.name ?? basename(path)}
-          subtitle={isPlaying ? 'WASD / arrows' : `${sceneData.actors.length} actors`}
-          right={
-            <span className={styles.mobileOnly}>
-              {playbackButtons}
-              {actorButtons}
-            </span>
-          }
-          onToggleFiles={onToggleFiles}
-          filesOpen={filesOpen}
-        />
-      )}
+      <EditorHeader
+        title={sceneData.name ?? basename(path)}
+        subtitle={isPlaying ? 'WASD / arrows' : `${sceneData.actors.length} actors`}
+        right={
+          <HeaderPlaybackButtons
+            isPlaying={isPlaying}
+            setIsPlaying={setIsPlaying}
+            history={history}
+          />
+        }
+        onToggleFiles={onToggleFiles}
+        filesOpen={filesOpen}
+        headerHost={headerHost}
+      />
       <EditorBody>
         <div className={styles.sceneWorkspace}>
           <div className={styles.sceneTools}>
-            <span aria-hidden="true" />
-            <div className={styles.sceneToolsGroup}>{playbackButtons}</div>
-            <div className={styles.sceneToolsGroup}>{actorButtons}</div>
+            <BlueprintHotbar
+              sceneData={sceneData}
+              files={files}
+              sprites={sprites}
+              canvasRef={canvasRef}
+              editCameraRef={editCameraRef}
+              selectedActorIds={selectedActorIds}
+              onSelectActorIds={onSelectActorIds}
+              isPlaying={isPlaying}
+              onChange={onChange}
+              history={history}
+            />
           </div>
-          <div className={styles.stageWrap}>
+          <div className={styles.stageWrap} style={stageWrapStyle}>
             <div className={styles.stageCard} data-castle-card>
-              <canvas
-                ref={canvasRef}
-                className={styles.stageCanvas}
-                onPointerDown={
-                  isPlaying
-                    ? playPointer.onPointerDown
-                    : panMode
-                      ? panGesture.onPointerDown
-                      : gesture.onPointerDown
-                }
-                onPointerMove={
-                  isPlaying
-                    ? playPointer.onPointerMove
-                    : panMode
-                      ? panGesture.onPointerMove
-                      : gesture.onPointerMove
-                }
-                onPointerUp={
-                  isPlaying
-                    ? playPointer.onPointerUp
-                    : panMode
-                      ? panGesture.onPointerUp
-                      : gesture.onPointerUp
-                }
-                onPointerCancel={
-                  isPlaying
-                    ? playPointer.onPointerUp
-                    : panMode
-                      ? panGesture.onPointerUp
-                      : gesture.onPointerUp
-                }
-              />
-              {isPlaying && <SceneUI getRuntime={getRuntime} />}
+              <div className={cx(styles.stageCardClip, !isPlaying && styles.stageCardEditSurface)}>
+                <canvas
+                  ref={canvasRef}
+                  className={cx(styles.stageCanvas, !isPlaying && styles.stageCanvasEdit)}
+                  onPointerDown={(event) =>
+                    isPlaying
+                      ? playPointer.onPointerDown(event)
+                      : panGesture.isSpacePanning()
+                        ? panGesture.onPointerDown(event)
+                        : gesture.onPointerDown(event)
+                  }
+                  onPointerMove={(event) =>
+                    isPlaying
+                      ? playPointer.onPointerMove(event)
+                      : panGesture.isActive()
+                        ? panGesture.onPointerMove(event)
+                        : gesture.onPointerMove(event)
+                  }
+                  onPointerUp={(event) =>
+                    isPlaying
+                      ? playPointer.onPointerUp(event)
+                      : panGesture.isActive()
+                        ? panGesture.onPointerUp(event)
+                        : gesture.onPointerUp(event)
+                  }
+                  onPointerCancel={(event) =>
+                    isPlaying
+                      ? playPointer.onPointerUp(event)
+                      : panGesture.isActive()
+                        ? panGesture.onPointerUp(event)
+                        : gesture.onPointerUp(event)
+                  }
+                />
+                {isPlaying && <SceneUI getRuntime={getRuntime} />}
+              </div>
+              {!isPlaying && selectedActorIds.length >= 1 && (
+                <SelectionOverlay
+                  canvasRef={canvasRef}
+                  editCameraRef={editCameraRef}
+                  sceneData={sceneData}
+                  selectedActorIds={selectedActorIds}
+                  snap={snapSettings}
+                  onArrange={actions.arrangeSelection}
+                  onClone={actions.duplicateSelection}
+                  onDelete={actions.deleteSelection}
+                  applyScene={(next) => onChange(formatJson(next))}
+                  recordSnapshot={history.recordSnapshot}
+                />
+              )}
             </div>
           </div>
           <aside {...inspectorSheet.rootProps}>
@@ -222,8 +263,6 @@ export function SceneEditor({
               {showMulti ? (
                 <MultiSelectInspector
                   count={selectedActorIds.length}
-                  onDelete={actions.deleteSelection}
-                  onDuplicate={actions.duplicateSelection}
                   onDeselectAll={() => {
                     onSelectActorIds([]);
                     onSetMultiSelectMode(false);
@@ -253,16 +292,11 @@ export function SceneEditor({
     </>
   );
 }
-function PlaybackButtons({ isPlaying, setIsPlaying, history, panMode, setPanMode }) {
+// Header-right playback controls, in the mockup's order: Undo, Redo, Play.
+// Play stays a play/stop toggle. Duplicate/remove live on the on-canvas toolbar.
+function HeaderPlaybackButtons({ isPlaying, setIsPlaying, history }) {
   return (
     <>
-      <IconButton
-        icon={isPlaying ? 'stop' : 'play'}
-        label={isPlaying ? 'Stop' : 'Play'}
-        active={isPlaying}
-        variant={isPlaying ? 'primary' : ''}
-        onClick={() => setIsPlaying(!isPlaying)}
-      />
       <IconButton
         icon="undo"
         label="Undo"
@@ -275,66 +309,359 @@ function PlaybackButtons({ isPlaying, setIsPlaying, history, panMode, setPanMode
         onClick={history.redo}
         disabled={!history.canRedo || isPlaying}
       />
-      <span style={{ width: 16 }} aria-hidden="true" />
       <IconButton
-        icon="camera"
-        label="Pan camera"
-        active={panMode}
-        onClick={() => setPanMode((value) => !value)}
-        disabled={isPlaying}
+        icon={isPlaying ? 'stop' : 'play'}
+        label={isPlaying ? 'Stop' : 'Play'}
+        active={isPlaying}
+        onClick={(event) => {
+          // Drop focus so a subsequent Space (a game input / pan modifier)
+          // doesn't re-activate this button and toggle play.
+          event.currentTarget.blur();
+          setIsPlaying(!isPlaying);
+        }}
       />
     </>
   );
 }
-function ActorToolButtons({
+// Blueprint hotbar -- lightweight actor stamps saved in scene.editor.blueprints.
+function BlueprintHotbar({
   sceneData,
   files,
-  drawings,
+  sprites,
+  canvasRef,
+  editCameraRef,
   selectedActorIds,
   onSelectActorIds,
   isPlaying,
   onChange,
   history,
 }) {
-  const applyScene = (next) => onChange(formatJson(next));
+  const blueprints = sceneData.editor?.blueprints ?? [];
+  const dragRef = useRef(null);
+  const suppressClickRef = useRef(false);
+  const [dragPreview, setDragPreview] = useState(null);
+  // Right-click context menu anchored at the cursor: { blueprint, x, y }.
+  const [contextMenu, setContextMenu] = useState(null);
+  const closeContextMenu = useCallback(() => setContextMenu(null), []);
   const onAdd = () => {
-    const { sceneData: next, newId } = addActor(sceneData, files, drawings);
+    const { sceneData: next, newId } = addActor(sceneData, files, sprites);
     history.recordSnapshot();
-    applyScene(next);
+    onChange(formatJson(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 onSaveSelection = () => {
+    const next = addSelectedActorBlueprint(sceneData, selectedActorIds);
+    if (next === sceneData) return;
+    history.commit(formatJson(next));
   };
-  const onRemove = () => {
-    if (selectedActorIds.length === 0) return;
-    history.recordSnapshot();
-    applyScene(removeActors(sceneData, selectedActorIds));
-    onSelectActorIds([]);
+  const onStamp = (blueprint, position) => {
+    const { sceneData: next, newId } = stampActorBlueprint(sceneData, blueprint, position);
+    if (next === sceneData) return;
+    history.commit(formatJson(next));
+    onSelectActorIds([newId]);
+  };
+  const onRemoveBlueprint = (blueprintId) => {
+    const next = removeActorBlueprint(sceneData, blueprintId);
+    if (next === sceneData) return;
+    history.commit(formatJson(next));
+  };
+  const onBlueprintContextMenu = (event, blueprint) => {
+    if (isPlaying) return;
+    event.preventDefault();
+    event.stopPropagation();
+    setContextMenu({ blueprint, x: event.clientX, y: event.clientY });
+  };
+  const onBlueprintPointerDown = (event, blueprint) => {
+    if (isPlaying || event.button !== 0) return;
+    event.preventDefault();
+    const drag = {
+      blueprint,
+      pointerId: event.pointerId,
+      startX: event.clientX,
+      startY: event.clientY,
+      moved: false,
+    };
+    dragRef.current = drag;
+    try {
+      event.currentTarget.setPointerCapture(event.pointerId);
+    } catch {
+      // Window listeners still finish the drag if capture is unavailable.
+    }
+    const onMove = (moveEvent) => {
+      if (moveEvent.pointerId !== drag.pointerId) return;
+      if (!drag.moved && Math.hypot(moveEvent.clientX - drag.startX, moveEvent.clientY - drag.startY) > DRAG_THRESHOLD) {
+        drag.moved = true;
+      }
+      if (drag.moved) {
+        setDragPreview({
+          blueprint,
+          x: moveEvent.clientX,
+          y: moveEvent.clientY,
+          overStage: Boolean(eventToStagePoint(moveEvent, canvasRef, editCameraRef)),
+        });
+      }
+    };
+    const onUp = (upEvent) => {
+      if (upEvent.pointerId !== drag.pointerId) return;
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', onUp);
+      window.removeEventListener('pointercancel', onUp);
+      dragRef.current = null;
+      setDragPreview(null);
+      if (!drag.moved) return;
+      suppressClickRef.current = true;
+      const position = eventToStagePoint(upEvent, canvasRef, editCameraRef);
+      if (position) onStamp(blueprint, position);
+    };
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', onUp);
+    window.addEventListener('pointercancel', onUp);
   };
-  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}
-      />
-    </>
+    <div className={styles.bpHotbar} aria-label="Blueprints">
+      <button
+        type="button"
+        className={styles.bpActionSlot}
+        aria-label="Save selected actor as blueprint"
+        title="Save selected actor as blueprint"
+        onClick={onSaveSelection}
+        disabled={isPlaying || selectedActorIds.length !== 1}>
+        <Icon name="stamp" />
+      </button>
+      <button
+        type="button"
+        className={styles.bpActionSlot}
+        aria-label="Add actor"
+        title="Add actor"
+        onClick={onAdd}
+        disabled={isPlaying}>
+        <span className={styles.dashedSquareIcon} aria-hidden="true" />
+      </button>
+      {blueprints.map((blueprint) => (
+        <button
+          key={blueprint.id}
+          type="button"
+          className={styles.bpSlot}
+          title={`Add ${blueprint.name}`}
+          disabled={isPlaying}
+          onPointerDown={(event) => onBlueprintPointerDown(event, blueprint)}
+          onContextMenu={(event) => onBlueprintContextMenu(event, blueprint)}
+          onClick={() => {
+            if (suppressClickRef.current) {
+              suppressClickRef.current = false;
+              return;
+            }
+            onStamp(blueprint);
+          }}>
+          <BlueprintThumbnail blueprint={blueprint} sprites={sprites} />
+        </button>
+      ))}
+      {dragPreview ? (
+        <BlueprintDragPreview preview={dragPreview} sprites={sprites} />
+      ) : null}
+      {contextMenu ? (
+        <BlueprintContextMenu
+          x={contextMenu.x}
+          y={contextMenu.y}
+          onRemove={() => onRemoveBlueprint(contextMenu.blueprint.id)}
+          onClose={closeContextMenu}
+        />
+      ) : null}
+    </div>
   );
 }
+// Cursor-anchored right-click menu for a hotbar blueprint. Mirrors the
+// pxArtTimeline ContextMenu: reuses the shared `selArrangeMenu`/`selArrangeItem`
+// chrome, fixed-positions at the click point with viewport clamping, and closes
+// on outside pointerdown or Escape.
+function BlueprintContextMenu({ x, y, onRemove, onClose }) {
+  const ref = useRef(null);
+  const [pos, setPos] = useState({ left: x, top: y });
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const margin = 8;
+    const maxLeft = Math.max(margin, window.innerWidth - rect.width - margin);
+    const maxTop = Math.max(margin, window.innerHeight - rect.height - margin);
+    setPos({ left: Math.min(x, maxLeft), top: Math.min(y, maxTop) });
+  }, [x, y]);
+  useEffect(() => {
+    const onPointerDown = (event) => {
+      if (!ref.current?.contains(event.target)) onClose();
+    };
+    const onKeyDown = (event) => {
+      if (event.key === 'Escape') onClose();
+    };
+    window.addEventListener('pointerdown', onPointerDown);
+    window.addEventListener('keydown', onKeyDown);
+    return () => {
+      window.removeEventListener('pointerdown', onPointerDown);
+      window.removeEventListener('keydown', onKeyDown);
+    };
+  }, [onClose]);
+  return (
+    <div
+      ref={ref}
+      className={styles.selArrangeMenu}
+      role="menu"
+      aria-label="Blueprint"
+      style={{ position: 'fixed', left: pos.left, top: pos.top, transform: 'none' }}
+      onPointerDown={(event) => event.stopPropagation()}
+      onContextMenu={(event) => event.preventDefault()}>
+      <button
+        type="button"
+        role="menuitem"
+        className={styles.selArrangeItem}
+        onClick={() => {
+          onRemove();
+          onClose();
+        }}>
+        Remove blueprint
+      </button>
+    </div>
+  );
+}
+function BlueprintDragPreview({ preview, sprites }) {
+  const layout = preview.blueprint.actor?.components?.Layout;
+  const width = Math.max(24, Math.min(80, layout?.width ?? 48));
+  const height = Math.max(24, Math.min(80, layout?.height ?? 48));
+  return (
+    <div
+      className={cx(styles.bpDragPreview, preview.overStage && styles.bpDragPreviewOverStage)}
+      style={{
+        left: preview.x,
+        top: preview.y,
+        width,
+        height,
+        transform: `translate(-50%, -50%) rotate(${layout?.rotation ?? 0}deg)`,
+      }}>
+      <BlueprintThumbnail blueprint={preview.blueprint} sprites={sprites} preview />
+    </div>
+  );
+}
+function BlueprintThumbnail({ blueprint, sprites, preview = false }) {
+  const canvasRef = useRef(null);
+  const spritePath = blueprint.actor?.components?.Sprite?.file;
+  const sprite = spritePath ? sprites?.[spritePath] : null;
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || !sprite) return;
+    // A .pxart blueprint renders its first frame via the SDK.
+    renderSpriteFrame(sprite, 0, canvas);
+  }, [sprite]);
+  if (!sprite) {
+    return (
+      <span className={styles.bpSlotFallback}>
+        <Icon name="clone" />
+      </span>
+    );
+  }
+  return (
+    <canvas
+      ref={canvasRef}
+      className={cx(styles.bpSlotThumb, preview && styles.bpPreviewThumb)}
+      aria-hidden="true"
+    />
+  );
+}
+function addSelectedActorBlueprint(sceneData, selectedActorIds) {
+  if (selectedActorIds.length !== 1) return sceneData;
+  const actor = sceneData.actors.find((candidate) => candidate.id === selectedActorIds[0]);
+  if (!actor) return sceneData;
+  const next = structuredClone(sceneData);
+  const copy = structuredClone(actor);
+  delete copy.id;
+  if (copy.components?.Layout) {
+    copy.components.Layout = {
+      ...copy.components.Layout,
+      x: 0,
+      y: 0,
+    };
+  }
+  const blueprints = [...(next.editor?.blueprints ?? [])];
+  const name = makeBlueprintName(actor, blueprints.length);
+  blueprints.push({
+    id: makeBlueprintId(blueprints),
+    name,
+    actor: copy,
+  });
+  next.editor = {
+    ...(next.editor ?? {}),
+    blueprints,
+  };
+  return next;
+}
+function stampActorBlueprint(sceneData, blueprint, position) {
+  if (!blueprint?.actor) return { sceneData, newId: null };
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const actor = structuredClone(blueprint.actor);
+  const newId = makeActorId(existingIds);
+  actor.id = newId;
+  actor.components = actor.components ?? {};
+  const layout = actor.components.Layout ?? { width: 64, height: 64, z: 0, rotation: 0 };
+  actor.components.Layout = {
+    ...layout,
+    x: Math.round((position?.x ?? cardSize.width / 2) - layout.width / 2),
+    y: Math.round((position?.y ?? cardSize.height / 2) - layout.height / 2),
+  };
+  next.actors.push(actor);
+  return { sceneData: next, newId };
+}
+function removeActorBlueprint(sceneData, blueprintId) {
+  const blueprints = sceneData.editor?.blueprints ?? [];
+  if (!blueprints.some((blueprint) => blueprint.id === blueprintId)) return sceneData;
+  const next = structuredClone(sceneData);
+  next.editor = {
+    ...(next.editor ?? {}),
+    blueprints: (next.editor?.blueprints ?? []).filter(
+      (blueprint) => blueprint.id !== blueprintId
+    ),
+  };
+  return next;
+}
+function eventToStagePoint(event, canvasRef, editCameraRef) {
+  const canvas = canvasRef.current;
+  if (!canvas) return null;
+  const rect = canvas.getBoundingClientRect();
+  if (
+    event.clientX < rect.left ||
+    event.clientX > rect.right ||
+    event.clientY < rect.top ||
+    event.clientY > rect.bottom
+  ) {
+    return null;
+  }
+  const raw = screenToCard(canvas, event.clientX, event.clientY);
+  const camera = editCameraRef.current ?? { x: 0, y: 0 };
+  return {
+    x: raw.x + camera.x,
+    y: raw.y + camera.y,
+  };
+}
+function makeBlueprintName(actor, index) {
+  const spriteFile = actor.components?.Sprite?.file;
+  if (spriteFile) return basename(spriteFile).replace(/\.pxart$/i, '');
+  return `Actor ${index + 1}`;
+}
+function makeBlueprintId(blueprints) {
+  const existing = new Set(blueprints.map((blueprint) => blueprint.id));
+  for (let index = 1; index < 1000; index++) {
+    const candidate = `blueprint-${index}`;
+    if (!existing.has(candidate)) return candidate;
+  }
+  return `blueprint-${Date.now()}`;
+}
+function makeActorId(existingIds) {
+  for (let attempt = 0; attempt < 64; attempt++) {
+    const candidate = Math.floor(Math.random() * 0xffffffff)
+      .toString(16)
+      .padStart(8, '0');
+    if (!existingIds.has(candidate)) return candidate;
+  }
+  return `actor-${Date.now()}`;
+}
 function makeSceneActions({ sceneData, commit, selectedActorIds, onSelectActorIds }) {
   function commitScene(next) {
     commit(formatJson(next));
@@ -362,6 +689,11 @@ function makeSceneActions({ sceneData, commit, selectedActorIds, onSelectActorId
       commitScene(next);
       if (newIds.length) onSelectActorIds(newIds);
     },
+    arrangeSelection: (action) => {
+      if (selectedActorIds.length === 0) return;
+      const next = arrangeActors(sceneData, selectedActorIds, action);
+      if (next !== sceneData) commitScene(next);
+    },
   };
 }
 function setSceneSettings(sceneData, nextScene) {
@@ -379,6 +711,34 @@ function setSceneEditorSettings(sceneData, nextEditor) {
     },
   };
 }
+function darkenSceneBackground(background) {
+  const parsed = parseHexColor(background ?? '#121213');
+  if (!parsed) return 'var(--castle-stage-workspace-bg)';
+  const amount = 0.42;
+  const darken = (channel) => Math.max(0, Math.round(channel * (1 - amount)));
+  return `rgb(${darken(parsed.r)}, ${darken(parsed.g)}, ${darken(parsed.b)})`;
+}
+function parseHexColor(value) {
+  if (typeof value !== 'string') return null;
+  const hex = value.trim().replace(/^#/, '');
+  const expand = (text) =>
+    text
+      .split('')
+      .map((char) => `${char}${char}`)
+      .join('');
+  const normalized =
+    hex.length === 3 || hex.length === 4
+      ? expand(hex.slice(0, 3))
+      : hex.length === 6 || hex.length === 8
+        ? hex.slice(0, 6)
+        : null;
+  if (!normalized || !/^[0-9a-f]{6}$/i.test(normalized)) return null;
+  return {
+    r: parseInt(normalized.slice(0, 2), 16),
+    g: parseInt(normalized.slice(2, 4), 16),
+    b: parseInt(normalized.slice(4, 6), 16),
+  };
+}
 function useSelectionInspectorSheet(open) {
   const [snap, setSnap] = useState('high');
   // Inspector visibility is driven by selection / multi-mode. Snap state
@@ -408,7 +768,7 @@ function useSelectionGesture(args) {
     const cam = current.editCameraRef.current;
     const point = { x: raw.x + cam.x, y: raw.y + cam.y };
     current.canvasRef.current.setPointerCapture(event.pointerId);
-    const scene = makeScene(current.sceneData, behaviorClasses, current.drawings);
+    const scene = makeScene(current.sceneData, behaviorClasses, current.sprites);
     const actor = scene.actorAt(point.x, point.y);
     const drag = {
       pointerId: event.pointerId,
@@ -580,36 +940,156 @@ function usePlayPointerGesture({ canvasRef, runtimeRef }) {
   );
   return { onPointerDown, onPointerMove, onPointerUp };
 }
-function usePanGesture({ canvasRef, editCameraRef, enabled }) {
+function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
   const dragRef = useRef(null);
-  const onPointerDown = useCallback(
-    (event) => {
-      if (!enabled) return;
+  const spaceDownRef = useRef(false);
+  // Native wheel/gesture listeners (below) read play state through a ref so they
+  // never need to detach/reattach when play toggles.
+  const isPlayingRef = useRef(isPlaying);
+  isPlayingRef.current = isPlaying;
+  useEffect(() => {
+    function onKeyDown(event) {
+      if (event.key !== ' ' || isEditableTarget(event.target)) return;
+      // Swallow Space's default: it would scroll the panel and re-activate a
+      // focused button (e.g. the Play/Stop toggle that keeps focus after a
+      // click), so Space only ever arms the pan modifier here.
+      event.preventDefault();
+      spaceDownRef.current = true;
+    }
+    function onKeyUp(event) {
+      if (event.key === ' ') spaceDownRef.current = false;
+    }
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('keyup', onKeyUp);
+    return () => {
+      window.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('keyup', onKeyUp);
+    };
+  }, []);
+  const panByScreenDelta = useCallback(
+    (dx, dy) => {
       const canvas = canvasRef.current;
       if (!canvas) return;
-      const point = screenToCard(canvas, event.clientX, event.clientY);
-      event.currentTarget.setPointerCapture(event.pointerId);
-      dragRef.current = { id: event.pointerId, last: point };
+      const rect = canvas.getBoundingClientRect();
+      const viewportWidth = Number(canvas.dataset.viewportWidth) || cardSize.width;
+      const viewportHeight = Number(canvas.dataset.viewportHeight) || cardSize.height;
+      editCameraRef.current = {
+        ...editCameraRef.current,
+        x: editCameraRef.current.x + (dx * viewportWidth) / rect.width,
+        y: editCameraRef.current.y + (dy * viewportHeight) / rect.height,
+      };
     },
-    [canvasRef, enabled]
+    [canvasRef, editCameraRef]
   );
-  const onPointerMove = useCallback(
-    (event) => {
-      const drag = dragRef.current;
-      if (!drag || drag.id !== event.pointerId) return;
+  // Zoom about the pointer by a multiplicative factor: keep the world point
+  // under the cursor pinned while the zoom level changes. Because the effective
+  // origin scales as EDIT_VIEWPORT.origin / zoom, the camera shift to re-pin the
+  // cursor is (1/z0 - 1/z1) * (frac * EDIT_VIEWPORT.extent - EDIT_VIEWPORT.origin).
+  const zoomByFactorAtPointer = useCallback(
+    (clientX, clientY, factor) => {
       const canvas = canvasRef.current;
-      if (!canvas) return;
-      const point = screenToCard(canvas, event.clientX, event.clientY);
-      const dx = point.x - drag.last.x;
-      const dy = point.y - drag.last.y;
-      drag.last = point;
+      if (!canvas || !Number.isFinite(factor) || factor <= 0) return;
+      const cam = editCameraRef.current;
+      const z0 = cam.zoom ?? 1;
+      const z1 = clampZoom(z0 * factor);
+      if (z1 === z0) return;
+      const rect = canvas.getBoundingClientRect();
+      const fracX = (clientX - rect.left) / rect.width;
+      const fracY = (clientY - rect.top) / rect.height;
+      const k = 1 / z0 - 1 / z1;
       editCameraRef.current = {
-        x: editCameraRef.current.x - dx,
-        y: editCameraRef.current.y - dy,
+        x: cam.x + k * (fracX * EDIT_VIEWPORT.width - EDIT_VIEWPORT.originX),
+        y: cam.y + k * (fracY * EDIT_VIEWPORT.height - EDIT_VIEWPORT.originY),
+        zoom: z1,
       };
     },
     [canvasRef, editCameraRef]
   );
+  // Wheel + pinch are bound as NATIVE, non-passive listeners (not React props):
+  // React attaches `wheel` passively at its root, so a React onWheel can't call
+  // preventDefault and the browser's own page-zoom wins. We also need Safari's
+  // proprietary `gesture*` events, which is how it reports trackpad pinch (it
+  // does not emit ctrl+wheel like Chromium). Both paths preventDefault to stop
+  // the browser from zooming the page underneath the editor.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return undefined;
+    let gestureScale = 1;
+    // Set while a Safari pinch gesture is in flight, so we don't double-apply
+    // zoom if Safari also emits ctrl+wheel for the same pinch.
+    let gestureActive = false;
+    const onWheel = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      // Trackpad pinch (and Ctrl+wheel) surface as wheel events with ctrlKey set
+      // in Chromium; route those to zoom and leave plain scroll as pan.
+      if (event.ctrlKey) {
+        if (gestureActive) return;
+        zoomByFactorAtPointer(
+          event.clientX,
+          event.clientY,
+          Math.exp(-event.deltaY * ZOOM_WHEEL_SPEED)
+        );
+      } else {
+        panByScreenDelta(event.deltaX, event.deltaY);
+      }
+    };
+    const onGestureStart = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      gestureActive = true;
+      gestureScale = event.scale || 1;
+    };
+    const onGestureChange = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      // Safari reports `scale` cumulatively from gesturestart (1.0 at start), so
+      // zoom by the ratio against the last reading.
+      const prev = gestureScale || 1;
+      const next = event.scale || prev;
+      gestureScale = next;
+      // GestureEvent carries clientX/clientY (the pinch centroid); fall back to
+      // the canvas center if a browser omits them.
+      const rect = canvas.getBoundingClientRect();
+      const px = Number.isFinite(event.clientX) ? event.clientX : rect.left + rect.width / 2;
+      const py = Number.isFinite(event.clientY) ? event.clientY : rect.top + rect.height / 2;
+      zoomByFactorAtPointer(px, py, next / prev);
+    };
+    const onGestureEnd = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      gestureActive = false;
+    };
+    const opts = { passive: false };
+    canvas.addEventListener('wheel', onWheel, opts);
+    canvas.addEventListener('gesturestart', onGestureStart, opts);
+    canvas.addEventListener('gesturechange', onGestureChange, opts);
+    canvas.addEventListener('gestureend', onGestureEnd, opts);
+    return () => {
+      canvas.removeEventListener('wheel', onWheel, opts);
+      canvas.removeEventListener('gesturestart', onGestureStart, opts);
+      canvas.removeEventListener('gesturechange', onGestureChange, opts);
+      canvas.removeEventListener('gestureend', onGestureEnd, opts);
+    };
+  }, [canvasRef, panByScreenDelta, zoomByFactorAtPointer]);
+  const onPointerDown = useCallback((event) => {
+    if (isPlaying || !spaceDownRef.current) return;
+    event.preventDefault();
+    event.currentTarget.setPointerCapture(event.pointerId);
+    dragRef.current = { id: event.pointerId, lastX: event.clientX, lastY: event.clientY };
+  }, [isPlaying]);
+  const onPointerMove = useCallback(
+    (event) => {
+      const drag = dragRef.current;
+      if (!drag || drag.id !== event.pointerId) return;
+      const dx = event.clientX - drag.lastX;
+      const dy = event.clientY - drag.lastY;
+      drag.lastX = event.clientX;
+      drag.lastY = event.clientY;
+      panByScreenDelta(-dx, -dy);
+    },
+    [panByScreenDelta]
+  );
   const onPointerUp = useCallback((event) => {
     const drag = dragRef.current;
     if (!drag || drag.id !== event.pointerId) return;
@@ -620,7 +1100,9 @@ function usePanGesture({ canvasRef, editCameraRef, enabled }) {
     }
     dragRef.current = null;
   }, []);
-  return { onPointerDown, onPointerMove, onPointerUp };
+  const isSpacePanning = useCallback(() => spaceDownRef.current, []);
+  const isActive = useCallback(() => Boolean(dragRef.current), []);
+  return { onPointerDown, onPointerMove, onPointerUp, isSpacePanning, isActive };
 }
 function handleShiftPointerDown(drag, actor, current) {
   if (actor) {
@@ -666,6 +1148,8 @@ function handleDefaultPointerDown(drag, actor, point, current) {
     }, LONG_PRESS_MS);
   } else {
     current.onSelectActorIds([]);
+    drag.selectionBeforeMarquee = [];
+    drag.pendingMarquee = true;
     drag.longPressTimer = window.setTimeout(() => {
       if (drag.movedFar) return;
       drag.longPressFired = true;
@@ -679,7 +1163,7 @@ function finalizeMarquee(drag, current) {
   const m = current.marqueeRef.current;
   if (!m || !current.sceneData) return;
   if (m.width === 0 && m.height === 0) return;
-  const scene = makeScene(current.sceneData, behaviorClasses, current.drawings);
+  const scene = makeScene(current.sceneData, behaviorClasses, current.sprites);
   const hits = scene.actorIdsInRect(m);
   const merged = new Set(drag.selectionBeforeMarquee);
   for (const id of hits) merged.add(id);
@@ -721,6 +1205,17 @@ function useSelectionKeyboard(args) {
         current.onSelectActorIds(current.sceneData.actors.map((actor) => actor.id));
         return;
       }
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'd') {
+        if (!current.sceneData || current.selectedActorIds.length === 0) return;
+        event.preventDefault();
+        const { sceneData: next, newIds } = duplicateActors(
+          current.sceneData,
+          current.selectedActorIds
+        );
+        current.commitScene(next);
+        if (newIds.length) current.onSelectActorIds(newIds);
+        return;
+      }
       if (event.key === 'Delete' || event.key === 'Backspace') {
         if (!current.sceneData || current.selectedActorIds.length === 0) return;
         event.preventDefault();
@@ -734,14 +1229,14 @@ function useSelectionKeyboard(args) {
 }
 function useScenePlayLoop({
   sceneData,
-  drawings,
+  sprites,
   isPlaying,
   text,
   canvasRef,
   runtimeRef,
   editCameraRef,
-  selectedActorIds,
   marqueeRef,
+  selectedActorIdsRef,
 }) {
   // Spin up / tear down the play-mode runtime as the user toggles play. `text`
   // is the stable identity for `sceneData` (which is re-parsed every render);
@@ -753,35 +1248,51 @@ function useScenePlayLoop({
       return;
     }
     if (!sceneData) return;
-    runtimeRef.current = makeScene(sceneData, behaviorClasses, drawings).clone();
+    runtimeRef.current = makeScene(sceneData, behaviorClasses, sprites).clone();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [drawings, isPlaying, text, runtimeRef]);
+  }, [sprites, isPlaying, text, runtimeRef]);
   // Animation loop -- draws edit-mode previews and ticks the play-mode runtime.
   useEffect(() => {
     if (!sceneData || !canvasRef.current) return undefined;
     const canvas = canvasRef.current;
     const ctx = canvas.getContext('2d');
     if (!ctx) return undefined;
-    configureSceneCanvas(canvas, ctx);
+    const viewport = isPlaying
+      ? undefined
+      : editViewportForZoom(editCameraRef.current.zoom);
+    configureSceneCanvas(canvas, ctx, viewport);
     let raf = 0;
     let last = performance.now();
     const frame = (now) => {
       const dt = Math.min(0.033, (now - last) / 1000);
       last = now;
+      // Recompute each frame so the edit zoom (mutated on the camera ref by the
+      // pinch gesture) takes effect without restarting the loop.
+      const frameViewport = isPlaying
+        ? undefined
+        : editViewportForZoom(editCameraRef.current.zoom);
       const scene = isPlaying
         ? runtimeRef.current
-        : makeScene(sceneData, behaviorClasses, drawings);
+        : makeScene(sceneData, behaviorClasses, sprites);
       if (scene) {
+        const snap = getSnapSettings(sceneData);
         if (isPlaying) scene.update(dt);
         if (!isPlaying) scene.camera = { ...editCameraRef.current };
-        configureSceneCanvas(canvas, ctx);
+        configureSceneCanvas(canvas, ctx, frameViewport);
+        // Read selection from the ref each frame so the grid/box gating tracks
+        // the current selection without resetting this loop.
+        const editSelectedActorIds = isPlaying ? [] : selectedActorIdsRef.current ?? [];
         scene.draw(ctx, {
-          selectedActorIds: isPlaying ? [] : selectedActorIds,
+          selectedActorIds: [],
           marquee: isPlaying ? null : marqueeRef.current,
-          showGrid: false,
+          showGrid: !isPlaying && snap.enabled && editSelectedActorIds.length > 0,
+          gridSize: snap.gridSize,
           showDebugColliders: false,
+          showCropOutline: !isPlaying,
+          viewport: frameViewport,
           useCamera: true,
           editPlaceholders: !isPlaying,
+          editSelectedActorIds,
         });
       }
       raf = requestAnimationFrame(frame);
@@ -789,17 +1300,16 @@ function useScenePlayLoop({
     raf = requestAnimationFrame(frame);
     return () => cancelAnimationFrame(raf);
     // eslint-disable-next-line react-hooks/exhaustive-deps -- `text` proxies `sceneData` identity; resetting on every parse churns the loop and wipes runtime state.
-  }, [drawings, isPlaying, selectedActorIds, text, canvasRef, runtimeRef, marqueeRef]);
+  }, [sprites, isPlaying, text, canvasRef, runtimeRef, marqueeRef, selectedActorIdsRef]);
 }
-function useScenePlayKeys(runtimeRef, setIsPlaying) {
+function useScenePlayKeys(runtimeRef) {
   useEffect(() => {
     const down = (event) => {
-      if (event.key === ' ' && !isEditableTarget(event.target)) {
-        event.preventDefault();
-        setIsPlaying((current) => !current);
-        return;
-      }
       if (!runtimeRef.current) return;
+      // Space is a game input while playing — stop the browser from scrolling
+      // the panel or re-triggering a focused button (the Play/Stop toggle keeps
+      // focus after a click) instead of reaching gameplay.
+      if (event.key === ' ') event.preventDefault();
       runtimeRef.current.keys.add(event.key);
     };
     const up = (event) => {
@@ -812,7 +1322,7 @@ function useScenePlayKeys(runtimeRef, setIsPlaying) {
       window.removeEventListener('keydown', down);
       window.removeEventListener('keyup', up);
     };
-  }, [runtimeRef, setIsPlaying]);
+  }, [runtimeRef]);
 }
 function isEditableTarget(target) {
   return (
@@ -820,7 +1330,9 @@ function isEditableTarget(target) {
     !!target.closest('input, textarea, select, [contenteditable="true"]')
   );
 }
-function MultiSelectInspector({ count, onDelete, onDuplicate, onDeselectAll }) {
+// Clone/Delete moved to the on-canvas SelectionOverlay toolbar; this inspector
+// now only carries the multi-select status text and "Deselect all".
+function MultiSelectInspector({ count, onDeselectAll }) {
   return (
     <div style={{ padding: '14px 16px', display: 'flex', flexDirection: 'column', gap: 12 }}>
       <div style={{ fontSize: 13, opacity: 0.8 }}>
@@ -829,20 +1341,6 @@ function MultiSelectInspector({ count, onDelete, onDuplicate, onDeselectAll }) {
           : `${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>
@@ -976,42 +1474,25 @@ function AddBehaviorPicker({ available, onAdd }) {
   return (
     <div
       style={{
-        padding: '12px 16px',
+        height: 'var(--castle-hotbar-row-full)',
+        padding: '0 16px',
+        display: 'flex',
+        alignItems: 'center',
         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>
+      <select
+        className={styles.select}
+        value=""
+        onChange={(event) => {
+          if (event.target.value) onAdd(event.target.value);
+        }}>
+        <option value="">+ Add behavior</option>
+        {available.map((behavior) => (
+          <option key={behavior.behaviorName} value={behavior.behaviorName}>
+            {behavior.behaviorName}
+          </option>
+        ))}
+      </select>
     </div>
   );
 }