@blorkfield/overlay-core 0.8.1 → 0.8.3

package/README.md

@@ -312,6 +312,52 @@ const tagged = scene.getObjectIdsByTag('falling');
 const allTags = scene.getAllTags();
 ```
 
+## Mouse Position and Grab API
+
+For scenarios where mouse input comes from an external source (e.g., system-wide mouse capture via WebSocket), you can programmatically control mouse position and grab/release behavior. This is useful when the canvas is positioned with an offset from the screen origin.
+
+### Setting Mouse Position
+
+```typescript
+// Apply your offset and set the adjusted position
+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
+
+```typescript
+// Grab object at current mouse position (only 'grabable' tagged objects)
+const grabbedId = scene.startGrab();
+if (grabbedId) {
+  console.log(`Grabbed: ${grabbedId}`);
+}
+
+// Update mouse position while dragging - object follows automatically
+scene.setFollowTarget('mouse', newX, newY);
+
+// Release the grabbed object
+scene.endGrab();
+
+// Check what's currently grabbed
+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 |
+
 ## Configuration
 
 ### Scene Config

package/dist/index.cjs

@@ -2327,14 +2327,6 @@ var OverlayScene = class {
     }
     return Array.from(tagsSet).sort();
   }
-  /**
-   * Set the mouse position for follow behavior.
-   * This overrides the browser mouse position for the 'follow' and 'follow-mouse' tags.
-   * @deprecated Use setFollowTarget('mouse', x, y) instead
-   */
-  setMousePosition(x, y) {
-    this.setFollowTarget("mouse", x, y);
-  }
   /**
    * Set a follow target position. Objects with 'follow-{key}' tag will
    * automatically move toward this target each frame.
@@ -2384,6 +2376,7 @@ var OverlayScene = class {
     for (const body of bodies) {
       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,
@@ -2401,6 +2394,9 @@ var OverlayScene = class {
     if (this.mouseConstraint) {
       this.mouseConstraint.constraint.bodyB = null;
     }
+    if (this.mouse) {
+      this.mouse.button = -1;
+    }
   }
   /**
    * Get the ID of the currently grabbed object.