jspsych-tangram 0.0.1

package/src/core/components/board/useDragController.ts

@@ -0,0 +1,1051 @@
+import React from "react";
+import { BaseGameController } from "@/core/engine/state/BaseGameController";
+import type { CircleLayout } from "@/core/domain/layout";
+import type { Blueprint } from "@/core/domain/types";
+import { sectorAtPoint } from "@/core/domain/layout";
+import { 
+  boundsOfBlueprint, 
+  computeSupportOffsets, 
+  clampTopLeftBySupport, 
+  polysOverlap, 
+  piecePolysAt 
+} from "@/core/engine/geometry";
+import { nearestNodeSnap, polyFullyInside } from "@/core/engine/collision/grid-snapping";
+import { checkFaceToFaceAttachment, wouldRemovalDisconnectSector } from "@/core/engine/validation/face-to-face";
+import { blueprintLocalFromWorld } from "./utils";
+import type { AnchorDots } from "./useAnchorGrid";
+import type { PieceData } from "./usePieceState";
+import { CONFIG } from "@/core/config/config";
+
+interface DragState {
+  id: string;
+  dx: number;
+  dy: number;
+  tlx: number;
+  tly: number;
+  aabb: { width: number; height: number };
+  minx: number;
+  miny: number;
+  support: { x: number; y: number }[];
+  fromIcon?: boolean;
+  validSnap?: boolean;
+  prevValidSnap?: boolean;
+  raf?: number | null;
+  originalPos?: { x: number; y: number; sectorId: string | undefined } | undefined; // For prep mode: return to original position when invalid
+  pointerAnchor?: { x: number; y: number } | null;
+  pointerAnchorId?: string | null;
+  pointerAnchorSectorId?: string | undefined;
+  snapAnchor?: { x: number; y: number } | null;
+  snapAnchorId?: string | null;
+  snapAnchorSectorId?: string | undefined;
+  snapAnchorDist?: number | null;
+  overlaps?: boolean;
+  maxExceeded?: boolean;
+}
+
+/**
+ * Return interface for useDragController hook
+ * 
+ * Provides complete drag interaction functionality for both click and drag input modes.
+ * Handles piece spawning, dragging, collision detection, snapping, and placement validation.
+ */
+export interface DragControllerHook {
+  // State
+  /** ID of currently dragging piece (null if none) */
+  draggingId: string | null;
+  
+  /** True if current drag position is invalid (for visual feedback) */
+  dragInvalid: boolean;
+  
+  /** ID of piece that is locked due to connectivity constraints (for visual feedback) */
+  lockedPieceId: string | null;
+  
+  /** Ref to SVG element for coordinate transformation and pointer capture */
+  svgRef: React.RefObject<SVGSVGElement>;
+  
+  // Handlers
+  /** 
+   * Handler for piece pointer down events (both click and drag modes)
+   * @param e - Pointer event from SVG path or group element
+   * @param p - Piece data including position and blueprint information
+   */
+  onPiecePointerDown: (
+    e: React.PointerEvent<SVGPathElement | SVGGElement>,
+    p: { id: string; x: number; y: number; blueprintId: string; sectorId?: string }
+  ) => void;
+  
+  /** 
+   * Handler for blueprint icon pointer down events (spawning new pieces)
+   * @param e - Pointer event from blueprint icon
+   * @param bp - Blueprint definition for the new piece
+   * @param bpGeom - Geometry information for the blueprint icon
+   */
+  onBlueprintPointerDown: (
+    e: React.PointerEvent,
+    bp: Blueprint,
+    bpGeom: { bx: number; by: number; cx: number; cy: number }
+  ) => void;
+  
+  /** 
+   * Handler for pointer move events during drag operations
+   * @param e - Pointer event from SVG root element
+   */
+  onPointerMove: (e: React.PointerEvent<SVGSVGElement>) => void;
+  
+  /** Handler for pointer up events (completing drag operations) */
+  onPointerUp: () => void;
+  
+  /** 
+   * Factory function for piece element refs (for direct DOM manipulation)
+   * @param id - Piece ID
+   * @returns Ref callback for SVG group element
+   */
+  setPieceRef: (id: string) => (el: SVGGElement | null) => void;
+  
+  // Click controller integration
+  /** 
+   * Setter for dragging ID (used by click controller for carry state)
+   * @param id - Piece ID or null to clear
+   */
+  setDraggingId: (id: string | null) => void;
+  
+  // TODO: Remove this once click mode is extracted - temporary for compatibility
+  /** Internal drag state ref (temporary for click controller integration) */
+  dragRef: React.RefObject<DragState | null>;
+}
+
+/**
+ * Hook for managing drag interactions with RAF optimization and collision detection
+ * 
+ * This is the most complex hook in the system, handling all aspects of piece interaction
+ * for both click and drag input modes. It manages piece spawning, dragging, collision
+ * detection, grid snapping, placement validation, and visual feedback.
+ * 
+ * ## Key Features
+ * - **Dual input mode support**: Handles both click and drag interaction patterns
+ * - **RAF-optimized rendering**: Uses requestAnimationFrame for smooth drag performance
+ * - **Collision detection**: Real-time overlap checking with existing pieces
+ * - **Grid snapping**: Automatic snapping to anchor points with validation
+ * - **Placement validation**: Comprehensive validation for workspace/silhouette modes
+ * - **Visual feedback**: Real-time visual indicators for valid/invalid placement
+ * 
+ * ## Input Mode Behavior
+ * - **Click mode**: First click starts "carry" state, second click places/cancels
+ * - **Drag mode**: Traditional drag-and-drop with immediate visual feedback
+ * 
+ * ## Validation Rules
+ * - **Workspace mode**: Pieces must not overlap, any grid position valid
+ * - **Silhouette mode**: Pieces must be within silhouette mask, on valid anchors, no overlap
+ * - **Completed sectors**: No placement allowed, pieces deleted if dropped
+ * 
+ * @param controller - BaseGameController for state management
+ * @param layout - Computed CircleLayout for sector geometry
+ * @param pieces - Current piece data from usePieceState
+ * @param pieceById - Lookup function for piece data
+ * @param anchorDots - Anchor grid data from useAnchorGrid
+ * @param placedSilBySector - Silhouette polygons for containment checking
+ * @param isSectorLocked - Function to check if sector is completed
+ * @param maybeCompleteSector - Callback to check sector completion after placement
+ * @param force - Force React re-render function
+ * @param clickController - Optional click controller integration
+ * @returns Hook interface with drag state and event handlers
+ * 
+ * @example
+ * ```typescript
+ * const dragController = useDragController(
+ *   controller, layout, pieces, pieceById, anchorDots,
+ *   placedSilBySector, isSectorLocked, maybeCompleteSector, force
+ * );
+ * 
+ * // Usage in JSX:
+ * <svg ref={dragController.svgRef} onPointerMove={dragController.onPointerMove}>
+ *   <g onPointerDown={(e) => dragController.onPiecePointerDown(e, piece)}>
+ *     <path />  
+ *   </g>
+ * </svg>
+ * ```
+ */
+export function useDragController(
+  controller: BaseGameController,
+  layout: CircleLayout,
+  pieces: PieceData[],
+  pieceById: (id: string | null) => PieceData | null,
+  anchorDots: AnchorDots[],
+  placedSilBySector: Map<string, any[]>,
+  isSectorLocked: (id: string) => boolean,
+  maybeCompleteSector: (secId: string) => boolean,
+  force: () => void,
+  // Click controller integration
+  clickController?: {
+    setSelectedPiece: (id: string | null) => void;
+    setPendingBp: (id: string | null) => void;
+  },
+  // Interaction tracking
+  tracker?: {
+    recordPickup: (
+      pieceId: string,
+      blueprintId: string,
+      blueprintType: 'primitive' | 'composite',
+      source: 'blueprint' | 'sector',
+      position: { x: number; y: number },
+      vertices: number[][][],
+      sectorId?: string
+    ) => void;
+    recordPlacedown: (
+      outcome: 'placed' | 'deleted',
+      sectorId?: string,
+      position?: { x: number; y: number },
+      vertices?: number[][][],
+      anchorId?: string,
+      wasValid?: boolean,
+      wasOverlapping?: boolean,
+      completedSector?: boolean
+    ) => void;
+    recordMouseMove?: (anchorX: number, anchorY: number, sectorId?: string) => void;
+    recordClickEvent?: (
+      location: { x: number; y: number },
+      clickType: 'blueprint_view_switch' | 'invalid_placement' | 'sector_complete_attempt',
+      metadata?: any
+    ) => void;
+  } | null
+): DragControllerHook {
+  const cfg = controller.state.cfg;
+  const clickMode = cfg.input === "click";
+  
+  // Core drag state
+  const svgRef = React.useRef<SVGSVGElement | null>(null);
+  const dragRef = React.useRef<DragState | null>(null);
+  const [draggingId, setDraggingId] = React.useState<string | null>(null);
+  const elMap = React.useRef(new Map<string, SVGGElement>());
+  
+  // Visual feedback for connectivity-locked pieces
+  const [lockedPieceId, setLockedPieceId] = React.useState<string | null>(null);
+  
+  // Ensure dragRef is cleared when draggingId becomes null (for click controller integration)
+  React.useEffect(() => {
+    if (draggingId === null) {
+      dragRef.current = null;
+    }
+  }, [draggingId]);
+
+  const setPieceRef = (id: string) => (el: SVGGElement | null) => {
+    const m = elMap.current;
+    if (el) m.set(id, el); else m.delete(id);
+  };
+
+  const svgPoint = (clientX: number, clientY: number) => {
+    const svg = svgRef.current!;
+    const pt = svg.createSVGPoint();
+    pt.x = clientX; pt.y = clientY;
+    const ctm = svg.getScreenCTM();
+    if (!ctm) return { x: 0, y: 0 };
+    const sp = pt.matrixTransform(ctm.inverse());
+    return { x: sp.x, y: sp.y };
+  };
+
+  const scheduleFrame = () => {
+    if (!dragRef.current) return;
+    const d = dragRef.current;
+    if (d.raf != null) return;
+    d.raf = requestAnimationFrame(() => {
+      d.raf = null;
+      const g = elMap.current.get(d.id);
+      if (g) g.setAttribute("transform", `translate(${d.tlx - d.minx}, ${d.tly - d.miny})`);
+    });
+  };
+
+  const sectorIdAt = (x: number, y: number) => sectorAtPoint(x, y, layout, cfg.target);
+  const GRID_STEP = CONFIG.layout.grid.stepPx;
+
+  const anchorIdFromNode = (node: { x: number; y: number } | null | undefined): string | null => {
+    if (!node) return null;
+    const ax = Math.round(node.x / GRID_STEP);
+    const ay = Math.round(node.y / GRID_STEP);
+    return `${ax},${ay}`;
+  };
+
+  const anchorNodeFromPoint = (point: { x: number; y: number }) => ({
+    x: Math.round(point.x / GRID_STEP) * GRID_STEP,
+    y: Math.round(point.y / GRID_STEP) * GRID_STEP
+  });
+
+  const updatePointerAnchor = (point: { x: number; y: number }, sectorId: string | undefined) => {
+    if (!dragRef.current) return;
+    const d = dragRef.current;
+    const anchorNode = anchorNodeFromPoint(point);
+    const anchorId = anchorIdFromNode(anchorNode);
+
+    if (tracker?.recordMouseMove && (anchorId !== d.pointerAnchorId || sectorId !== d.pointerAnchorSectorId)) {
+      tracker.recordMouseMove(anchorNode.x, anchorNode.y, sectorId);
+    }
+
+    d.pointerAnchor = anchorNode;
+    d.pointerAnchorId = anchorId;
+    d.pointerAnchorSectorId = sectorId;
+  };
+
+  const updateSnapAnchor = (
+    node: { x: number; y: number } | null,
+    sectorId: string | undefined,
+    dist?: number
+  ) => {
+    if (!dragRef.current) return;
+    const d = dragRef.current;
+    d.snapAnchor = node;
+    d.snapAnchorId = anchorIdFromNode(node);
+    d.snapAnchorSectorId = sectorId;
+    d.snapAnchorDist = node && dist !== undefined ? dist : null;
+  };
+
+  const emitClickEvent = (
+    location: { x: number; y: number },
+    clickType: 'blueprint_view_switch' | 'invalid_placement' | 'sector_complete_attempt',
+    metadata?: any
+  ) => {
+    if (!tracker?.recordClickEvent) return;
+    tracker.recordClickEvent(location, clickType, metadata);
+  };
+
+  // Helper: Compute piece vertices in world space
+  const getPieceVertices = (pieceId: string): number[][][] => {
+    const piece = controller.findPiece(pieceId);
+    if (!piece) return [];
+    const bp = controller.getBlueprint(piece.blueprintId);
+    if (!bp) return [];
+    const bb = boundsOfBlueprint(bp, controller.getPrimitive);
+    const polys = piecePolysAt(bp, bb, piece.pos);
+    // Convert from {x,y}[][] to number[][][]
+    return polys.map(ring => ring.map(pt => [pt.x, pt.y]));
+  };
+
+  const onPiecePointerDown = (
+    e: React.PointerEvent<SVGPathElement | SVGGElement>,
+    p: { id: string; x: number; y: number; blueprintId: string; sectorId?: string }
+  ) => {
+    if (p.sectorId && isSectorLocked(p.sectorId)) return;
+    if (clickMode && draggingId) return; // ignore if already carrying
+
+    // Check connectivity in prep mode - prevent removal if it would disconnect remaining pieces
+    if (cfg.mode === "prep" && p.sectorId) {
+      const allPiecesInSector = controller.getPiecesInSector(p.sectorId);
+      const pieceToRemove = controller.findPiece(p.id);
+      
+      if (pieceToRemove && wouldRemovalDisconnectSector(
+        pieceToRemove,
+        allPiecesInSector,
+        (id) => controller.getBlueprint(id),
+        (kind) => controller.getPrimitive(kind)
+      )) {
+        // Flash red briefly to indicate piece cannot be removed
+        setLockedPieceId(p.id);
+        setTimeout(() => setLockedPieceId(null), 500);
+        return; // Prevent pickup
+      }
+    }
+
+    if (clickMode) {
+      // Start a "carry" in click mode: make the piece follow the cursor
+      e.stopPropagation();
+      clickController?.setSelectedPiece(p.id);
+      clickController?.setPendingBp(null);
+
+      const bp = controller.getBlueprint(p.blueprintId)!;
+      const bb = boundsOfBlueprint(bp, (k) => controller.getPrimitive(k));
+      const support = computeSupportOffsets(bp, bb);
+      const { x, y } = svgPoint(e.clientX, e.clientY);
+
+      const pointerAnchorNode = anchorNodeFromPoint({ x, y });
+      const pointerSector = p.sectorId;
+      if (tracker?.recordMouseMove) {
+        tracker.recordMouseMove(pointerAnchorNode.x, pointerAnchorNode.y, pointerSector);
+      }
+
+      // Record pickup event
+      if (tracker) {
+        const blueprintType = ('kind' in bp) ? 'primitive' : 'composite';
+        tracker.recordPickup(
+          p.id,
+          p.blueprintId,
+          blueprintType,
+          'sector',
+          { x: p.x, y: p.y },
+          getPieceVertices(p.id),
+          p.sectorId
+        );
+      }
+
+      dragRef.current = {
+        id: p.id,
+        dx: x - p.x, dy: y - p.y,
+        tlx: p.x,    tly: p.y,
+        aabb: { width: bb.width, height: bb.height },
+        minx: bb.min.x, miny: bb.min.y,
+        support,
+        fromIcon: false,
+        validSnap: true,
+        prevValidSnap: true,
+        raf: null,
+        originalPos: { x: p.x, y: p.y, sectorId: p.sectorId },
+        pointerAnchor: pointerAnchorNode,
+        pointerAnchorId: anchorIdFromNode(pointerAnchorNode),
+        pointerAnchorSectorId: pointerSector,
+        snapAnchor: null,
+        snapAnchorId: null,
+        snapAnchorSectorId: undefined,
+        snapAnchorDist: null,
+        overlaps: false,
+        maxExceeded: false,
+      };
+      updateSnapAnchor(null, p.sectorId);
+      setDraggingId(p.id);
+      force();
+      return;
+    }
+
+    // DRAG path
+    svgRef.current?.setPointerCapture(e.pointerId);
+    const bp = controller.getBlueprint(p.blueprintId)!;
+    const bb = boundsOfBlueprint(bp, (k) => controller.getPrimitive(k));
+    const support = computeSupportOffsets(bp, bb);
+    const { x, y } = svgPoint(e.clientX, e.clientY);
+
+    const pointerAnchorNode = anchorNodeFromPoint({ x, y });
+    const pointerSector = p.sectorId;
+    if (tracker?.recordMouseMove) {
+      tracker.recordMouseMove(pointerAnchorNode.x, pointerAnchorNode.y, pointerSector);
+    }
+
+    // Record pickup event
+    if (tracker) {
+      const blueprintType = ('kind' in bp) ? 'primitive' : 'composite';
+      tracker.recordPickup(
+        p.id,
+        p.blueprintId,
+        blueprintType,
+        'sector',
+        { x: p.x, y: p.y },
+        getPieceVertices(p.id),
+        p.sectorId
+      );
+    }
+
+    dragRef.current = {
+      id: p.id,
+      dx: x - p.x, dy: y - p.y,
+      tlx: p.x,    tly: p.y,
+      aabb: { width: bb.width, height: bb.height },
+      minx: bb.min.x, miny: bb.min.y,
+      support,
+      fromIcon: false,
+      validSnap: true,
+      prevValidSnap: true,
+      raf: null,
+      originalPos: { x: p.x, y: p.y, sectorId: p.sectorId },
+      pointerAnchor: pointerAnchorNode,
+      pointerAnchorId: anchorIdFromNode(pointerAnchorNode),
+      pointerAnchorSectorId: pointerSector,
+      snapAnchor: null,
+      snapAnchorId: null,
+      snapAnchorSectorId: undefined,
+      snapAnchorDist: null,
+      overlaps: false,
+      maxExceeded: false,
+    };
+    updateSnapAnchor(null, p.sectorId);
+    setDraggingId(p.id);
+    force();
+  };
+
+  const onPointerMove = (e: React.PointerEvent<SVGSVGElement>) => {
+    const { x, y } = svgPoint(e.clientX, e.clientY);
+
+    // Always log pointer movement for mouse tracking, even before pickup
+    const pointerAnchorNode = anchorNodeFromPoint({ x, y });
+    const pointerR = Math.hypot(x - layout.cx, y - layout.cy);
+    const pointerSectorId = pointerR < layout.innerR ? undefined : sectorIdAt(x, y) ?? undefined;
+    if (!dragRef.current) {
+      if (tracker?.recordMouseMove) {
+        tracker.recordMouseMove(pointerAnchorNode.x, pointerAnchorNode.y, pointerSectorId);
+      }
+      return;
+    }
+
+    const d = dragRef.current;
+    const tlx = x - d.dx, tly = y - d.dy;
+
+    updatePointerAnchor({ x, y }, pointerSectorId);
+
+    const clamped = clampTopLeftBySupport(
+      tlx, tly,
+      { aabb: d.aabb, support: d.support },
+      layout,
+      controller.state.cfg.target,
+      pointerR < layout.innerR
+    );
+
+    let tl = clamped;
+    // Snap the *piece itself* to nearest nodes in the active sector (or inner ring),
+    // and compute validity (silhouette: within snapRadius; workspace: always valid).
+      const centerX = tl.x + d.aabb.width / 2;
+      const centerY = tl.y + d.aabb.height / 2;
+      const rFromCenter = Math.hypot(centerX - layout.cx, centerY - layout.cy);
+      const inInnerRing = rFromCenter < layout.innerR;
+      const secId = inInnerRing ? null : sectorIdAt(centerX, centerY);
+      let snapNode: { x: number; y: number } | null = null;
+      let snapDist: number | null = null;
+      let snapSectorId: string | undefined = secId ?? undefined;
+      let overlapsDetected = false;
+      let maxExceededDetected = false;
+
+      // Check for inner ring snapping first
+      if (inInnerRing) {
+        const innerEntry = anchorDots.find(a => a.sectorId === "inner-ring");
+        if (innerEntry && innerEntry.valid.length) {
+          const piece = pieceById(d.id);
+          if (piece) {
+            const bp = controller.getBlueprint(piece.blueprintId)!;
+            const snap = nearestNodeSnap(tl, bp, controller.getPrimitive, innerEntry.valid);
+            tl = snap.tl;
+            snapNode = snap.node;
+            snapDist = snap.dist;
+            snapSectorId = undefined;
+          }
+        }
+        // Inner ring shows RED (invalid) to indicate piece will be deleted
+        d.validSnap = false;
+      } else if (secId) {
+        const isCompletedSector = isSectorLocked(secId);
+        const entry = anchorDots.find(a => a.sectorId === secId);
+        const allNodes =
+          (cfg.target === "workspace" && cfg.mode !== "prep")
+            ? (entry?.valid ?? [])  // Construction workspace: only valid nodes
+            : [ ...(entry?.valid ?? []), ...(entry?.invalid ?? []) ];  // Silhouette + Prep: all nodes
+
+        // Snap to anchors even in completed sectors
+        if (allNodes.length) {
+          const piece = pieceById(d.id);
+          if (piece) {
+            const bp = controller.getBlueprint(piece.blueprintId)!;
+            const snap = nearestNodeSnap(
+              tl,
+              bp,
+              controller.getPrimitive,
+              allNodes
+            );
+            tl = snap.tl;
+            snapNode = snap.node;
+            snapDist = snap.dist;
+            snapSectorId = secId;
+
+            // Completed sectors: always show red (invalid)
+            if (isCompletedSector) {
+              d.validSnap = false;
+            } else {
+              // Normal validation for incomplete sectors
+              const radius = controller.state.cfg.snapRadiusPx;
+              // Gather world polys for the carried piece at the *snapped* TL
+              const carried = pieceById(d.id);
+              let overlapsOk = true;
+              if (carried) {
+              const bpCar = controller.getBlueprint(carried.blueprintId)!;
+              const bbCar = boundsOfBlueprint(
+                bpCar,
+                controller.getPrimitive
+              );
+              const carriedPolys = piecePolysAt(bpCar, bbCar, tl);
+
+              // only compare against pieces in the same sector we're currently over
+              const sameSector = pieces.filter(
+                pp =>
+                  pp.id !== d.id &&
+                  sectorIdAt(
+                    pp.x +
+                      boundsOfBlueprint(
+                        controller.getBlueprint(pp.blueprintId)!,
+                        controller.getPrimitive
+                      ).width / 2,
+                    pp.y +
+                      boundsOfBlueprint(
+                        controller.getBlueprint(pp.blueprintId)!,
+                        controller.getPrimitive
+                      ).height / 2,
+                  ) === secId
+              );
+
+              for (const other of sameSector) {
+                const bpO = controller.getBlueprint(other.blueprintId)!;
+                const bbO = boundsOfBlueprint(
+                  bpO,
+                  controller.getPrimitive
+                );
+                const otherPolys = piecePolysAt(bpO, bbO, { x: other.x, y: other.y });
+                if (polysOverlap(carriedPolys, otherPolys)) {
+                  overlapsOk = false;
+                  break;
+                }
+              }
+
+              // workspace: validity depends on mode
+              if (cfg.target === "workspace") {
+                if (cfg.mode === "prep") {
+                  // Prep mode: ALWAYS allow movement (just show visual feedback)
+                  // Face-to-face validation only affects visual feedback, not movement
+                  const allPiecesInSector = controller.getPiecesInSector(secId);
+                  const otherPiecesInSector = allPiecesInSector.filter(piece => piece.id !== d.id);
+                  const isFirstPiece = otherPiecesInSector.length === 0;
+                  const storedPiece = controller.findPiece(d.id);
+                  const currentSectorId = storedPiece?.sectorId;
+                  const maxPieces = controller.state.cfg.maxCompositeSize ?? 0;
+                  const enforceMaxPieces = maxPieces > 0;
+                  const effectiveCount = allPiecesInSector.length - (currentSectorId === secId ? 1 : 0);
+                  const wouldExceedMax = enforceMaxPieces && (effectiveCount + 1 > maxPieces);
+
+                  if (isFirstPiece) {
+                    // First piece: visual feedback based on overlaps and max-piece limit
+                    d.validSnap = overlapsOk && !wouldExceedMax;
+                    maxExceededDetected = wouldExceedMax;
+                  } else if (storedPiece) {
+                    // Subsequent pieces: visual feedback based on face-to-face attachment
+                    const pieceAtDragPosition = {
+                      ...storedPiece,
+                      pos: { x: tl.x, y: tl.y }
+                    };
+
+                    const attachmentResult = checkFaceToFaceAttachment(
+                      pieceAtDragPosition,
+                      otherPiecesInSector,
+                      (id) => controller.getBlueprint(id),
+                      (kind) => controller.getPrimitive(kind)
+                    );
+
+                    d.validSnap = overlapsOk && attachmentResult.isAttached && !wouldExceedMax;
+                    maxExceededDetected = wouldExceedMax;
+                  } else {
+                    d.validSnap = overlapsOk && !wouldExceedMax;
+                    maxExceededDetected = wouldExceedMax;
+                  }
+
+                  // IMPORTANT: In prep mode, always allow movement regardless of validSnap
+                  // validSnap is only for visual feedback (red/blue coloring)
+                } else {
+                  // Construction mode: original behavior (validSnap blocks movement)
+                d.validSnap = overlapsOk;
+                maxExceededDetected = false;
+              }
+              overlapsDetected = !overlapsOk;
+            } else {
+                // silhouette: node must be valid AND fully inside AND !overlap
+                const key = (p: { x: number; y: number }) => `${p.x},${p.y}`;
+                const validSet = new Set((entry?.valid ?? []).map(key));
+                const nodeOk =
+                  !!snap.node && validSet.has(key(snap.node)) && snap.dist <= (radius ?? 0);
+                let insideOk = false;
+                if (nodeOk) {
+                  const silPolys = placedSilBySector.get(secId) ?? [];
+                  insideOk = polyFullyInside(carriedPolys, silPolys);
+                }
+                d.validSnap = nodeOk && insideOk && overlapsOk;
+                overlapsDetected = !overlapsOk;
+              }
+            }
+            }
+          }
+        }
+      } else { 
+        // not over any sector band
+        d.validSnap = (controller.state.cfg.target === "workspace");
+        snapNode = null;
+        snapDist = null;
+        snapSectorId = undefined;
+        maxExceededDetected = false;
+      }
+    d.overlaps = overlapsDetected;
+    d.maxExceeded = maxExceededDetected;
+    updateSnapAnchor(snapNode, snapSectorId, snapDist ?? undefined);
+    d.tlx = tl.x; d.tly = tl.y;
+
+    // If the validity state changed, force a React render so fill/stroke update immediately.
+    if (d.prevValidSnap !== d.validSnap) {
+      d.prevValidSnap = d.validSnap ?? false;
+      force();
+    }
+
+    scheduleFrame();
+  };
+
+  const onPointerUp = () => {
+    if (!dragRef.current) return;
+    if (clickMode) return;
+
+    const d = dragRef.current;
+    // If the candidate is invalid for any reason (overlap/outside/bad node), handle based on mode
+    if (d.validSnap === false) {
+      const piece = controller.findPiece(d.id);
+      const cfg = controller.state.cfg;
+      const centerX = d.tlx + d.aabb.width / 2;
+      const centerY = d.tly + d.aabb.height / 2;
+      const attemptedSector = sectorIdAt(centerX, centerY);
+      let invalidReason: 'overlapping' | 'outside_bounds' | 'no_valid_anchor' | 'sector_complete' = 'outside_bounds';
+      if (d.maxExceeded) {
+        invalidReason = 'no_valid_anchor';
+      } else if (d.overlaps) {
+        invalidReason = 'overlapping';
+      } else if (attemptedSector) {
+        invalidReason = 'no_valid_anchor';
+      }
+      emitClickEvent(
+        { x: centerX, y: centerY },
+        'invalid_placement',
+        { invalidPlacement: { reason: invalidReason, attemptedSectorId: attemptedSector ?? undefined } }
+      );
+
+      // In prep mode: return to original position (if exists) or delete (if from icon)
+      if (cfg.mode === "prep" && d.originalPos) {
+        // Return piece to its original position
+        controller.move(d.id, { x: d.originalPos.x, y: d.originalPos.y });
+
+        // Record placedown as "placed" back in original position
+        if (tracker) {
+          tracker.recordPlacedown(
+            'placed',
+            d.originalPos.sectorId,
+            { x: d.originalPos.x, y: d.originalPos.y },
+            getPieceVertices(d.id),
+            d.snapAnchorId ?? undefined,
+            false,
+            d.overlaps ?? false
+          );
+        }
+      } else {
+        // Construction mode or fromIcon in prep mode: delete piece
+        const removedFromSector = piece?.sectorId;
+        controller.remove(d.id);
+        // Re-check completion for the sector the piece was removed from
+        if (removedFromSector) maybeCompleteSector(removedFromSector);
+
+        // Record placedown as "deleted"
+        if (tracker) {
+          tracker.recordPlacedown(
+            'deleted',
+            removedFromSector,
+            undefined,
+            undefined,
+            d.snapAnchorId ?? undefined,
+            false,
+            d.overlaps ?? false
+          );
+        }
+      }
+
+      dragRef.current = null;
+      setDraggingId(null);
+      force();
+      return;
+    }
+    
+    dragRef.current = null;
+    if (d.raf) { cancelAnimationFrame(d.raf); d.raf = null; }
+
+    const commitTL = { x: d.tlx, y: d.tly };
+    const centerX = commitTL.x + d.aabb.width / 2;
+    const centerY = commitTL.y + d.aabb.height / 2;
+
+    // delete if inside the inner hole
+    const rFromCenter = Math.hypot(centerX - layout.cx, centerY - layout.cy);
+    if (rFromCenter < layout.innerR) {
+      const piece = controller.findPiece(d.id);
+      const removedFromSector = piece?.sectorId;
+      controller.remove(d.id);
+      // Re-check completion for the sector the piece was removed from
+      if (removedFromSector) maybeCompleteSector(removedFromSector);
+
+      // Record placedown as "deleted"
+      if (tracker) {
+        tracker.recordPlacedown(
+          'deleted',
+          removedFromSector,
+          undefined,
+          undefined,
+          d.snapAnchorId ?? undefined,
+          false,
+          d.overlaps ?? false
+        );
+      }
+
+      setDraggingId(null);
+      force();
+      return;
+    }
+
+    const secId = sectorIdAt(centerX, centerY);
+
+    // Completed sector: no-op (do nothing, same as clicking incomplete sector in silhouette mode)
+    if (secId && isSectorLocked(secId)) {
+      emitClickEvent(
+        { x: centerX, y: centerY },
+        'sector_complete_attempt',
+        { invalidPlacement: { reason: 'sector_complete', attemptedSectorId: secId } }
+      );
+      // Return piece to original position if it exists, otherwise delete (from icon spawn)
+      if (d.originalPos) {
+        controller.move(d.id, { x: d.originalPos.x, y: d.originalPos.y });
+        if (d.originalPos.sectorId) {
+          controller.drop(d.id, d.originalPos.sectorId);
+        }
+
+        // Record placedown as "placed" back in original position
+        if (tracker) {
+          tracker.recordPlacedown(
+            'placed',
+            d.originalPos.sectorId,
+            { x: d.originalPos.x, y: d.originalPos.y },
+            getPieceVertices(d.id),
+            d.snapAnchorId ?? undefined,
+            false,
+            d.overlaps ?? false
+          );
+        }
+      } else {
+        // Piece was spawned from icon and dropped in completed sector → delete
+        controller.remove(d.id);
+
+        // Record placedown as "deleted"
+        if (tracker) {
+          tracker.recordPlacedown(
+            'deleted',
+            undefined,
+            undefined,
+            undefined,
+            d.snapAnchorId ?? undefined,
+            false,
+            d.overlaps ?? false
+          );
+        }
+      }
+      setDraggingId(null);
+      force();
+      return;
+    }
+
+    controller.move(d.id, commitTL);
+    controller.drop(d.id, secId);
+
+    const justCompleted = secId ? maybeCompleteSector(secId) : false;
+
+    // Record placedown as "placed" successfully
+    const wasValid = d.validSnap === undefined ? true : d.validSnap;
+    if (tracker) {
+      tracker.recordPlacedown(
+        'placed',
+        secId,
+        commitTL,
+        getPieceVertices(d.id),
+        d.snapAnchorId ?? undefined,
+        wasValid,
+        d.overlaps ?? false,
+        justCompleted
+      );
+    }
+
+    setDraggingId(null);
+
+    // auto-revert AFTER completing a drag spawn from the center
+    if (d.fromIcon && controller.state.blueprintView === "primitives") {
+      controller.switchBlueprintView();
+    }
+    force();
+  };
+
+  const onBlueprintPointerDown = (
+    e: React.PointerEvent,
+    bp: Blueprint,
+    bpGeom: { bx: number; by: number; cx: number; cy: number }
+  ) => {
+    if (clickMode && draggingId) return;
+    e.stopPropagation();
+
+    const { x: px, y: py } = svgPoint(e.clientX, e.clientY);
+    const bb = boundsOfBlueprint(bp, controller.getPrimitive);
+    const support = computeSupportOffsets(bp, bb);
+
+    if (clickMode) {
+      // Click mode: spawn then enter carry state
+      
+      // Compute the local point of the blueprint glyph that was clicked
+      const q = blueprintLocalFromWorld(px, py, bpGeom);
+      // Compute TL so that the clicked point stays under the cursor
+      const tl0 = { x: px - (q.x - bb.min.x), y: py - (q.y - bb.min.y) };
+      const pointerR = Math.hypot(px - layout.cx, py - layout.cy);
+      const allowInside = pointerR < layout.innerR;
+      const clamped = clampTopLeftBySupport(
+        tl0.x, tl0.y,
+        { aabb: bb, support },
+        layout,
+        controller.state.cfg.target,
+        allowInside
+      );
+      const pieceId = controller.spawnFromBlueprint(bp, clamped);
+      const pointerAnchorNode = anchorNodeFromPoint({ x: px, y: py });
+      const pointerSector = sectorIdAt(px, py) ?? undefined;
+      if (tracker?.recordMouseMove) {
+        tracker.recordMouseMove(pointerAnchorNode.x, pointerAnchorNode.y, pointerSector);
+      }
+
+      // Record pickup event for blueprint spawn
+      if (tracker) {
+        const blueprintType = ('kind' in bp) ? 'primitive' : 'composite';
+        tracker.recordPickup(
+          pieceId,
+          bp.id,
+          blueprintType,
+          'blueprint',
+          clamped,
+          getPieceVertices(pieceId),
+          undefined
+        );
+      }
+
+      const tl = clamped;
+      // If anchors mode, immediately snap initial TL to the nearest nodes in the active sector
+      let finalTl = tl;
+      let snapInfo: { node: { x: number; y: number } | null; dist: number } | null = null;
+        const centerX = tl.x + bb.width / 2;
+        const centerY = tl.y + bb.height / 2;
+        const secId = sectorIdAt(centerX, centerY);
+        if (secId) {
+          const entry = anchorDots.find(a => a.sectorId === secId);
+          const nodes =
+            controller.state.cfg.target === "workspace"
+              ? (entry?.valid ?? [])
+              : [ ...(entry?.valid ?? []), ...(entry?.invalid ?? []) ];
+          if (nodes.length) {
+            const snap = nearestNodeSnap(tl, bp, controller.getPrimitive, nodes);
+            finalTl = snap.tl;
+            snapInfo = { node: snap.node, dist: snap.dist };
+          }
+        }
+      
+      controller.move(pieceId, finalTl);
+      dragRef.current = {
+        id: pieceId,
+        dx: px - finalTl.x,
+        dy: py - finalTl.y,
+        tlx: finalTl.x,
+        tly: finalTl.y,
+        aabb: bb,
+        minx: bb.min.x,
+        miny: bb.min.y,
+        support,
+        fromIcon: true,
+        validSnap: true,
+        prevValidSnap: true,
+        raf: null,
+        originalPos: undefined, // No original position for fromIcon drags
+        pointerAnchor: pointerAnchorNode,
+        pointerAnchorId: anchorIdFromNode(pointerAnchorNode),
+        pointerAnchorSectorId: pointerSector,
+        snapAnchor: null,
+        snapAnchorId: null,
+        snapAnchorSectorId: undefined,
+        snapAnchorDist: null,
+        overlaps: false,
+        maxExceeded: false,
+      };
+      updatePointerAnchor({ x: px, y: py }, pointerSector);
+      const snappingSecId = sectorIdAt(finalTl.x + bb.width / 2, finalTl.y + bb.height / 2) ?? undefined;
+      updateSnapAnchor(snapInfo?.node ?? null, snappingSecId, snapInfo?.dist);
+      setDraggingId(pieceId); // now onPointerMove will keep it in sync
+      force();
+      scheduleFrame();
+      return;
+    }
+
+    // Drag mode: spawn at pointer with immediate drag
+    svgRef.current?.setPointerCapture(e.pointerId);
+
+    // Compute the local point of the blueprint glyph that was clicked
+    const q = blueprintLocalFromWorld(px, py, bpGeom);
+    // Compute TL so that the clicked point stays under the cursor
+    const tl0 = { x: px - (q.x - bb.min.x), y: py - (q.y - bb.min.y) };
+    const pointerR = Math.hypot(px - layout.cx, py - layout.cy);
+    const allowInside = pointerR < layout.innerR;
+    const clamped = clampTopLeftBySupport(
+      tl0.x, tl0.y,
+      { aabb: bb, support },
+      layout,
+      controller.state.cfg.target,
+      allowInside
+    );
+    const pieceId = controller.spawnFromBlueprint(bp, clamped);
+    const pointerAnchorNode = anchorNodeFromPoint({ x: px, y: py });
+    const pointerSector = sectorIdAt(px, py) ?? undefined;
+    if (tracker?.recordMouseMove) {
+      tracker.recordMouseMove(pointerAnchorNode.x, pointerAnchorNode.y, pointerSector);
+    }
+
+    // Record pickup event for blueprint spawn
+    if (tracker) {
+      const blueprintType = ('kind' in bp) ? 'primitive' : 'composite';
+      tracker.recordPickup(
+        pieceId,
+        bp.id,
+        blueprintType,
+        'blueprint',
+        clamped,
+        getPieceVertices(pieceId),
+        undefined
+      );
+    }
+
+    dragRef.current = {
+      id: pieceId,
+      dx: px - clamped.x,
+      dy: py - clamped.y,
+      tlx: clamped.x,
+      tly: clamped.y,
+      aabb: bb,
+      minx: bb.min.x,
+      miny: bb.min.y,
+      support,
+      fromIcon: true,
+      validSnap: true,
+      prevValidSnap: true,
+      raf: null,
+      originalPos: undefined, // No original position for fromIcon drags
+      pointerAnchor: pointerAnchorNode,
+      pointerAnchorId: anchorIdFromNode(pointerAnchorNode),
+      pointerAnchorSectorId: pointerSector,
+      snapAnchor: null,
+      snapAnchorId: null,
+      snapAnchorSectorId: undefined,
+      snapAnchorDist: null,
+      overlaps: false,
+    };
+    updatePointerAnchor({ x: px, y: py }, pointerSector);
+    updateSnapAnchor(null, undefined);
+    setDraggingId(pieceId);
+    force();
+    scheduleFrame();
+  };
+
+  return {
+    // State
+    draggingId,
+    dragInvalid: !!(dragRef.current && dragRef.current.validSnap === false),
+    lockedPieceId,
+    svgRef,
+    
+    // Handlers
+    onPiecePointerDown,
+    onBlueprintPointerDown,
+    onPointerMove,
+    onPointerUp,
+    setPieceRef,
+    
+    // Click controller integration
+    setDraggingId,
+
+    // TODO: Remove this once click mode is extracted - temporary for compatibility
+    dragRef
+  };
+}