@blorkfield/overlay-core 0.8.3 → 0.8.5

package/README.md

@@ -323,28 +323,27 @@ For scenarios where mouse input comes from an external source (e.g., system-wide
 const canvasX = screenMouseX - canvasOffsetX;
 const canvasY = screenMouseY - canvasOffsetY;
 scene.setFollowTarget('mouse', canvasX, canvasY);
-
-// This position is now used for:
-// - Objects with 'follow' tag (they move toward this position)
-// - Programmatic grab detection via startGrab()
-// - MouseConstraint during drag (grabbed objects follow this position)
 ```
 
 The offset calculation is your responsibility - overlay-core uses whatever position you provide.
 
 ### Programmatic Grab/Release
 
+Grab uses delta-based movement: when grabbed, the entity and mouse become linked. The entity moves BY the same amount as the mouse moves, not TO the mouse position. This ensures the entity stays at its original position on grab and follows mouse movement naturally.
+
 ```typescript
 // Grab object at current mouse position (only 'grabable' tagged objects)
 const grabbedId = scene.startGrab();
 if (grabbedId) {
+  // Entity stays at its current position, now linked to mouse
   console.log(`Grabbed: ${grabbedId}`);
 }
 
-// Update mouse position while dragging - object follows automatically
+// As mouse moves, entity moves by the same delta
+// Mouse moves +50px right → entity moves +50px right
 scene.setFollowTarget('mouse', newX, newY);
 
-// Release the grabbed object
+// Release unlinks entity from mouse
 scene.endGrab();
 
 // Check what's currently grabbed
@@ -354,9 +353,9 @@ const currentGrab = scene.getGrabbedObject(); // Returns ID or null
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `setFollowTarget('mouse', x, y)` | void | Set mouse position for follow behavior and grab detection |
-| `startGrab()` | string \| null | Grab object at current mouse position, returns object ID |
-| `endGrab()` | void | Release any currently grabbed object |
-| `getGrabbedObject()` | string \| null | Get ID of currently grabbed object |
+| `startGrab()` | string \| null | Link entity at current mouse position to mouse, returns entity ID |
+| `endGrab()` | void | Unlink currently grabbed entity |
+| `getGrabbedObject()` | string \| null | Get ID of currently grabbed entity |
 
 ## Configuration
 

package/dist/index.cjs

@@ -1443,6 +1443,8 @@ var OverlayScene = class {
     };
     // Follow targets for follow-{key} tagged objects
     this.followTargets = /* @__PURE__ */ new Map();
+    // Programmatic grab state - tracks initial positions for relative movement
+    this.grabState = null;
     /** Filter drag events - only allow grabbing objects with 'grabable' tag */
     this.handleStartDrag = (event) => {
       const body = event.body;
@@ -2337,10 +2339,21 @@ var OverlayScene = class {
   setFollowTarget(key, x, y) {
     this.followTargets.set(key, { x, y });
     if (key === "mouse" && this.mouse) {
-      this.mouse.position.x = x;
-      this.mouse.position.y = y;
-      this.mouse.absolute.x = x;
-      this.mouse.absolute.y = y;
+      if (this.grabState && this.mouseConstraint?.constraint.bodyB) {
+        const deltaX = x - this.grabState.grabMouseX;
+        const deltaY = y - this.grabState.grabMouseY;
+        const newX = this.grabState.grabBodyX + deltaX;
+        const newY = this.grabState.grabBodyY + deltaY;
+        this.mouse.position.x = newX;
+        this.mouse.position.y = newY;
+        this.mouse.absolute.x = newX;
+        this.mouse.absolute.y = newY;
+      } else {
+        this.mouse.position.x = x;
+        this.mouse.position.y = y;
+        this.mouse.absolute.x = x;
+        this.mouse.absolute.y = y;
+      }
     }
   }
   /**
@@ -2377,11 +2390,29 @@ var OverlayScene = class {
       const entry = this.findObjectByBody(body);
       if (entry && entry.tags.includes("grabable")) {
         this.mouse.button = 0;
-        this.mouseConstraint.constraint.bodyB = entry.body;
-        this.mouseConstraint.constraint.pointB = {
-          x: position.x - entry.body.position.x,
-          y: position.y - entry.body.position.y
+        this.grabState = {
+          entityId: entry.id,
+          grabMouseX: position.x,
+          grabMouseY: position.y,
+          grabBodyX: entry.body.position.x,
+          grabBodyY: entry.body.position.y
         };
+        this.mouseConstraint.constraint.pointA = {
+          x: entry.body.position.x,
+          y: entry.body.position.y
+        };
+        this.mouseConstraint.constraint.bodyB = entry.body;
+        this.mouseConstraint.constraint.pointB = { x: 0, y: 0 };
+        this.mouse.position.x = entry.body.position.x;
+        this.mouse.position.y = entry.body.position.y;
+        this.mouse.absolute.x = entry.body.position.x;
+        this.mouse.absolute.y = entry.body.position.y;
+        console.log("[overlay-core] startGrab success", {
+          entityId: entry.id,
+          mousePosition: position,
+          bodyPosition: { x: entry.body.position.x, y: entry.body.position.y },
+          grabState: this.grabState
+        });
         return entry.id;
       }
     }
@@ -2397,6 +2428,7 @@ var OverlayScene = class {
     if (this.mouse) {
       this.mouse.button = -1;
     }
+    this.grabState = null;
   }
   /**
    * Get the ID of the currently grabbed object.