@morphika/webframe 0.1.0

package/components/builder/live-preview/LiveProjectGridPreview.tsx

@@ -0,0 +1,1010 @@
+"use client";
+
+/**
+ * LiveProjectGridPreview — Builder canvas preview for ProjectGrid v2.
+ *
+ * Uses the shared masonry engine (lib/builder/masonry.ts) with absolute
+ * positioning for pixel-perfect parity with the public renderer.
+ *
+ * Features:
+ * - JS masonry layout (shortest-column algorithm)
+ * - 1–6 columns, per-card aspect ratio overrides
+ * - Card selection (click → blue border, settings panel shows per-card controls)
+ * - Hover state (blue border, suppressed during drag)
+ * - Override badge (aspect ratio override indicator)
+ * - Custom drag & drop: hold card body (150ms) or grab handle (immediate)
+ *   → grabbed state (darkened + icon) → dragging (ghost follows mouse,
+ *   dashed placeholder, green drop targets via coordinate hit-testing)
+ *   → swap on drop or cancel fly-back animation
+ *
+ * Session 105 Phase 4: Builder live preview rewrite.
+ * Session 105 Phase 5: Custom DnD system (drag initiation, ghost, coordinate
+ *   hit-testing for drop targets, swap logic, cancel animation).
+ */
+
+import {
+  useState,
+  useCallback,
+  useRef,
+  useEffect,
+  useMemo,
+} from "react";
+import { createPortal } from "react-dom";
+import { ProjectGridCard, useProjectThumbnails } from "./shared";
+import { useBuilderStore } from "../../../lib/builder/store";
+import {
+  computeMasonry,
+  resolveItemRatio,
+  type MasonryItem,
+  type MasonryOutput,
+} from "../../../lib/builder/masonry";
+import type { ProjectGridBlock, ProjectGridItem } from "../../../lib/sanity/types";
+import type { DeviceViewport } from "../../../lib/builder/types";
+import { BUILDER_BLUE, BUILDER_GREEN } from "../../../lib/builder/constants";
+
+// ─── Constants ───────────────────────────────────────────────────────
+
+const HOLD_DELAY = 150; // ms before card-body drag activates
+const MOVE_THRESHOLD_SQ = 9; // 3px² — grabbed → dragging
+const CANCEL_DURATION = 200; // ms — cancel fly-back animation
+const ADMIN_BLUE = BUILDER_BLUE;
+const DROP_GREEN = BUILDER_GREEN;
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+interface DragState {
+  phase: "grabbed" | "dragging" | "cancelling";
+  draggedKey: string;
+  hoverTargetKey: string | null;
+  mouseX: number;
+  mouseY: number;
+  startMouseX: number;
+  startMouseY: number;
+  offsetX: number; // grab offset inside the card (screen px)
+  offsetY: number;
+  cardWidth: number; // screen-space dimensions (includes zoom)
+  cardHeight: number;
+  origScreenX: number; // original card position on screen (for cancel)
+  origScreenY: number;
+}
+
+// ─── Utilities ───────────────────────────────────────────────────────
+
+/** Cross-arrow icon SVG (reused in handle, grabbed overlay, ghost). */
+function CrossArrowIcon({
+  size = 14,
+  color = "currentColor",
+}: {
+  size?: number;
+  color?: string;
+}) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 16 16" fill={color}>
+      <path d="M8 0l2.5 3h-2v4.5H13v-2L16 8l-3 2.5v-2H8.5V13h2L8 16l-2.5-3h2V8.5H3v2L0 8l3-2.5v2h4.5V3h-2L8 0z" />
+    </svg>
+  );
+}
+
+/**
+ * Hit-test pointer (screen coords) against masonry items (container coords).
+ * Returns the key of the card under the cursor, or null if in a gap.
+ * Only ONE card can match (masonry cards never overlap).
+ */
+function hitTestCards(
+  clientX: number,
+  clientY: number,
+  container: HTMLElement,
+  containerWidth: number,
+  masonry: MasonryOutput,
+  excludeKey: string,
+): string | null {
+  const rect = container.getBoundingClientRect();
+  if (rect.width === 0 || rect.height === 0 || masonry.totalHeight === 0)
+    return null;
+
+  // Convert screen → masonry coordinate space
+  const relX = (clientX - rect.left) * (containerWidth / rect.width);
+  const relY = (clientY - rect.top) * (masonry.totalHeight / rect.height);
+
+  for (const item of masonry.items) {
+    if (item.key === excludeKey) continue;
+    if (
+      relX >= item.x &&
+      relX <= item.x + item.width &&
+      relY >= item.y &&
+      relY <= item.y + item.height
+    ) {
+      return item.key;
+    }
+  }
+  return null;
+}
+
+// ─── ProjectCardWrapper ─────────────────────────────────────────────
+
+interface CardProps {
+  item: ProjectGridItem;
+  thumbMap: Map<string, string | undefined>;
+  borderRadius: number;
+  cardWidth: number;
+  cardHeight: number;
+  isGrabbed: boolean;
+  isDragging: boolean;
+  isDropTarget: boolean;
+  isSelected: boolean;
+  isAnyDragActive: boolean;
+  onPointerDown: (
+    key: string,
+    e: React.PointerEvent,
+    cardEl: HTMLDivElement,
+    fromHandle: boolean,
+  ) => void;
+  onSelect: (key: string) => void;
+}
+
+function ProjectCardWrapper({
+  item,
+  thumbMap,
+  borderRadius,
+  cardWidth,
+  cardHeight,
+  isGrabbed,
+  isDragging,
+  isDropTarget,
+  isSelected,
+  isAnyDragActive,
+  onPointerDown,
+  onSelect,
+}: CardProps) {
+  const cardRef = useRef<HTMLDivElement>(null);
+  const canvasZoom = useBuilderStore((s) => s.canvasZoom);
+  const [isHovered, setIsHovered] = useState(false);
+
+  // ── Handle pointerdown (drag handle = immediate, card body = hold) ──
+
+  const handleHandleDown = useCallback(
+    (e: React.PointerEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (cardRef.current) onPointerDown(item._key, e, cardRef.current, true);
+    },
+    [item._key, onPointerDown],
+  );
+
+  const handleCardDown = useCallback(
+    (e: React.PointerEvent) => {
+      if (e.button !== 0) return;
+      e.stopPropagation();
+      if (cardRef.current) onPointerDown(item._key, e, cardRef.current, false);
+    },
+    [item._key, onPointerDown],
+  );
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      onSelect(item._key);
+    },
+    [item._key, onSelect],
+  );
+
+  const br = borderRadius > 0 ? borderRadius : undefined;
+  const brStr = borderRadius > 0 ? String(borderRadius) : undefined;
+  const invZoom = Math.min(2, 1 / canvasZoom);
+
+  // ── Grabbed: darkened card + centered cross-arrow icon ──────────
+
+  if (isGrabbed) {
+    return (
+      <div
+        ref={cardRef}
+        style={{
+          position: "relative",
+          width: cardWidth,
+          height: cardHeight,
+          borderRadius: br,
+          overflow: "hidden",
+          outline: `2px solid ${ADMIN_BLUE}`,
+          outlineOffset: -2,
+        }}
+      >
+        <ProjectGridCard
+          slug={item.project_slug}
+          thumbPath={thumbMap.get(item.project_slug)}
+          customThumb={item.custom_thumbnail}
+          borderRadius={brStr}
+          style={{ width: "100%", height: "100%", filter: "brightness(0.65)" }}
+        />
+        {/* Centered drag icon overlay */}
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            pointerEvents: "none",
+          }}
+        >
+          <div
+            style={{
+              width: 40,
+              height: 40,
+              borderRadius: "50%",
+              backgroundColor: "rgba(255,255,255,0.92)",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              boxShadow: "0 2px 12px rgba(0,0,0,0.2)",
+              transform: `scale(${invZoom})`,
+            }}
+          >
+            <CrossArrowIcon size={20} color="#333" />
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // ── Dragging / Cancelling: dashed blue placeholder ─────────────
+
+  if (isDragging) {
+    return (
+      <div
+        ref={cardRef}
+        style={{
+          width: cardWidth,
+          height: cardHeight,
+          borderRadius: br,
+          border: `${Math.max(2, 2 / canvasZoom)}px dashed ${ADMIN_BLUE}`,
+          backgroundColor: "transparent",
+          boxSizing: "border-box",
+        }}
+      />
+    );
+  }
+
+  // ── Normal card ────────────────────────────────────────────────
+
+  // Green drop-target highlight — no extra style on wrapper, overlay rendered below
+  const dropStyle: React.CSSProperties = {};
+
+  // Blue hover border (suppressed when drag is active or card is selected/drop target)
+  const showHover = isHovered && !isSelected && !isDropTarget && !isAnyDragActive;
+  const hoverStyle: React.CSSProperties = showHover
+    ? {
+        outline: `${2 / canvasZoom}px solid ${ADMIN_BLUE}`,
+        outlineOffset: -2 / canvasZoom,
+      }
+    : {};
+
+  // Blue selection border + subtle tint
+  const selectStyle: React.CSSProperties =
+    isSelected && !isDropTarget
+      ? {
+          outline: `2px solid ${ADMIN_BLUE}`,
+          outlineOffset: -2,
+          boxShadow: "inset 0 0 0 9999px rgba(7,107,255,0.04)",
+        }
+      : {};
+
+  return (
+    <div
+      ref={cardRef}
+      style={{
+        position: "relative",
+        width: cardWidth,
+        height: cardHeight,
+        cursor: "pointer",
+        borderRadius: br,
+        overflow: "hidden",
+        ...dropStyle,
+        ...hoverStyle,
+        ...selectStyle,
+        transition: "outline 150ms ease, box-shadow 150ms ease",
+      }}
+      onPointerDown={handleCardDown}
+      onClick={handleClick}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+    >
+      {/* Drag handle — centered, visible on hover/selection (hidden during drag) */}
+      <div
+        className={`absolute z-10 transition-opacity ${
+          (isHovered || isSelected) && !isAnyDragActive
+            ? "opacity-100"
+            : "opacity-0 pointer-events-none"
+        }`}
+        style={{
+          inset: 0,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+        }}
+      >
+        <div
+          onPointerDown={handleHandleDown}
+          onClick={(e) => e.stopPropagation()}
+          style={{
+            width: 48,
+            height: 48,
+            borderRadius: "50%",
+            backgroundColor: "rgba(255,255,255,0.92)",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            boxShadow: "0 2px 12px rgba(0,0,0,0.25)",
+            cursor: "grab",
+            transform: `scale(${invZoom})`,
+          }}
+          title="Drag to reorder"
+          aria-label="Drag to reorder project"
+        >
+          <CrossArrowIcon size={22} color="#333" />
+        </div>
+      </div>
+
+      {/* Per-card aspect ratio override badge — bottom-right */}
+      {item.aspect_ratio_override && (
+        <div
+          className="absolute z-10"
+          style={{
+            bottom: 8,
+            right: 8,
+            transform: `scale(${invZoom})`,
+            transformOrigin: "bottom right",
+          }}
+        >
+          <span
+            className="px-1.5 py-0.5 rounded text-[9px] font-medium"
+            style={{
+              backgroundColor: "rgba(0,0,0,0.6)",
+              color: "rgba(255,255,255,0.85)",
+              backdropFilter: "blur(4px)",
+            }}
+          >
+            {item.aspect_ratio_override.replace("/", ":")}
+          </span>
+        </div>
+      )}
+
+      <ProjectGridCard
+        slug={item.project_slug}
+        thumbPath={thumbMap.get(item.project_slug)}
+        customThumb={item.custom_thumbnail}
+        borderRadius={brStr}
+        style={{ width: "100%", height: "100%" }}
+      />
+
+      {/* Green drop-target overlay (covers the image) */}
+      {isDropTarget && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            backgroundColor: "rgba(34,197,94,0.30)",
+            borderRadius: br,
+            pointerEvents: "none",
+            zIndex: 5,
+            border: `2px solid ${DROP_GREEN}`,
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+// ─── GhostCard ──────────────────────────────────────────────────────
+
+function GhostCard({
+  item,
+  thumbMap,
+  borderRadius,
+  dragState,
+}: {
+  item: ProjectGridItem;
+  thumbMap: Map<string, string | undefined>;
+  borderRadius: number;
+  dragState: DragState;
+}) {
+  const isCancelling = dragState.phase === "cancelling";
+  return (
+    <div
+      style={{
+        position: "fixed",
+        left: dragState.mouseX - dragState.offsetX,
+        top: dragState.mouseY - dragState.offsetY,
+        width: dragState.cardWidth,
+        height: dragState.cardHeight,
+        zIndex: 9999,
+        pointerEvents: "none",
+        borderRadius: borderRadius > 0 ? borderRadius : 8,
+        overflow: "hidden",
+        transform: isCancelling ? "scale(1)" : "scale(1.03)",
+        outline: `2px solid ${ADMIN_BLUE}`,
+        outlineOffset: -2,
+        boxShadow: isCancelling
+          ? "0 4px 16px rgba(0,0,0,0.15)"
+          : "0 16px 48px rgba(0,0,0,0.3)",
+        transition: isCancelling
+          ? `left ${CANCEL_DURATION}ms ease, top ${CANCEL_DURATION}ms ease, transform ${CANCEL_DURATION}ms ease, box-shadow ${CANCEL_DURATION}ms ease`
+          : undefined,
+      }}
+    >
+      <ProjectGridCard
+        slug={item.project_slug}
+        thumbPath={thumbMap.get(item.project_slug)}
+        customThumb={item.custom_thumbnail}
+        borderRadius={borderRadius > 0 ? String(borderRadius) : undefined}
+        style={{ width: "100%", height: "100%" }}
+      />
+      {/* Centered cross-arrow icon */}
+      <div
+        style={{
+          position: "absolute",
+          inset: 0,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          pointerEvents: "none",
+        }}
+      >
+        <div
+          style={{
+            width: 40,
+            height: 40,
+            borderRadius: "50%",
+            backgroundColor: "rgba(255,255,255,0.92)",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            boxShadow: "0 2px 12px rgba(0,0,0,0.2)",
+          }}
+        >
+          <CrossArrowIcon size={20} color="#333" />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ─── Main Component ─────────────────────────────────────────────────
+
+export default function LiveProjectGridPreview({
+  block,
+  viewport: frameViewport = "desktop",
+}: {
+  block: ProjectGridBlock;
+  viewport?: DeviceViewport;
+}) {
+  const updateBlock = useBuilderStore((s) => s.updateBlock);
+  const _pushSnapshot = useBuilderStore((s) => s._pushSnapshot);
+  const selectProjectCard = useBuilderStore((s) => s.selectProjectCard);
+  const selectedProjectCardKey = useBuilderStore((s) =>
+    s.selectedProjectCardKey,
+  );
+  const selectedBlockKey = useBuilderStore((s) => s.selectedBlockKey);
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const roRef = useRef<ResizeObserver | null>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [dragState, setDragState] = useState<DragState | null>(null);
+
+  const activeViewport = useBuilderStore((s) => s.activeViewport);
+  const isThisBlockSelected = selectedBlockKey === block._key;
+
+  // ── Grid config ───────────────────────────────────────────────
+
+  const columns = block.columns || 3;
+  const gapV = block.gap_v ?? 16;
+  const gapH = block.gap_h ?? 16;
+  const aspectRatios = block.aspect_ratios?.length
+    ? block.aspect_ratios
+    : ["16/9"];
+  const borderRadius = block.border_radius || 0;
+  const projects = block.projects || [];
+  const slugs = useMemo(
+    () => projects.map((p) => p.project_slug),
+    [projects],
+  );
+  const thumbMap = useProjectThumbnails(slugs);
+
+  // ── Stable refs for event handlers ────────────────────────────
+
+  const blockRef = useRef(block);
+  blockRef.current = block;
+  const updateBlockRef = useRef(updateBlock);
+  updateBlockRef.current = updateBlock;
+  const pushSnapshotRef = useRef(_pushSnapshot);
+  pushSnapshotRef.current = _pushSnapshot;
+  const containerWidthRef = useRef(containerWidth);
+  containerWidthRef.current = containerWidth;
+  const dragStateRef = useRef(dragState);
+  dragStateRef.current = dragState;
+
+  // Timer & cleanup refs
+  const holdTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const holdCleanupRef = useRef<(() => void) | null>(null);
+  const cancelTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const cancelRafRef = useRef<number | null>(null);
+  const didDragRef = useRef(false);
+
+  // ── Measure container width via ResizeObserver ────────────────
+  // Uses a callback ref so the observer is set up the instant the DOM
+  // node is attached (avoids the stale-ref problem with useEffect+[]).
+  // A rAF retry loop covers the case where the initial measurement is
+  // 0 due to CSS containment or pending layout from the canvas transform.
+
+  const containerCallbackRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      // Disconnect previous observer
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+
+      containerRef.current = node;
+      if (!node) return;
+
+      const ro = new ResizeObserver((entries) => {
+        for (const entry of entries) {
+          const w =
+            entry.contentBoxSize?.[0]?.inlineSize ?? entry.contentRect.width;
+          if (w > 0) setContainerWidth(w);
+        }
+      });
+      roRef.current = ro;
+      ro.observe(node);
+
+      // Immediate measurement + rAF retry for delayed layout
+      const measure = () => {
+        const w = node.clientWidth;
+        if (w > 0) {
+          setContainerWidth(w);
+        }
+      };
+      measure();
+      // Retry once layout is flushed (covers CSS containment delay)
+      requestAnimationFrame(measure);
+    },
+    [],
+  );
+
+  // Disconnect on unmount
+  useEffect(
+    () => () => {
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+    },
+    [],
+  );
+
+  // ── Masonry computation ───────────────────────────────────────
+
+  const masonryItems: MasonryItem[] = useMemo(
+    () =>
+      projects.map((item, i) => {
+        // Resolve per-card override for the frame's viewport (not the global active one)
+        let override = item.aspect_ratio_override;
+        if (frameViewport !== "desktop") {
+          const vp = frameViewport as "tablet" | "phone";
+          const vpOverride = item.responsive?.[vp]?.aspect_ratio_override;
+          if (vpOverride !== undefined) override = vpOverride;
+        }
+        return {
+          key: item._key,
+          aspectRatio: resolveItemRatio(i, override, {
+            gridRatios: aspectRatios,
+          }),
+        };
+      }),
+    [projects, aspectRatios, frameViewport],
+  );
+
+  const masonry: MasonryOutput = useMemo(() => {
+    if (containerWidth <= 0 || masonryItems.length === 0)
+      return { items: [], totalHeight: 0 };
+    return computeMasonry(masonryItems, { columns, gapH, gapV, containerWidth });
+  }, [masonryItems, columns, gapH, gapV, containerWidth]);
+
+  const masonryRef = useRef(masonry);
+  masonryRef.current = masonry;
+
+  const masonryByKey = useMemo(() => {
+    const map = new Map<string, (typeof masonry.items)[0]>();
+    for (const item of masonry.items) map.set(item.key, item);
+    return map;
+  }, [masonry]);
+
+  // ── Drag: initiate ────────────────────────────────────────────
+
+  const initiateDrag = useCallback(
+    (
+      key: string,
+      clientX: number,
+      clientY: number,
+      cardEl: HTMLDivElement,
+    ) => {
+      // Clean up any pending hold
+      if (holdCleanupRef.current) {
+        holdCleanupRef.current();
+        holdCleanupRef.current = null;
+      }
+      // Clean up any cancel animation in progress
+      if (cancelTimerRef.current) {
+        clearTimeout(cancelTimerRef.current);
+        cancelTimerRef.current = null;
+      }
+      if (cancelRafRef.current) {
+        cancelAnimationFrame(cancelRafRef.current);
+        cancelRafRef.current = null;
+      }
+
+      const rect = cardEl.getBoundingClientRect();
+      didDragRef.current = true;
+      setDragState({
+        phase: "grabbed",
+        draggedKey: key,
+        hoverTargetKey: null,
+        mouseX: clientX,
+        mouseY: clientY,
+        startMouseX: clientX,
+        startMouseY: clientY,
+        offsetX: clientX - rect.left,
+        offsetY: clientY - rect.top,
+        cardWidth: rect.width,
+        cardHeight: rect.height,
+        origScreenX: rect.left,
+        origScreenY: rect.top,
+      });
+    },
+    [],
+  );
+
+  const handleDragStart = useCallback(
+    (
+      key: string,
+      e: React.PointerEvent,
+      cardEl: HTMLDivElement,
+      fromHandle: boolean,
+    ) => {
+      if (fromHandle) {
+        e.preventDefault();
+        initiateDrag(key, e.clientX, e.clientY, cardEl);
+        return;
+      }
+
+      // Card body → hold-to-drag
+      const cx = e.clientX;
+      const cy = e.clientY;
+      didDragRef.current = false;
+
+      // Clean any previous pending hold
+      if (holdCleanupRef.current) holdCleanupRef.current();
+
+      const cleanup = () => {
+        if (holdTimerRef.current) {
+          clearTimeout(holdTimerRef.current);
+          holdTimerRef.current = null;
+        }
+        window.removeEventListener("pointerup", onEarlyRelease);
+        window.removeEventListener("pointermove", onEarlyMove);
+        holdCleanupRef.current = null;
+      };
+
+      const onEarlyRelease = () => cleanup();
+
+      const onEarlyMove = (ev: PointerEvent) => {
+        // If user moved > 10px before hold time, cancel (not a drag intent)
+        const dx = ev.clientX - cx;
+        const dy = ev.clientY - cy;
+        if (dx * dx + dy * dy > 100) cleanup();
+      };
+
+      holdTimerRef.current = setTimeout(() => {
+        holdTimerRef.current = null;
+        window.removeEventListener("pointerup", onEarlyRelease);
+        window.removeEventListener("pointermove", onEarlyMove);
+        holdCleanupRef.current = null;
+        initiateDrag(key, cx, cy, cardEl);
+      }, HOLD_DELAY);
+
+      window.addEventListener("pointerup", onEarlyRelease);
+      window.addEventListener("pointermove", onEarlyMove);
+      holdCleanupRef.current = cleanup;
+    },
+    [initiateDrag],
+  );
+
+  // ── Drag: click handler (selection) ───────────────────────────
+
+  const handleSelect = useCallback(
+    (key: string) => {
+      // Suppress click that follows a completed drag
+      if (didDragRef.current) {
+        didDragRef.current = false;
+        return;
+      }
+      selectProjectCard(selectedProjectCardKey === key ? null : key);
+    },
+    [selectProjectCard, selectedProjectCardKey],
+  );
+
+  // ── Global pointer handlers during drag ───────────────────────
+
+  const hasDrag = dragState !== null;
+
+  useEffect(() => {
+    if (!hasDrag) return;
+
+    const onMove = (e: PointerEvent) => {
+      setDragState((prev) => {
+        if (!prev || prev.phase === "cancelling") return prev;
+
+        const next: DragState = {
+          ...prev,
+          mouseX: e.clientX,
+          mouseY: e.clientY,
+        };
+
+        // Transition: grabbed → dragging on sufficient movement
+        if (prev.phase === "grabbed") {
+          const dx = e.clientX - prev.startMouseX;
+          const dy = e.clientY - prev.startMouseY;
+          if (dx * dx + dy * dy > MOVE_THRESHOLD_SQ) {
+            next.phase = "dragging";
+          }
+        }
+
+        // Coordinate-based hit-testing for drop targets
+        if (next.phase === "dragging" && containerRef.current) {
+          next.hoverTargetKey = hitTestCards(
+            e.clientX,
+            e.clientY,
+            containerRef.current,
+            containerWidthRef.current,
+            masonryRef.current,
+            prev.draggedKey,
+          );
+        }
+
+        return next;
+      });
+    };
+
+    const onUp = () => {
+      const prev = dragStateRef.current;
+      if (!prev) {
+        setDragState(null);
+        return;
+      }
+
+      // Grabbed with no movement → cancel (no visual action, allow click through)
+      if (prev.phase === "grabbed") {
+        setDragState(null);
+        setTimeout(() => {
+          didDragRef.current = false;
+        }, 0);
+        return;
+      }
+
+      // Dragging with a valid drop target → swap
+      if (prev.phase === "dragging" && prev.hoverTargetKey) {
+        const blk = blockRef.current;
+        const arr = [...(blk.projects || [])];
+        const fromIdx = arr.findIndex((p) => p._key === prev.draggedKey);
+        const toIdx = arr.findIndex((p) => p._key === prev.hoverTargetKey);
+        if (fromIdx !== -1 && toIdx !== -1 && fromIdx !== toIdx) {
+          pushSnapshotRef.current();
+          [arr[fromIdx], arr[toIdx]] = [arr[toIdx], arr[fromIdx]];
+          updateBlockRef.current(blk._key, {
+            projects: arr,
+          } as Partial<ProjectGridBlock>);
+        }
+        setDragState(null);
+        setTimeout(() => {
+          didDragRef.current = false;
+        }, 0);
+        return;
+      }
+
+      // Dragging with no target → cancel with fly-back animation
+      if (prev.phase === "dragging") {
+        setDragState({ ...prev, phase: "cancelling", hoverTargetKey: null });
+        setTimeout(() => {
+          didDragRef.current = false;
+        }, 0);
+        return;
+      }
+
+      // Fallback: clear
+      setDragState(null);
+    };
+
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    return () => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+    };
+  }, [hasDrag]);
+
+  // ── Cancel animation: fly ghost back to original position ─────
+
+  useEffect(() => {
+    if (dragState?.phase !== "cancelling") return;
+
+    // Double rAF ensures the transition CSS is painted before position change
+    cancelRafRef.current = requestAnimationFrame(() => {
+      cancelRafRef.current = requestAnimationFrame(() => {
+        setDragState((prev) => {
+          if (prev?.phase !== "cancelling") return prev;
+          return {
+            ...prev,
+            mouseX: prev.origScreenX + prev.offsetX,
+            mouseY: prev.origScreenY + prev.offsetY,
+          };
+        });
+        cancelRafRef.current = null;
+      });
+    });
+
+    // Clear state after transition completes
+    cancelTimerRef.current = setTimeout(() => {
+      setDragState(null);
+      cancelTimerRef.current = null;
+    }, CANCEL_DURATION + 50);
+
+    return () => {
+      if (cancelRafRef.current) cancelAnimationFrame(cancelRafRef.current);
+      if (cancelTimerRef.current) {
+        clearTimeout(cancelTimerRef.current);
+        cancelTimerRef.current = null;
+      }
+    };
+  }, [dragState?.phase]);
+
+  // ── Cleanup on unmount ────────────────────────────────────────
+
+  useEffect(
+    () => () => {
+      if (holdTimerRef.current) clearTimeout(holdTimerRef.current);
+      if (holdCleanupRef.current) holdCleanupRef.current();
+      if (cancelTimerRef.current) clearTimeout(cancelTimerRef.current);
+      if (cancelRafRef.current) cancelAnimationFrame(cancelRafRef.current);
+    },
+    [],
+  );
+
+  // ── Container click → clear card selection ────────────────────
+
+  const handleContainerClick = useCallback(
+    (e: React.MouseEvent) => {
+      if (e.target === e.currentTarget) selectProjectCard(null);
+    },
+    [selectProjectCard],
+  );
+
+  // ── Derived drag values ───────────────────────────────────────
+
+  const draggedKey = dragState?.draggedKey ?? null;
+  const hoverTargetKey =
+    dragState?.phase === "dragging" ? dragState.hoverTargetKey : null;
+  const dragPhase = dragState?.phase ?? null;
+  const isAnyDragActive = dragState !== null;
+  const draggedItem = dragState
+    ? projects.find((p) => p._key === dragState.draggedKey)
+    : null;
+
+  // ── Empty state ───────────────────────────────────────────────
+
+  if (projects.length === 0) {
+    return (
+      <div
+        className="border-2 border-dashed border-neutral-300 rounded-lg py-12 flex flex-col items-center justify-center"
+        style={{ minHeight: 200 }}
+      >
+        <div className="text-neutral-400 mb-2">
+          <svg
+            width="32"
+            height="32"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.5"
+          >
+            <rect x="3" y="3" width="7" height="7" />
+            <rect x="14" y="3" width="7" height="7" />
+            <rect x="3" y="14" width="7" height="7" />
+            <rect x="14" y="14" width="7" height="7" />
+          </svg>
+        </div>
+        <span className="text-xs text-neutral-400 font-medium">
+          Project Grid
+        </span>
+        <span className="text-[10px] text-neutral-400 mt-0.5">
+          Select projects in the settings panel
+        </span>
+      </div>
+    );
+  }
+
+  // ── Render ────────────────────────────────────────────────────
+
+  return (
+    <div ref={containerCallbackRef} onClick={handleContainerClick}>
+      {/* Masonry container with absolute positioning */}
+      <div
+        style={{
+          position: "relative",
+          height: masonry.totalHeight > 0 ? masonry.totalHeight : undefined,
+          minHeight: masonry.totalHeight > 0 ? undefined : 100,
+        }}
+      >
+        {projects.map((item) => {
+          const mr = masonryByKey.get(item._key);
+          if (!mr) return null;
+
+          const isThisDragged = draggedKey === item._key;
+          const showGrabbed = isThisDragged && dragPhase === "grabbed";
+          const showPlaceholder =
+            isThisDragged &&
+            (dragPhase === "dragging" || dragPhase === "cancelling");
+
+          return (
+            <div
+              key={item._key}
+              style={{
+                position: "absolute",
+                left: mr.x,
+                top: mr.y,
+                width: mr.width,
+                height: mr.height,
+                // Smooth position transitions after swap (disabled during active drag)
+                transition:
+                  isAnyDragActive && !showPlaceholder
+                    ? undefined
+                    : "left 200ms ease, top 200ms ease",
+              }}
+            >
+              <ProjectCardWrapper
+                item={item}
+                thumbMap={thumbMap}
+                borderRadius={borderRadius}
+                cardWidth={mr.width}
+                cardHeight={mr.height}
+                isGrabbed={showGrabbed}
+                isDragging={showPlaceholder}
+                isDropTarget={hoverTargetKey === item._key}
+                isSelected={
+                  isThisBlockSelected &&
+                  selectedProjectCardKey === item._key
+                }
+                isAnyDragActive={isAnyDragActive}
+                onPointerDown={handleDragStart}
+                onSelect={handleSelect}
+              />
+            </div>
+          );
+        })}
+      </div>
+
+      {/* Ghost card — portaled to body to escape canvas CSS transform
+          (transforms create a new containing block, breaking position:fixed) */}
+      {dragState &&
+        (dragState.phase === "dragging" || dragState.phase === "cancelling") &&
+        draggedItem &&
+        createPortal(
+          <GhostCard
+            item={draggedItem}
+            thumbMap={thumbMap}
+            borderRadius={borderRadius}
+            dragState={dragState}
+          />,
+          document.body,
+        )}
+    </div>
+  );
+}