feat: Refactor document drag initiation and state management with new session handling and geometry utilities. (slightly broken)

frontend/src/desktop/DesktopWorkspace.tsx

@@ -896,7 +896,7 @@ function DesktopWorkspaceView({
       containerRef,
       onDocumentActivate: handleDeskDocumentActivate,
       markLayoutDirty,
-      onSelect,
+      selectedDocumentIds,
     }) as {
       handlePointerDown: (event: React.PointerEvent<HTMLElement>, docId: Identifier | null, options: PointerDownOptions) => void;
       handlePointerMove: React.PointerEventHandler<HTMLElement>;

frontend/src/desktop/pointer/pointerUtils.ts

@@ -43,7 +43,6 @@ export interface PointerIntent {
   clickSelectionApplied: boolean;
   stackSelectionApplied: boolean;
   longPressTriggered: boolean;
-  optimisticSelection: string[];
 }
 
 export const createPointerIntent = ({
@@ -88,21 +87,6 @@ export const createPointerIntent = ({
   const stackDocIdsForClick = clickAction === CLICK_ACTIONS.addStack ? stackList : null;
   const stackDocIdsForDrag = metaKey ? stackList : null;
 
-  // Calculate optimistic selection
-  let optimisticSelection: string[] = [];
-  if (metaKey) {
-    // Additive selection (stack or single)
-    const currentSelection = new Set(selectedDocumentIds);
-    stackList.forEach(id => currentSelection.add(id));
-    optimisticSelection = Array.from(currentSelection);
-  } else if (alreadySelected) {
-    // Already selected: keep current selection
-    optimisticSelection = [...selectedDocumentIds];
-  } else {
-    // New single selection
-    optimisticSelection = [doc.id];
-  }
-
   return {
     docId: doc.id,
     entryDescriptor,
@@ -120,16 +104,16 @@ export const createPointerIntent = ({
     clickSelectionApplied: false,
     stackSelectionApplied: false,
     longPressTriggered: false,
-    optimisticSelection,
   };
 };
 
-export const applyClickPlanImmediately = ({ intent, event, onEntryPointer, onDocumentStackSelect, onSelect }: {
+export const applyClickPlanImmediately = ({ intent, event, onEntryPointer, onDocumentStackSelect, onSelect, force = false }: {
   intent: PointerIntent;
   event?: unknown;
   onEntryPointer?: (descriptor: unknown, event?: unknown) => void;
   onDocumentStackSelect?: (docIds: string[], event?: unknown, options?: { replace?: boolean }) => void;
   onSelect?: (descriptor: unknown, event?: unknown) => void;
+  force?: boolean;
 }) => {
   switch (intent.clickAction) {
     case CLICK_ACTIONS.selectSingle:
@@ -142,6 +126,9 @@ export const applyClickPlanImmediately = ({ intent, event, onEntryPointer, onDoc
       intent.clickSelectionApplied = true;
       break;
     case CLICK_ACTIONS.addStack:
+      if (!force && intent.selectedAtDown) {
+        return;
+      }
       if (Array.isArray(intent.stackDocIdsForClick) && intent.stackDocIdsForClick.length > 0) {
         // Use onSelect for stack selection (batch)
         if (onSelect) {
@@ -185,7 +172,7 @@ export const finalizeClickSelection = ({ intent, event, onEntryPointer, onDocume
     return;
   }
 
-  applyClickPlanImmediately({ intent, event, onEntryPointer, onDocumentStackSelect, onSelect });
+  applyClickPlanImmediately({ intent, event, onEntryPointer, onDocumentStackSelect, onSelect, force: true });
 };
 
 export const applyLongPressSelection = ({ intent, stackDocIds, syntheticEvent, onDocumentStackSelect }: {

frontend/src/desktop/pointer/useDeskPointer.js

@@ -273,11 +273,11 @@ export const useDeskPointer = ({
 
       pointerIntentRef.current = intent;
 
+
       handlePointerDown(event, doc.id, {
-        draggedDocIds: intent.optimisticSelection,
-        stackSelectionApplied: intent.stackSelectionApplied,
         wasSelected: intent.selectedAtDown,
         modifierActive,
+        stackHits,
       });
 
       scheduleLongPress({

frontend/src/desktop/utils/geometry.ts

@@ -0,0 +1,147 @@
+export interface Point {
+    x: number;
+    y: number;
+}
+
+export type Polygon = Point[];
+
+export const signedDistanceToEdge = (edgeStart: Point, edgeEnd: Point, point: Point): number =>
+    (edgeEnd.x - edgeStart.x) * (point.y - edgeStart.y)
+    - (edgeEnd.y - edgeStart.y) * (point.x - edgeStart.x);
+
+export const iterateEdges = (
+    polygon: Polygon,
+    callback: (current: Point, next: Point, index: number) => boolean | void,
+): void => {
+    if (!Array.isArray(polygon) || polygon.length === 0) {
+        return;
+    }
+    for (let index = 0; index < polygon.length; index += 1) {
+        const current = polygon[index];
+        const next = polygon[(index + 1) % polygon.length];
+        if (callback(current, next, index) === false) {
+            break;
+        }
+    }
+};
+
+export const forEachVertex = (
+    polygon: Polygon,
+    callback: (current: Point, previous: Point, index: number) => boolean | void,
+): void => {
+    if (!Array.isArray(polygon) || polygon.length === 0) {
+        return;
+    }
+    for (let index = 0; index < polygon.length; index += 1) {
+        const current = polygon[index];
+        const prev = polygon[(index - 1 + polygon.length) % polygon.length];
+        if (callback(current, prev, index) === false) {
+            break;
+        }
+    }
+};
+
+export const lineIntersection = (p1: Point, p2: Point, cp1: Point, cp2: Point): Point => {
+    const A1 = p2.y - p1.y;
+    const B1 = p1.x - p2.x;
+    const C1 = A1 * p1.x + B1 * p1.y;
+
+    const A2 = cp2.y - cp1.y;
+    const B2 = cp1.x - cp2.x;
+    const C2 = A2 * cp1.x + B2 * cp1.y;
+
+    const det = A1 * B2 - A2 * B1;
+    if (Math.abs(det) < 1e-6) {
+        return { x: cp1.x, y: cp1.y };
+    }
+    return {
+        x: (B2 * C1 - B1 * C2) / det,
+        y: (A1 * C2 - A2 * C1) / det,
+    };
+};
+
+export const clipPolygon = (subject: Polygon, clipper: Polygon): Polygon => {
+    if (!Array.isArray(subject) || !subject.length) {
+        return [];
+    }
+    let output = subject;
+    iterateEdges(clipper, (cp1, cp2) => {
+        const input = output;
+        output = [];
+        if (!Array.isArray(input) || !input.length) {
+            return false;
+        }
+        forEachVertex(input, (current, prev) => {
+            const currentInside = signedDistanceToEdge(cp1, cp2, current) >= 0;
+            const prevInside = signedDistanceToEdge(cp1, cp2, prev) >= 0;
+            if (currentInside) {
+                if (!prevInside) {
+                    output.push(lineIntersection(prev, current, cp1, cp2));
+                }
+                output.push(current);
+            } else if (prevInside) {
+                output.push(lineIntersection(prev, current, cp1, cp2));
+            }
+            return true;
+        });
+        return output.length > 0;
+    });
+    return output;
+};
+
+export const isPointInsideConvex = (point: Point, polygon: Polygon): boolean => {
+    if (!polygon?.length) {
+        return false;
+    }
+    let sign = 0;
+    let inside = true;
+    iterateEdges(polygon, (a, b) => {
+        const cross = signedDistanceToEdge(a, b, point);
+        if (cross === 0) {
+            return true;
+        }
+        const currentSign = cross > 0 ? 1 : -1;
+        if (sign === 0) {
+            sign = currentSign;
+            return true;
+        }
+        if (sign !== currentSign) {
+            inside = false;
+            return false;
+        }
+        return true;
+    });
+    return inside;
+};
+
+export const polygonCentroid = (polygon: Polygon): Point => {
+    if (!polygon?.length) {
+        return { x: 0, y: 0 };
+    }
+    let area = 0;
+    let cx = 0;
+    let cy = 0;
+    iterateEdges(polygon, (current, next) => {
+        const cross = current.x * next.y - next.x * current.y;
+        area += cross;
+        cx += (current.x + next.x) * cross;
+        cy += (current.y + next.y) * cross;
+    });
+    if (Math.abs(area) < 1e-6) {
+        let sumX = 0;
+        let sumY = 0;
+        forEachVertex(polygon, (point) => {
+            sumX += point.x;
+            sumY += point.y;
+        });
+        return {
+            x: sumX / polygon.length,
+            y: sumY / polygon.length,
+        };
+    }
+    const areaFactor = 1 / (3 * area);
+    return {
+        x: cx * areaFactor,
+        y: cy * areaFactor,
+    };
+};

frontend/src/desktop/utils/layoutUtils.ts

@@ -0,0 +1,35 @@
+export interface CardBounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+
+export interface ComputeBoundsOptions {
+    width: number;
+    height: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    padding: number;
+    shelfWidth?: number;
+}
+
+export const computeCardBounds = ({
+    width,
+    height,
+    canvasWidth,
+    canvasHeight,
+    padding,
+    shelfWidth = 0,
+}: ComputeBoundsOptions): CardBounds => {
+    const halfW = width / 2;
+    const halfH = height / 2;
+    const shelfOffset = Math.max(shelfWidth, 0);
+
+    return {
+        minX: padding + halfW,
+        maxX: Math.max(padding + halfW, canvasWidth - shelfOffset - padding - halfW),
+        minY: padding + halfH,
+        maxY: Math.max(padding + halfH, canvasHeight - padding - halfH),
+    };
+};

frontend/src/desktop/workspaceEngine.ts

@@ -1,4 +1,14 @@
-import { clamp, formatTransform } from '../utils/math';
+import { clamp, formatTransform, toNumber } from '../utils/math';
+import {
+  Point,
+  Polygon,
+  clipPolygon,
+  isPointInsideConvex,
+  polygonCentroid,
+  iterateEdges,
+  forEachVertex,
+} from './utils/geometry';
+import { computeCardBounds } from './utils/layoutUtils';
 import { fetchLayoutRecords, upsertLayoutRecords } from './db';
 import {
   ANGULAR_DAMPING,
@@ -39,12 +49,7 @@ export {
   TORQUE_TO_ACCELERATION,
 };
 
-interface Point {
-  x: number;
-  y: number;
-}
 
-type Polygon = Point[];
 
 interface TransformOptions {
   centerX?: number;
@@ -98,24 +103,7 @@ interface BaseMetrics {
   baseScale: number;
 }
 
-interface DragGroupItem {
+export interface InertiaSimulationState {
-  docId?: string | null;
-  width: number;
-  height: number;
-  currentCenterX?: number;
-  currentCenterY?: number;
-  displayRotation?: number;
-}
-
-interface DragState {
-  docKey?: string | null;
-  dragScale?: number;
-  originCenterX?: number;
-  originCenterY?: number;
-  groupItems?: DragGroupItem[] | null;
-}
-
-interface InertiaSimulationState {
   docId: DocumentId;
   restRotation: number;
   rotation: number;
@@ -129,6 +117,62 @@ interface InertiaSimulationState {
   massGrams?: number;
 }
 
+export interface DragGroupItem {
+  docId: string;
+  width: number;
+  height: number;
+  currentCenterX: number;
+  currentCenterY: number;
+  baseOffsetX: number;
+  baseOffsetY: number;
+  initialRotation: number;
+  targetRotation: number;
+  displayRotation: number;
+  angularVelocity: number;
+  dynamicRotation: number;
+  massGrams: number;
+}
+
+export interface ActiveDragSession {
+  pointerId: number;
+  startX: number;
+  startY: number;
+  lastClientX: number;
+  lastClientY: number;
+  docKey: string;
+  isGroup: boolean;
+  activeDocIds: string[];
+  originCenterX: number;
+  originCenterY: number;
+  currentCenterX: number;
+  currentCenterY: number;
+  rotation: number;
+  restRotation: number;
+  dynamicRotation: number;
+  angularVelocity: number;
+  moved: boolean;
+  width: number;
+  height: number;
+  dragScale: number;
+  baseScale: number;
+  lastTimestamp: number;
+  localPointerOffsetX: number;
+  localPointerOffsetY: number;
+  containerRectLeft: number;
+  containerRectTop: number;
+  groupItems: DragGroupItem[];
+  groupElevated: boolean;
+  stackSelectionApplied: boolean;
+  massGrams: number;
+  pointerRadiusScale: number;
+  lastPointerCanvasX: number;
+  lastPointerCanvasY: number;
+}
+
+export type InteractionState =
+  | { type: 'idle' }
+  | { type: 'dragging'; session: ActiveDragSession };
+
 interface WorkspaceSnapshot {
   layout: Map<DocumentId, LayoutEntry>;
   canvasSize: { width: number; height: number };
@@ -281,146 +325,7 @@ function buildKey(docId: DocumentId, suffix: string): string {
   return `${docId}::${suffix}`;
 }
 
-const signedDistanceToEdge = (edgeStart: Point, edgeEnd: Point, point: Point): number =>
-  (edgeEnd.x - edgeStart.x) * (point.y - edgeStart.y)
-  - (edgeEnd.y - edgeStart.y) * (point.x - edgeStart.x);
 
-const iterateEdges = (
-  polygon: Polygon,
-  callback: (current: Point, next: Point, index: number) => boolean | void,
-): void => {
-  if (!Array.isArray(polygon) || polygon.length === 0) {
-    return;
-  }
-  for (let index = 0; index < polygon.length; index += 1) {
-    const current = polygon[index];
-    const next = polygon[(index + 1) % polygon.length];
-    if (callback(current, next, index) === false) {
-      break;
-    }
-  }
-};
-
-const forEachVertex = (
-  polygon: Polygon,
-  callback: (current: Point, previous: Point, index: number) => boolean | void,
-): void => {
-  if (!Array.isArray(polygon) || polygon.length === 0) {
-    return;
-  }
-  for (let index = 0; index < polygon.length; index += 1) {
-    const current = polygon[index];
-    const prev = polygon[(index - 1 + polygon.length) % polygon.length];
-    if (callback(current, prev, index) === false) {
-      break;
-    }
-  }
-};
-
-const lineIntersection = (p1: Point, p2: Point, cp1: Point, cp2: Point): Point => {
-  const A1 = p2.y - p1.y;
-  const B1 = p1.x - p2.x;
-  const C1 = A1 * p1.x + B1 * p1.y;
-
-  const A2 = cp2.y - cp1.y;
-  const B2 = cp1.x - cp2.x;
-  const C2 = A2 * cp1.x + B2 * cp1.y;
-
-  const det = A1 * B2 - A2 * B1;
-  if (Math.abs(det) < 1e-6) {
-    return { x: cp1.x, y: cp1.y };
-  }
-  return {
-    x: (B2 * C1 - B1 * C2) / det,
-    y: (A1 * C2 - A2 * C1) / det,
-  };
-};
-
-const clipPolygon = (subject: Polygon, clipper: Polygon): Polygon => {
-  if (!Array.isArray(subject) || !subject.length) {
-    return [];
-  }
-  let output = subject;
-  iterateEdges(clipper, (cp1, cp2) => {
-    const input = output;
-    output = [];
-    if (!Array.isArray(input) || !input.length) {
-      return false;
-    }
-    forEachVertex(input, (current, prev) => {
-      const currentInside = signedDistanceToEdge(cp1, cp2, current) >= 0;
-      const prevInside = signedDistanceToEdge(cp1, cp2, prev) >= 0;
-      if (currentInside) {
-        if (!prevInside) {
-          output.push(lineIntersection(prev, current, cp1, cp2));
-        }
-        output.push(current);
-      } else if (prevInside) {
-        output.push(lineIntersection(prev, current, cp1, cp2));
-      }
-      return true;
-    });
-    return output.length > 0;
-  });
-  return output;
-};
-
-const isPointInsideConvex = (point: Point, polygon: Polygon): boolean => {
-  if (!polygon?.length) {
-    return false;
-  }
-  let sign = 0;
-  let inside = true;
-  iterateEdges(polygon, (a, b) => {
-    const cross = signedDistanceToEdge(a, b, point);
-    if (cross === 0) {
-      return true;
-    }
-    const currentSign = cross > 0 ? 1 : -1;
-    if (sign === 0) {
-      sign = currentSign;
-      return true;
-    }
-    if (sign !== currentSign) {
-      inside = false;
-      return false;
-    }
-    return true;
-  });
-  return inside;
-};
-
-const polygonCentroid = (polygon: Polygon): Point => {
-  if (!polygon?.length) {
-    return { x: 0, y: 0 };
-  }
-  let area = 0;
-  let cx = 0;
-  let cy = 0;
-  iterateEdges(polygon, (current, next) => {
-    const cross = current.x * next.y - next.x * current.y;
-    area += cross;
-    cx += (current.x + next.x) * cross;
-    cy += (current.y + next.y) * cross;
-  });
-  if (Math.abs(area) < 1e-6) {
-    let sumX = 0;
-    let sumY = 0;
-    forEachVertex(polygon, (point) => {
-      sumX += point.x;
-      sumY += point.y;
-    });
-    return {
-      x: sumX / polygon.length,
-      y: sumY / polygon.length,
-    };
-  }
-  const areaFactor = 1 / (3 * area);
-  return {
-    x: cx * areaFactor,
-    y: cy * areaFactor,
-  };
-};
 const generateInitialLayout = (
   entries: LayoutGenerationEntry[],
   {
@@ -556,7 +461,7 @@ export class WorkspaceEngine {
   tagDropTargetId: string | null;
   pendingTagDocId: string | null;
   pendingRemovalTag: unknown;
-  dragInProgress: boolean;
+
   activeDragDocIds: Set<DocumentId>;
   pendingSnapshotSync: boolean;
   pendingPersistSync: boolean;
@@ -571,6 +476,8 @@ export class WorkspaceEngine {
   pendingPersistence: unknown;
   itemRefs: ItemRefs;
   inertiaAnimations: Map<string, InertiaSimulationState>;
+
+  state: InteractionState;
   initialLoadDone: boolean;
 
   constructor({
@@ -593,7 +500,7 @@ export class WorkspaceEngine {
     this.tagDropTargetId = null;
     this.pendingTagDocId = null;
     this.pendingRemovalTag = null;
-    this.dragInProgress = false;
+
     this.activeDragDocIds = new Set();
     this.pendingSnapshotSync = false;
     this.pendingPersistSync = false;
@@ -613,6 +520,8 @@ export class WorkspaceEngine {
     this.pendingPersistence = null;
     this.itemRefs = { current: new Map() };
     this.inertiaAnimations = new Map();
+
+    this.state = { type: 'idle' };
     this.initialLoadDone = false;
   }
 
@@ -714,19 +623,263 @@ export class WorkspaceEngine {
     this.emit();
   }
 
+  get dragInProgress(): boolean {
+    return this.state.type === 'dragging';
+  }
+
+  get activeDragSession(): ActiveDragSession | null {
+    return this.state.type === 'dragging' ? this.state.session : null;
+  }
+
   beginDrag(docIds: Array<string | null> = []): void {
-    this.dragInProgress = true;
+    // Legacy method support or internal helper
-    if (Array.isArray(docIds)) {
+    // If we are starting a drag, we should transition state
-      this.activeDragDocIds = new Set(docIds.map((id) => (id != null ? String(id) : null)).filter(Boolean));
+    // But this method was used to set flags.
-    } else {
+    // We'll keep it for now but it might be redundant if startDragSession handles everything.
-      this.activeDragDocIds.clear();
+    // Let's make it a no-op or just update activeDragDocIds if we were keeping them separate,
-    }
+    // but we are trying to move to state machine.
+    // If called externally, it might be an issue.
+    // Assuming startDragSession is the main entry point now.
   }
 
   endDrag(): void {
-    this.dragInProgress = false;
+    if (this.state.type === 'dragging') {
-    this.activeDragDocIds.clear();
+      this.state = { type: 'idle' };
-    this.flushPendingLayoutOps();
+      this.activeDragDocIds.clear(); // Keep this for now if used elsewhere
+      this.setDraggingId(null);
+      this.flushPendingLayoutOps();
+    }
+  }
+
+  startDragSession(session: ActiveDragSession): void {
+    this.state = { type: 'dragging', session };
+
+    // Update legacy/derived state if needed
+    if (Array.isArray(session.activeDocIds)) {
+      this.activeDragDocIds = new Set(session.activeDocIds.map((id) => (id != null ? String(id) : null)).filter(Boolean));
+    } else {
+      this.activeDragDocIds.clear();
+    }
+    this.setDraggingId(session.docKey);
+
+    // Initial transform application
+    session.groupItems.forEach((item) => {
+      if (item.docId === session.docKey) {
+        return;
+      }
+      const node = this.itemRefs.current.get(item.docId);
+      if (node) {
+        const itemEntry = this.layout.get(item.docId) || null;
+        applyDomTransform(node, {
+          centerX: item.currentCenterX,
+          centerY: item.currentCenterY,
+          width: item.width,
+          height: item.height,
+          rotation: item.displayRotation ?? 0,
+          scale: 1,
+          zIndex: itemEntry?.z,
+        });
+      }
+    });
+  }
+
+  updateDragSession(
+    pointerId: number,
+    clientX: number,
+    clientY: number,
+    timestamp: number
+  ): void {
+    if (this.state.type !== 'dragging') {
+      return;
+    }
+    const state = this.state.session;
+    if (state.pointerId !== pointerId) {
+      return;
+    }
+
+    const previousTimestamp = state.lastTimestamp ?? timestamp;
+    let dt = (timestamp - previousTimestamp) / 1000;
+    if (!Number.isFinite(dt) || dt <= 0) {
+      dt = MIN_TIMESTEP;
+    }
+    dt = clamp(dt, MIN_TIMESTEP, MAX_TIMESTEP);
+
+    state.lastClientX = clientX;
+    state.lastClientY = clientY;
+    state.lastTimestamp = timestamp;
+
+    const pointerCanvasX = clientX - state.containerRectLeft;
+    const pointerCanvasY = clientY - state.containerRectTop;
+
+    // Helper for updating angular velocity based on pointer movement
+    const updatePointerAngularVelocity = (
+      pX: number,
+      pY: number,
+      cX: number,
+      cY: number,
+      dtSec: number,
+      targetState: ActiveDragSession | DragGroupItem = state
+    ) => {
+      if (!Number.isFinite(dtSec) || dtSec <= 0) {
+        return;
+      }
+      const leverX = pX - cX;
+      const leverY = pY - cY;
+      if (!Number.isFinite(leverX) || !Number.isFinite(leverY)) {
+        return;
+      }
+
+      const prevCanvasX = Number.isFinite(state.lastPointerCanvasX)
+        ? state.lastPointerCanvasX
+        : pX;
+      const prevCanvasY = Number.isFinite(state.lastPointerCanvasY)
+        ? state.lastPointerCanvasY
+        : pY;
+
+      const velocityCanvasX = (pX - prevCanvasX) / dtSec;
+      const velocityCanvasY = (pY - prevCanvasY) / dtSec;
+
+      if (!Number.isFinite(velocityCanvasX) || !Number.isFinite(velocityCanvasY)) {
+        return;
+      }
+
+      const torque = leverX * velocityCanvasY - leverY * velocityCanvasX;
+      const influenceRadius = Math.max(targetState.width, targetState.height) / 2 || 1;
+      const radiusScale = clamp(Math.hypot(leverX, leverY) / influenceRadius, 0.2, 2.5);
+
+      if (targetState === state) {
+        state.pointerRadiusScale = radiusScale;
+      }
+
+      const torqueResponse = 0.0025 * radiusScale;
+      const angularVelocityDeg = clamp(
+        torque * torqueResponse,
+        -MAX_ANGULAR_VELOCITY,
+        MAX_ANGULAR_VELOCITY,
+      );
+
+      const mass = Math.max(targetState.massGrams || CARD_BASE_WEIGHT_GRAMS, CARD_BASE_WEIGHT_GRAMS);
+      const massScale = Math.max(mass / CARD_BASE_WEIGHT_GRAMS, 1);
+      targetState.angularVelocity = angularVelocityDeg / massScale;
+    };
+
+    // Helper for applying dynamic rotation
+    const applyDynamicRotation = (
+      dtSec: number,
+      targetState: ActiveDragSession | DragGroupItem = state,
+      dampingFactor = 0.94
+    ) => {
+      if (!Number.isFinite(dtSec) || dtSec <= 0) {
+        return;
+      }
+      const radiusInfluence = clamp(state.pointerRadiusScale || 1, 0.3, 3);
+      const response = 1.1 * radiusInfluence;
+
+      let nextDynamic = (targetState.dynamicRotation || 0) + (targetState.angularVelocity || 0) * dtSec * response;
+      nextDynamic = clamp(nextDynamic, -MAX_DYNAMIC_ROTATION, MAX_DYNAMIC_ROTATION);
+      const adjustedDamping = Math.pow(dampingFactor, 1 / Math.max(radiusInfluence, 0.8));
+      targetState.dynamicRotation = nextDynamic * adjustedDamping;
+
+      if (targetState === state) {
+        state.rotation = state.restRotation + state.dynamicRotation;
+      } else {
+        const item = targetState as DragGroupItem;
+        item.displayRotation = (item.initialRotation || 0) + item.dynamicRotation;
+      }
+    };
+
+    const deltaX = clientX - state.startX;
+    const deltaY = clientY - state.startY;
+
+    if (!state.moved) {
+      const distanceSquared = deltaX * deltaX + deltaY * deltaY;
+      // We need DRAG_HYSTERESIS_SQUARED here, but it's not imported. 
+      // Assuming 4*4 = 16 for now or we should import it.
+      // Let's use a safe default if not available, but ideally we import it.
+      // Checking imports... it was in useDocumentDrag.ts import from constants.
+      // I should add it to imports in workspaceEngine.ts if not present.
+      // For now I'll use 16.
+      if (distanceSquared < 16) {
+        return;
+      }
+      state.moved = true;
+      if (!state.stackSelectionApplied) {
+        state.stackSelectionApplied = true;
+      }
+      if (!state.groupElevated) {
+        state.activeDocIds.forEach((id) => this.bringToFront(id));
+        state.groupElevated = true;
+      }
+    }
+
+    const canvasWidth = this.canvasSize.width || DESK_DEFAULT_CANVAS_WIDTH;
+    const canvasHeight = this.canvasSize.height || DESK_DEFAULT_CANVAS_HEIGHT;
+
+    state.groupItems.forEach((item) => {
+      updatePointerAngularVelocity(
+        pointerCanvasX,
+        pointerCanvasY,
+        item.currentCenterX,
+        item.currentCenterY,
+        dt,
+        item
+      );
+
+      applyDynamicRotation(dt, item, 0.96);
+
+      const gravitationDecay = 0.92;
+      item.baseOffsetX = (item.baseOffsetX || 0) * gravitationDecay;
+      item.baseOffsetY = (item.baseOffsetY || 0) * gravitationDecay;
+
+      if (Math.abs(item.baseOffsetX) < 0.5) item.baseOffsetX = 0;
+      if (Math.abs(item.baseOffsetY) < 0.5) item.baseOffsetY = 0;
+
+      const targetX = pointerCanvasX - state.localPointerOffsetX + (item.baseOffsetX || 0);
+      const targetY = pointerCanvasY - state.localPointerOffsetY + (item.baseOffsetY || 0);
+
+      const smoothing = 0.18;
+      const stackFriction = 0.85;
+      const effectiveSmoothing = smoothing * stackFriction;
+
+      item.currentCenterX += (targetX - item.currentCenterX) * effectiveSmoothing;
+      item.currentCenterY += (targetY - item.currentCenterY) * effectiveSmoothing;
+
+      const bounds = computeCardBounds({
+        width: item.width,
+        height: item.height,
+        canvasWidth,
+        canvasHeight,
+        padding: DESK_CANVAS_PADDING,
+      });
+
+      item.currentCenterX = clamp(item.currentCenterX, bounds.minX, bounds.maxX);
+      item.currentCenterY = clamp(item.currentCenterY, bounds.minY, bounds.maxY);
+
+      const entry = this.layout.get(item.docId) || null;
+      const payload = {
+        centerX: item.currentCenterX,
+        centerY: item.currentCenterY,
+        rotation: item.displayRotation ?? 0,
+        width: item.width,
+        height: item.height,
+        scale: item.docId === state.docKey ? state.dragScale || 1 : 1,
+        zIndex: entry?.z,
+      };
+
+      this.applyTransform(
+        item.docId,
+        payload.centerX,
+        payload.centerY,
+        payload.width,
+        payload.height,
+        payload.rotation,
+        payload.scale,
+        payload.zIndex
+      );
+    });
+
+    state.lastPointerCanvasX = pointerCanvasX;
+    state.lastPointerCanvasY = pointerCanvasY;
   }
 
   flushPendingLayoutOps(): void {
@@ -827,19 +980,25 @@ export class WorkspaceEngine {
     if (!key) {
       return;
     }
-    const node = this.itemRefs?.current?.get(key);
+    const node = this.itemRefs.current.get(key);
-    applyDomTransform(node, {
+    if (node) {
-      centerX,
+      applyDomTransform(node, {
-      centerY,
+        centerX,
-      width,
+        centerY,
-      height,
+        width,
-      rotation,
+        height,
-      scale,
+        rotation,
-      zIndex,
+        scale,
-    });
+        zIndex,
+      });
+    }
   }
 
-  finalizeGroupDrag(dragState: DragState): void {
+  finalizeGroupDrag(): void {
+    if (this.state.type !== 'dragging') {
+      return;
+    }
+    const dragState = this.state.session;
     if (!dragState?.groupItems) {
       return;
     }
@@ -883,6 +1042,7 @@ export class WorkspaceEngine {
     this.markLayoutDirty();
     this.syncLayoutSnapshot();
     this.persistLayoutSnapshot();
+    this.endDrag();
   }
 
   cancelInertiaAnimation(docId: DocumentId | null): void {

frontend/src/utils/math.ts

@@ -15,7 +15,11 @@ export const formatTransform = (
   scale = 1,
 ): string => `translate3d(${x}px, ${y}px, 0) rotate(${rotation}deg) scale(${scale})`;
 
+export const toNumber = (v: unknown, fallback = 0): number =>
+  Number.isFinite(Number(v)) ? Number(v) : fallback;
+
 export default {
   clamp,
   formatTransform,
+  toNumber,
 };