castle-web-cli 0.4.84 → 0.4.85

package/kits/physics-2d/editors/SelectionOverlay.jsx

@@ -0,0 +1,909 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { getColliderShape } from '../behaviors/Collider';
+import { cardSize, screenToCard } from '../engine/scene';
+import { cx, Icon, styles, useElementSize } from '../engine/ui';
+
+// On-canvas selection toolbar ("selection handles"). Mounts inside `.stageCard`
+// as a sibling of the `<canvas>` and mirrors the `SceneUI` overlay approach:
+//
+// - A ResizeObserver measures the canvas-sized box so a card-unit (500x700)
+//   layer can be `scale()`d onto it -- the chrome (solid box, corner dots,
+//   center pivot) lives in card units inside that scaled layer and is
+//   translated by -camera so it tracks the edit camera exactly like the canvas
+//   draw path (`ctx.translate(-camera.x, -camera.y)`).
+// - The floating buttons live in a separate, un-scaled px layer. Their
+//   positions are projected from world card units into screen px, so they stay
+//   crisp and fixed-size with fixed px gaps regardless of the responsive card
+//   scale (the alternative -- buttons inside the scaled layer -- would distort
+//   them and make gaps scale).
+//
+// Clone/Delete reuse the existing duplicate/remove scene actions; Move and
+// Rotate are pointer drags that translate / rotate every selected actor and
+// commit one history entry per gesture.
+
+const HANDLE_OFFSET = 8; // card units between the real bounds and transform handles
+const GAP_PX = 30; // px from a box edge to a floating button's center
+const ACTION_GAP_PX = 22; // px from a box edge to clone/delete buttons
+const ROTATE_STEP = 15; // degrees -- rotation snaps to this increment when grid snap is on
+const ROTATE_MAGNET = 7; // degrees -- within this band of the pre-drag angle, snap back to it exactly
+const MIN_LAYOUT_SIZE = 4; // card units; prevents inverted / zero-size Layout boxes
+// Below this on-screen box extent (px) along an axis, the mid-edge scale handle
+// for that axis would collide with the corner handles, so we drop it and keep
+// only the corners. Gated per-axis: n/s depend on the box's px width, e/w on its
+// px height (a wide, short box can keep n/s while dropping e/w, and vice versa).
+const EDGE_HANDLE_MIN_PX = 40;
+// Move/grab handle is intentionally hidden for now (its drag logic + helpers
+// stay wired below so it can be re-enabled later); flip this to render it.
+const SHOW_MOVE_HANDLE = false;
+const ARRANGE_OPTIONS = [
+  { label: 'Bring to Front', action: 'front' },
+  { label: 'Bring Forward', action: 'forward' },
+  { label: 'Send Backward', action: 'backward' },
+  { label: 'Send to Back', action: 'back' },
+];
+
+const SCALE_HANDLES = [
+  { id: 'nw', x: -1, y: -1, cursor: 'nwse-resize', corner: true },
+  { id: 'n', x: 0, y: -1, cursor: 'ns-resize' },
+  { id: 'ne', x: 1, y: -1, cursor: 'nesw-resize', corner: true },
+  { id: 'e', x: 1, y: 0, cursor: 'ew-resize' },
+  { id: 'se', x: 1, y: 1, cursor: 'nwse-resize', corner: true },
+  { id: 's', x: 0, y: 1, cursor: 'ns-resize' },
+  { id: 'sw', x: -1, y: 1, cursor: 'nesw-resize', corner: true },
+  { id: 'w', x: -1, y: 0, cursor: 'ew-resize' },
+];
+
+// `sceneData` (raw, sparse) is the clone target for every write here --
+// writes only ever add/replace the exact prop keys a gesture changed (x/y,
+// rotation, width/height), preserving whatever sparse overrides already
+// existed. `previewSceneData` (blueprint template merged with overrides) is
+// the read side for every geometry computation (bounds, colliders, drag-start
+// snapshots) -- an instance that inherits width/height from its blueprint has
+// no `Layout.width` at all in `sceneData`, so reading raw here would produce
+// NaN boxes. See engine/blueprint.js for the merge this mirrors.
+export function SelectionOverlay({
+  canvasRef,
+  editCameraRef,
+  sceneData,
+  previewSceneData,
+  sprites,
+  selectedActorIds,
+  snap,
+  onArrange,
+  onClone,
+  onDelete,
+  applyScene,
+  recordSnapshot,
+}) {
+  const rootRef = useRef(null);
+  // Track the canvas-sized overlay box so the card-unit layer scales onto it.
+  const box = useElementSize(rootRef);
+  const [camera, setCamera] = useState({ x: 0, y: 0, zoom: 1 });
+  const [groupFrameRotation, setGroupFrameRotation] = useState(null);
+  const [arrangeOpen, setArrangeOpen] = useState(false);
+  const selectionKey = [...selectedActorIds].sort().join('|');
+
+  // Follow the edit camera on a RAF tick so the toolbar pans with the canvas.
+  // setState is skipped when the camera is unchanged, so this idles cheaply.
+  useEffect(() => {
+    let raf = 0;
+    const tick = () => {
+      const cam = editCameraRef.current ?? { x: 0, y: 0, zoom: 1 };
+      const zoom = cam.zoom ?? 1;
+      setCamera((prev) =>
+        prev.x === cam.x && prev.y === cam.y && prev.zoom === zoom
+          ? prev
+          : { x: cam.x, y: cam.y, zoom }
+      );
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [editCameraRef]);
+
+  useEffect(() => {
+    setGroupFrameRotation(null);
+    setArrangeOpen(false);
+  }, [selectionKey]);
+
+  const frame = getSelectionFrame(previewSceneData, selectedActorIds, groupFrameRotation);
+
+  const onMoveDown = usePointerDragHandle((event) => {
+    const canvas = canvasRef.current;
+    if (!canvas || !sceneData || selectedActorIds.length === 0) return null;
+    const startPoint = screenToCard(canvas, event.clientX, event.clientY);
+    const starts = collectLayoutStarts(previewSceneData, selectedActorIds);
+    const state = { recorded: false, lastKey: '0,0' };
+    return {
+      onMove: (moveEvent) => {
+        const point = screenToCard(canvas, moveEvent.clientX, moveEvent.clientY);
+        const dx = snapDelta(point.x - startPoint.x, snap);
+        const dy = snapDelta(point.y - startPoint.y, snap);
+        const next = moveSelected(sceneData, previewSceneData, selectedActorIds, starts, dx, dy);
+        applyDragResult(next, sceneData, `${dx},${dy}`, state, recordSnapshot, applyScene);
+      },
+    };
+  });
+
+  const onRotateDown = usePointerDragHandle((event) => {
+    const canvas = canvasRef.current;
+    if (!canvas || !sceneData || !frame || selectedActorIds.length === 0) return null;
+    const center = { x: frame.x + frame.width / 2, y: frame.y + frame.height / 2 };
+    const startAngle = pointerAngle(canvas, editCameraRef, event, center);
+    let lastAngle = startAngle;
+    let totalDelta = 0;
+    const startFrameRotation = frame.rotation;
+    const starts = collectLayoutStarts(previewSceneData, selectedActorIds);
+    const state = { recorded: false, lastDelta: 0 };
+    return {
+      onMove: (moveEvent) => {
+        const angle = pointerAngle(canvas, editCameraRef, moveEvent, center);
+        totalDelta += shortestAngleDelta(lastAngle, angle);
+        lastAngle = angle;
+        const delta = snapRotationDelta(totalDelta, snap?.enabled ?? true);
+        // Key the commit on the snapped delta itself, not on a diff against the
+        // pointer-down snapshot. `onMove` closes over the `sceneData` captured at
+        // drag-start, where the actor still sits at its original angle, so when
+        // the magnet pulls `delta` back to 0 `rotateSelected` returns that
+        // unchanged snapshot; an identity guard would treat that as a no-op and
+        // skip it, stranding the actor on the last grid step -- the reason
+        // returning to the original angle felt impossible. Re-applying whenever
+        // the delta changes lets delta 0 actually restore the start angle.
+        // (Scale/move share this contract via `applyDragResult`'s `key` param.)
+        if (delta === state.lastDelta) return;
+        state.lastDelta = delta;
+        setGroupFrameRotation(normalizeAngle(startFrameRotation + delta));
+        const next = rotateSelected(sceneData, previewSceneData, selectedActorIds, starts, center, delta);
+        if (!state.recorded) {
+          recordSnapshot();
+          state.recorded = true;
+        }
+        applyScene(next);
+      },
+    };
+  });
+
+  const onScaleDown = usePointerDragHandle((event) => {
+    const handleId = event.currentTarget.dataset.handle;
+    const handle = SCALE_HANDLES.find((candidate) => candidate.id === handleId);
+    const canvas = canvasRef.current;
+    if (!handle || !canvas || !sceneData || !frame || selectedActorIds.length === 0) return null;
+    const startTransform = makeBoundsTransform(frame, frame.rotation);
+    const startPointer = pointerLocal(canvas, editCameraRef, event, startTransform);
+    const starts = collectLayoutStarts(previewSceneData, selectedActorIds);
+    const state = { recorded: false, lastKey: '0,0,0' };
+    return {
+      onMove: (moveEvent) => {
+        const point = pointerLocal(canvas, editCameraRef, moveEvent, startTransform);
+        const dx = snapDelta(point.x - startPointer.x, snap);
+        const dy = snapDelta(point.y - startPointer.y, snap);
+        const nextBounds = scaleBoundsFromHandle(
+          startTransform.localBounds,
+          handle,
+          dx,
+          dy,
+          moveEvent.shiftKey
+        );
+        const next = scaleSelected(sceneData, previewSceneData, selectedActorIds, starts, startTransform, nextBounds);
+        // Include shift (uniform) in the key so toggling it without moving still re-applies.
+        applyDragResult(next, sceneData, `${dx},${dy},${moveEvent.shiftKey ? 1 : 0}`, state, recordSnapshot, applyScene);
+      },
+    };
+  });
+
+  if (!frame || box.width === 0 || box.height === 0) {
+    // Keep the root mounted so the ResizeObserver always has a node to measure.
+    return <div ref={rootRef} className={styles.selOverlayRoot} aria-hidden="true" />;
+  }
+
+  const geometry = getOverlayGeometry(frame, box, camera);
+  const colliderFrames = getSelectedColliderFrames(previewSceneData, selectedActorIds, sprites);
+
+  return (
+    <div ref={rootRef} className={styles.selOverlayRoot}>
+      <div
+        className={styles.selChromeLayer}
+        style={{
+          width: cardSize.width,
+          height: cardSize.height,
+          transform: `scale(${geometry.sx}, ${geometry.sy})`,
+        }}>
+        <div
+          className={styles.selChromeWorld}
+          style={{ transform: `translate(${-geometry.camX}px, ${-geometry.camY}px)` }}>
+          {colliderFrames.map((collider) => (
+            <div
+              key={collider.actorId}
+              className={cx(
+                styles.selColliderBox,
+                collider.isTrigger && styles.selColliderPickup
+              )}
+              style={{
+                left: collider.x,
+                top: collider.y,
+                width: collider.width,
+                height: collider.height,
+                borderRadius: collider.shape === 'circle' ? '50%' : undefined,
+                transformOrigin: `${collider.originX}px ${collider.originY}px`,
+                transform: `rotate(${collider.rotation}deg)`,
+              }}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Buttons stay screen-upright (never rotated) so their glyphs are always
+          readable. The rotate handle orbits via its anchor; clone/delete flip
+          above/below to stay clear of it. */}
+      <div className={styles.selButtonLayer}>
+        {/* Solid bounding box, connector stem, and center pivot render here
+            (un-scaled px layer) rather than the chrome layer, so their stroke
+            width and pivot size stay constant with zoom. Their px dimensions
+            are projected from the box's screen extents, so the box still traces
+            the actual bounds. The stem is anchored at the box's rotated
+            right-center edge and rotates about that point out to the handle. */}
+        <div
+          className={styles.selStem}
+          style={{
+            left: geometry.stemStart.x,
+            top: geometry.stemStart.y,
+            width: geometry.stemLengthPx,
+            transform: `translateY(-50%) rotate(${geometry.rotation}deg)`,
+          }}
+        />
+        <div
+          className={styles.selBox}
+          style={{
+            left: geometry.centerX,
+            top: geometry.centerY,
+            width: geometry.boxWidthPx,
+            height: geometry.boxHeightPx,
+            transform: `translate(-50%, -50%) rotate(${geometry.rotation}deg)`,
+          }}
+        />
+        <div className={styles.selPivot} style={{ left: geometry.centerX, top: geometry.centerY }} />
+        {/* Scale handles live here (un-scaled px layer), not in the chrome layer:
+            projecting them to screen px keeps them crisp and a constant size at
+            any zoom, instead of being rasterized small then stretched by the
+            layer's `scale()`. Each is rotated so edge handles hug the box side. */}
+        {geometry.scaleHandles.map((handle) => (
+          <div
+            key={handle.id}
+            role="button"
+            aria-label={`Scale ${handle.id}`}
+            title={`Scale ${handle.id}`}
+            className={cx(
+              styles.selScaleHandle,
+              handle.corner ? styles.selScaleCorner : styles.selScaleEdge
+            )}
+            data-handle={handle.id}
+            style={{
+              left: handle.x,
+              top: handle.y,
+              cursor: handle.cursor,
+              transform: `translate(-50%, -50%) rotate(${geometry.rotation}deg)`,
+            }}
+            onPointerDown={(event) => {
+              event.stopPropagation();
+              onScaleDown(event);
+            }}
+          />
+        ))}
+        <Floating x={geometry.cloneAnchor.x} y={geometry.cloneAnchor.y}>
+          <div className={styles.selBtnGroup}>
+            <div className={styles.selArrangeWrap}>
+              <OverlayButton
+                label="Arrange"
+                icon="layer-group"
+                disabled={!onArrange}
+                onActivate={() => setArrangeOpen((open) => !open)}
+              />
+              {arrangeOpen ? (
+                <div
+                  className={styles.selArrangeMenu}
+                  role="menu"
+                  aria-label="Arrange"
+                  onPointerDown={(event) => event.stopPropagation()}
+                  onClick={(event) => event.stopPropagation()}>
+                  {ARRANGE_OPTIONS.map((option) => (
+                    <button
+                      key={option.action}
+                      type="button"
+                      role="menuitem"
+                      className={styles.selArrangeItem}
+                      onClick={() => {
+                        onArrange?.(option.action);
+                        setArrangeOpen(false);
+                      }}>
+                      {option.label}
+                    </button>
+                  ))}
+                </div>
+              ) : null}
+            </div>
+            <OverlayButton label="Clone" icon="clone" disabled={!onClone} onActivate={onClone} />
+            <OverlayButton label="Delete" icon="trash" disabled={!onDelete} onActivate={onDelete} />
+          </div>
+        </Floating>
+        <Floating x={geometry.rotateAnchor.x} y={geometry.rotateAnchor.y}>
+          <OverlayButton label="Rotate" icon="rotate" extraClass={styles.selBtnRotate} onPointerDown={onRotateDown} />
+        </Floating>
+        {/* Move/grab handle hidden for now; drag wiring (onMoveDown) preserved. */}
+        {SHOW_MOVE_HANDLE && (
+          <Floating x={geometry.centerX} y={geometry.centerY + geometry.halfH + GAP_PX}>
+            <OverlayButton label="Move" icon="move" extraClass={styles.selBtnGrab} onPointerDown={onMoveDown} />
+          </Floating>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// `sceneData` here is always the MERGED preview scene (see the note on
+// `SelectionOverlay` above) -- every Layout read in this file is.
+function getSelectionFrame(sceneData, actorIds, preferredRotation = null) {
+  if (!sceneData || !actorIds || actorIds.length === 0) return null;
+  const wanted = new Set(actorIds);
+  const layouts = sceneData.actors
+    .filter((actor) => wanted.has(actor.id))
+    .map((actor) => actor.components.Layout)
+    .filter(Boolean);
+  if (layouts.length === 0) return null;
+  const sharedRotation = getSharedRotation(layouts);
+  const rotation = sharedRotation ?? (layouts.length > 1 ? preferredRotation : null) ?? 0;
+  return getOrientedLayoutBounds(layouts, rotation);
+}
+
+function getOverlayGeometry(frame, box, camera) {
+  // Fold the edit zoom into the card-unit -> screen-px scale. The canvas draws
+  // the card at (box / card) * zoom px-per-unit (the effective viewport extent
+  // and origin both scale by 1/zoom), and the chrome layer's `transform-origin:
+  // 0 0` projection from world (0,0) matches once sx/sy carry the same zoom.
+  const zoom = camera.zoom ?? 1;
+  const sx = (box.width / cardSize.width) * zoom;
+  const sy = (box.height / cardSize.height) * zoom;
+  const camX = Math.round(camera.x);
+  const camY = Math.round(camera.y);
+  const rotation = frame.rotation;
+  const centerCardX = frame.x + frame.width / 2;
+  const centerCardY = frame.y + frame.height / 2;
+  const centerX = (centerCardX - camX) * sx;
+  const centerY = (centerCardY - camY) * sy;
+  const halfW = (frame.width / 2 + HANDLE_OFFSET) * sx;
+  const halfH = (frame.height / 2 + HANDLE_OFFSET) * sy;
+  const rotateAnchor = getRotateAnchor({ centerX, centerY, halfW, rotation });
+  // Stem starts at the box's rotated right-center edge and runs out to the
+  // rotate handle. Projected to screen px (like the box + handles) so its
+  // thickness stays constant with zoom instead of scaling with the chrome layer.
+  const rad = (rotation * Math.PI) / 180;
+  const halfWpx = (frame.width / 2) * sx;
+  const stemStart = {
+    x: centerX + halfWpx * Math.cos(rad),
+    y: centerY + halfWpx * Math.sin(rad),
+  };
+  return {
+    sx,
+    sy,
+    camX,
+    camY,
+    rotation,
+    centerX,
+    centerY,
+    halfH,
+    rotateAnchor,
+    cloneAnchor: getActionAnchor({ centerX, centerY, halfH, rotateAnchor }),
+    stemStart,
+    stemLengthPx: Math.hypot(rotateAnchor.x - stemStart.x, rotateAnchor.y - stemStart.y),
+    boxWidthPx: frame.width * sx,
+    boxHeightPx: frame.height * sy,
+    scaleHandles: getScaleHandleAnchors({
+      centerX,
+      centerY,
+      halfWpx: (frame.width / 2) * sx,
+      halfHpx: (frame.height / 2) * sy,
+      rotation,
+    }),
+  };
+}
+
+// Project the scale handles from the box's rotated corners/edges into screen px
+// so they can render in the un-scaled button layer at a constant size. Corners
+// are always shown; mid-edge handles are dropped once the box is too small along
+// their axis (see EDGE_HANDLE_MIN_PX) so they don't overlap the corners.
+function getScaleHandleAnchors({ centerX, centerY, halfWpx, halfHpx, rotation }) {
+  const rad = (rotation * Math.PI) / 180;
+  const cosR = Math.cos(rad);
+  const sinR = Math.sin(rad);
+  const boxWidthPx = halfWpx * 2;
+  const boxHeightPx = halfHpx * 2;
+  return SCALE_HANDLES.filter((handle) => {
+    if (handle.corner) return true;
+    // n/s run along the box's width; e/w run along its height.
+    return handle.x === 0
+      ? boxWidthPx >= EDGE_HANDLE_MIN_PX
+      : boxHeightPx >= EDGE_HANDLE_MIN_PX;
+  }).map((handle) => {
+    const lx = handle.x * halfWpx;
+    const ly = handle.y * halfHpx;
+    return {
+      ...handle,
+      x: centerX + lx * cosR - ly * sinR,
+      y: centerY + lx * sinR + ly * cosR,
+    };
+  });
+}
+
+function getRotateAnchor({ centerX, centerY, halfW, rotation }) {
+  const rad = (rotation * Math.PI) / 180;
+  const cosR = Math.cos(rad);
+  const sinR = Math.sin(rad);
+  const lx = halfW + GAP_PX;
+  return {
+    x: centerX + lx * cosR,
+    y: centerY + lx * sinR,
+  };
+}
+
+function getActionAnchor({ centerX, centerY, halfH, rotateAnchor }) {
+  const topY = centerY - halfH - ACTION_GAP_PX;
+  const bottomY = centerY + halfH + ACTION_GAP_PX;
+  const overlapsTop =
+    Math.abs(rotateAnchor.x - centerX) < GAP_PX * 1.9 &&
+    Math.abs(rotateAnchor.y - topY) < GAP_PX * 1.4;
+  return {
+    x: centerX,
+    y: overlapsTop ? bottomY : topY,
+  };
+}
+
+function getSelectedColliderFrames(sceneData, actorIds, sprites) {
+  if (!sceneData || !actorIds || actorIds.length === 0) return [];
+  const wanted = new Set(actorIds);
+  return sceneData.actors
+    .filter((actor) => wanted.has(actor.id))
+    .map((actor) => {
+      const layout = actor.components.Layout;
+      const collider = actor.components.Collider;
+      const geom = getColliderShape(actor, sprites);
+      if (!layout || !collider || !geom) return null;
+      // For a circle we render a radius-sized square with border-radius; for a
+      // box, the rect itself. Both come from the shared geometry so the preview
+      // matches the physics body exactly (shape, radius, offset, auto/manual).
+      const isCircle = geom.shape === 'circle';
+      const x = isCircle ? geom.cx - geom.radius : geom.x;
+      const y = isCircle ? geom.cy - geom.radius : geom.y;
+      const width = isCircle ? geom.radius * 2 : geom.width;
+      const height = isCircle ? geom.radius * 2 : geom.height;
+      return {
+        actorId: actor.id,
+        shape: geom.shape,
+        isTrigger: Boolean(collider.isTrigger) || collider.kind === 'pickup',
+        x,
+        y,
+        width,
+        height,
+        rotation: layout.rotation ?? 0,
+        originX: layout.x + layout.width / 2 - x,
+        originY: layout.y + layout.height / 2 - y,
+      };
+    })
+    .filter(Boolean);
+}
+
+function getSharedRotation(layouts) {
+  const first = normalizeAngle(layouts[0].rotation ?? 0);
+  return layouts.every((layout) => normalizeAngle(layout.rotation ?? 0) === first) ? first : null;
+}
+
+function getOrientedLayoutBounds(layouts, rotation) {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const layout of layouts) {
+    for (const corner of getLayoutWorldCorners(layout)) {
+      const local = rotateAroundOrigin(corner, -rotation);
+      minX = Math.min(minX, local.x);
+      minY = Math.min(minY, local.y);
+      maxX = Math.max(maxX, local.x);
+      maxY = Math.max(maxY, local.y);
+    }
+  }
+  const width = maxX - minX;
+  const height = maxY - minY;
+  const center = rotateAroundOrigin({ x: minX + width / 2, y: minY + height / 2 }, rotation);
+  return {
+    x: center.x - width / 2,
+    y: center.y - height / 2,
+    width,
+    height,
+    rotation,
+  };
+}
+
+function getLayoutWorldCorners(layout) {
+  const center = {
+    x: layout.x + layout.width / 2,
+    y: layout.y + layout.height / 2,
+  };
+  const halfW = layout.width / 2;
+  const halfH = layout.height / 2;
+  const rotation = layout.rotation ?? 0;
+  return [
+    { x: -halfW, y: -halfH },
+    { x: halfW, y: -halfH },
+    { x: halfW, y: halfH },
+    { x: -halfW, y: halfH },
+  ].map((corner) => {
+    const rotated = rotateAroundOrigin(corner, rotation);
+    return {
+      x: center.x + rotated.x,
+      y: center.y + rotated.y,
+    };
+  });
+}
+
+function rotateAroundOrigin(point, deg) {
+  const rad = (deg * Math.PI) / 180;
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  return {
+    x: point.x * cos - point.y * sin,
+    y: point.x * sin + point.y * cos,
+  };
+}
+
+function Floating({ x, y, children }) {
+  return (
+    <div className={styles.selBtnWrap} style={{ left: x, top: y }}>
+      {children}
+    </div>
+  );
+}
+
+function OverlayButton({ label, icon, onActivate, onPointerDown, extraClass, disabled = false }) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      disabled={disabled}
+      className={cx(styles.selBtn, extraClass)}
+      onPointerDown={(event) => {
+        event.stopPropagation();
+        if (disabled) return;
+        onPointerDown?.(event);
+      }}
+      onClick={(event) => {
+        event.stopPropagation();
+        if (disabled) return;
+        onActivate?.();
+      }}>
+      <Icon name={icon} />
+    </button>
+  );
+}
+
+// Shared pointer-drag scaffolding. `begin(downEvent)` runs on pointerdown and
+// returns `{ onMove }` (or null to ignore). Window listeners + pointer capture
+// are wired here so the move/rotate gestures only describe their own math.
+function usePointerDragHandle(begin) {
+  const beginRef = useRef(begin);
+  beginRef.current = begin;
+  return useCallback((event) => {
+    const handlers = beginRef.current(event);
+    if (!handlers) return;
+    event.preventDefault();
+    try {
+      event.currentTarget.setPointerCapture(event.pointerId);
+    } catch {
+      // Pointer capture may be unavailable; window listeners still drive it.
+    }
+    const pointerId = event.pointerId;
+    const move = (moveEvent) => {
+      if (moveEvent.pointerId !== pointerId) return;
+      handlers.onMove(moveEvent);
+    };
+    const end = (endEvent) => {
+      if (endEvent.pointerId !== pointerId) return;
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', end);
+      window.removeEventListener('pointercancel', end);
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', end);
+    window.addEventListener('pointercancel', end);
+  }, []);
+}
+
+// Gate the commit on the gesture's snapped input (`key`), not on
+// `next === sceneData`. During a drag the handlers compute `next` relative to
+// the pointer-down `sceneData`, so returning the handle to its start value
+// makes `next` identity-equal to that snapshot -- an identity guard would treat
+// that as a no-op and skip `applyScene`, stranding the actor on the last grid
+// step (the reason handles couldn't be dragged back to their origin). Keying on
+// the snapped input re-applies whenever it changes, including back to the start
+// key, so the origin is reachable. The identity check now only decides whether
+// to record the undo snapshot, so a pure no-op drag never touches history. This
+// mirrors the rotate handle's delta-keyed commit.
+function applyDragResult(next, sceneData, key, state, recordSnapshot, applyScene) {
+  if (key === state.lastKey) return;
+  state.lastKey = key;
+  if (next !== sceneData && !state.recorded) {
+    recordSnapshot();
+    state.recorded = true;
+  }
+  applyScene(next);
+}
+
+function collectLayoutStarts(sceneData, actorIds) {
+  const starts = {};
+  const wanted = new Set(actorIds);
+  for (const actor of sceneData.actors) {
+    if (!wanted.has(actor.id)) continue;
+    const layout = actor.components.Layout;
+    if (layout) {
+      starts[actor.id] = {
+        x: layout.x,
+        y: layout.y,
+        width: layout.width,
+        height: layout.height,
+        rotation: layout.rotation ?? 0,
+      };
+    }
+  }
+  return starts;
+}
+
+function snapDelta(delta, snap) {
+  if (!snap || !snap.enabled) return delta;
+  return Math.round(delta / snap.gridSize) * snap.gridSize;
+}
+
+// Clone the RAW `sceneData` (the sparse write target) and patch the Layout
+// override of every selected actor, but read each actor's CURRENT layout
+// from `previewSceneData` (blueprint-merged) so `patch` sees real width/
+// height/rotation even when an instance inherits them and has no Layout
+// override of its own yet. `patch(layout, start)` returns the props to merge
+// into that actor's Layout OVERRIDE (not the merged layout), or null to leave
+// it untouched -- this is exactly the sparse-override write path (drag =
+// x/y, always non-inherited; scale additionally promotes width/height to
+// instance overrides). Returns the original `sceneData` when nothing changed
+// so callers can skip a no-op commit.
+function updateSelectedLayouts(sceneData, previewSceneData, actorIds, starts, patch) {
+  const wanted = new Set(actorIds);
+  const next = structuredClone(sceneData);
+  let changed = false;
+  for (const actor of next.actors) {
+    if (!wanted.has(actor.id)) continue;
+    const start = starts[actor.id];
+    const previewLayout = previewSceneData.actors.find((candidate) => candidate.id === actor.id)
+      ?.components?.Layout;
+    if (!start || !previewLayout) continue;
+    const props = patch(previewLayout, start);
+    if (!props) continue;
+    actor.components ??= {};
+    actor.components.Layout = { ...(actor.components.Layout ?? {}), ...props };
+    changed = true;
+  }
+  return changed ? next : sceneData;
+}
+
+function moveSelected(sceneData, previewSceneData, actorIds, starts, dx, dy) {
+  return updateSelectedLayouts(sceneData, previewSceneData, actorIds, starts, (layout, start) => {
+    const x = Math.round(start.x + dx);
+    const y = Math.round(start.y + dy);
+    return layout.x === x && layout.y === y ? null : { x, y };
+  });
+}
+
+// Common-pivot rotation: actor centers orbit the selection pivot while each
+// actor also spins by the same delta, matching a temporary group transform.
+function rotateSelected(sceneData, previewSceneData, actorIds, starts, pivot, deltaDeg) {
+  return updateSelectedLayouts(sceneData, previewSceneData, actorIds, starts, (layout, start) => {
+    const center = {
+      x: start.x + start.width / 2,
+      y: start.y + start.height / 2,
+    };
+    const nextCenter = rotatePoint(center, pivot, deltaDeg);
+    const x = Math.round(nextCenter.x - start.width / 2);
+    const y = Math.round(nextCenter.y - start.height / 2);
+    const rotation = normalizeAngle((start.rotation ?? 0) + deltaDeg);
+    if (layout.x === x && layout.y === y && (layout.rotation ?? 0) === rotation) return null;
+    return { x, y, rotation };
+  });
+}
+
+function scaleSelected(sceneData, previewSceneData, actorIds, starts, startTransform, nextLocalBounds) {
+  const startBounds = startTransform.localBounds;
+  const scaleX = startBounds.width === 0 ? 1 : nextLocalBounds.width / startBounds.width;
+  const scaleY = startBounds.height === 0 ? 1 : nextLocalBounds.height / startBounds.height;
+  return updateSelectedLayouts(sceneData, previewSceneData, actorIds, starts, (layout, start) => {
+    const startCenter = {
+      x: start.x + start.width / 2,
+      y: start.y + start.height / 2,
+    };
+    const localCenter = worldToLocal(startCenter, startTransform);
+    const nextLocalCenter = {
+      x: nextLocalBounds.left + (localCenter.x - startBounds.left) * scaleX,
+      y: nextLocalBounds.top + (localCenter.y - startBounds.top) * scaleY,
+    };
+    const nextCenter = localToWorld(nextLocalCenter, startTransform);
+    const width = Math.max(MIN_LAYOUT_SIZE, Math.round(start.width * scaleX));
+    const height = Math.max(MIN_LAYOUT_SIZE, Math.round(start.height * scaleY));
+    const x = Math.round(nextCenter.x - width / 2);
+    const y = Math.round(nextCenter.y - height / 2);
+    if (layout.x === x && layout.y === y && layout.width === width && layout.height === height) {
+      return null;
+    }
+    return { x, y, width, height };
+  });
+}
+
+function scaleBoundsFromHandle(bounds, handle, dx, dy, uniform = false) {
+  if (uniform) return uniformScaleBoundsFromHandle(bounds, handle, dx, dy);
+  let left = bounds.left;
+  let right = bounds.right;
+  let top = bounds.top;
+  let bottom = bounds.bottom;
+  if (handle.x < 0) left = clampMax(bounds.left + dx, right - MIN_LAYOUT_SIZE);
+  else if (handle.x > 0) right = clampMin(bounds.right + dx, left + MIN_LAYOUT_SIZE);
+  if (handle.y < 0) top = clampMax(bounds.top + dy, bottom - MIN_LAYOUT_SIZE);
+  else if (handle.y > 0) bottom = clampMin(bounds.bottom + dy, top + MIN_LAYOUT_SIZE);
+  return {
+    left,
+    right,
+    top,
+    bottom,
+    width: right - left,
+    height: bottom - top,
+  };
+}
+
+function uniformScaleBoundsFromHandle(bounds, handle, dx, dy) {
+  const raw = scaleBoundsFromHandle(bounds, handle, dx, dy);
+  const scale = uniformScaleForHandle(bounds, handle, raw);
+  return boundsFromUniformScale(bounds, handle, scale);
+}
+
+function uniformScaleForHandle(bounds, handle, raw) {
+  const scaleX = raw.width / bounds.width;
+  const scaleY = raw.height / bounds.height;
+  const minScale = Math.max(MIN_LAYOUT_SIZE / bounds.width, MIN_LAYOUT_SIZE / bounds.height);
+  if (handle.x === 0) return Math.max(scaleY, minScale);
+  if (handle.y === 0) return Math.max(scaleX, minScale);
+  const xDelta = Math.abs(scaleX - 1);
+  const yDelta = Math.abs(scaleY - 1);
+  return Math.max(xDelta >= yDelta ? scaleX : scaleY, minScale);
+}
+
+function boundsFromUniformScale(bounds, handle, scale) {
+  const width = bounds.width * scale;
+  const height = bounds.height * scale;
+  const centerX = (bounds.left + bounds.right) / 2;
+  const centerY = (bounds.top + bounds.bottom) / 2;
+  let left = centerX - width / 2;
+  let right = centerX + width / 2;
+  let top = centerY - height / 2;
+  let bottom = centerY + height / 2;
+  if (handle.x < 0) left = bounds.right - width;
+  else if (handle.x > 0) right = bounds.left + width;
+  if (handle.x !== 0) {
+    if (handle.x < 0) right = bounds.right;
+    else left = bounds.left;
+  }
+  if (handle.y < 0) top = bounds.bottom - height;
+  else if (handle.y > 0) bottom = bounds.top + height;
+  if (handle.y !== 0) {
+    if (handle.y < 0) bottom = bounds.bottom;
+    else top = bounds.top;
+  }
+  return {
+    left,
+    right,
+    top,
+    bottom,
+    width: right - left,
+    height: bottom - top,
+  };
+}
+
+function makeBoundsTransform(bounds, rotation) {
+  const pivot = {
+    x: bounds.x + bounds.width / 2,
+    y: bounds.y + bounds.height / 2,
+  };
+  const left = -bounds.width / 2;
+  const right = bounds.width / 2;
+  const top = -bounds.height / 2;
+  const bottom = bounds.height / 2;
+  return {
+    pivot,
+    rotation,
+    localBounds: {
+      left,
+      right,
+      top,
+      bottom,
+      width: bounds.width,
+      height: bounds.height,
+    },
+  };
+}
+
+function pointerLocal(canvas, editCameraRef, event, transform) {
+  const raw = screenToCard(canvas, event.clientX, event.clientY);
+  const cam = editCameraRef.current ?? { x: 0, y: 0 };
+  return worldToLocal({ x: raw.x + cam.x, y: raw.y + cam.y }, transform);
+}
+
+function worldToLocal(point, transform) {
+  const dx = point.x - transform.pivot.x;
+  const dy = point.y - transform.pivot.y;
+  const rad = (-transform.rotation * Math.PI) / 180;
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  return {
+    x: dx * cos - dy * sin,
+    y: dx * sin + dy * cos,
+  };
+}
+
+function localToWorld(point, transform) {
+  const rad = (transform.rotation * Math.PI) / 180;
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  return {
+    x: transform.pivot.x + point.x * cos - point.y * sin,
+    y: transform.pivot.y + point.x * sin + point.y * cos,
+  };
+}
+
+function rotatePoint(point, pivot, deltaDeg) {
+  const rad = (deltaDeg * Math.PI) / 180;
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  const dx = point.x - pivot.x;
+  const dy = point.y - pivot.y;
+  return {
+    x: pivot.x + dx * cos - dy * sin,
+    y: pivot.y + dx * sin + dy * cos,
+  };
+}
+
+function clampMin(value, min) {
+  return value < min ? min : value;
+}
+
+function clampMax(value, max) {
+  return value > max ? max : value;
+}
+
+function normalizeAngle(deg) {
+  const wrapped = ((deg % 360) + 360) % 360;
+  return Math.round(wrapped * 100) / 100;
+}
+
+function shortestAngleDelta(from, to) {
+  return ((((to - from) % 360) + 540) % 360) - 180;
+}
+
+// Snap a raw rotation delta (degrees from the angle at drag-start) to a value.
+// The original (pre-drag) angle lives at delta 0, so a magnet band there lets
+// the actor always return to exactly where it began -- independent of the
+// 15-degree grid, which would otherwise skip an off-grid original. Outside the
+// magnet, snap to the grid when enabled, else rotate freely (whole degrees).
+function snapRotationDelta(delta, snapEnabled) {
+  if (Math.abs(delta) <= ROTATE_MAGNET) return 0;
+  if (!snapEnabled) return Math.round(delta);
+  return Math.round(delta / ROTATE_STEP) * ROTATE_STEP;
+}
+
+// Angle (degrees) of the pointer around `center`, in world card units.
+function pointerAngle(canvas, editCameraRef, event, center) {
+  const raw = screenToCard(canvas, event.clientX, event.clientY);
+  const cam = editCameraRef.current ?? { x: 0, y: 0 };
+  const wx = raw.x + cam.x;
+  const wy = raw.y + cam.y;
+  return (Math.atan2(wy - center.y, wx - center.x) * 180) / Math.PI;
+}