@blorkfield/overlay-core 0.8.0 → 0.8.2

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.
@@ -2344,6 +2336,12 @@ 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;
+    }
   }
   /**
    * Remove a follow target. Objects with the corresponding tag will stop following.
@@ -2359,6 +2357,52 @@ var OverlayScene = class {
   getFollowTargetKeys() {
     return Array.from(this.followTargets.keys());
   }
+  // ==================== GRAB/DRAG METHODS ====================
+  /**
+   * Programmatically grab an object at the current mouse position.
+   * Uses the externally set mouse position (via setFollowTarget('mouse', x, y))
+   * or the native canvas mouse position if no external position is set.
+   * Only objects with the 'grabable' tag can be grabbed.
+   * @returns The ID of the grabbed object, or null if no grabable object at position
+   */
+  startGrab() {
+    if (!this.mouseConstraint || !this.mouse) return null;
+    const mouseTarget = this.followTargets.get("mouse");
+    const position = mouseTarget ?? { x: this.mouse.position.x, y: this.mouse.position.y };
+    const bodies = import_matter_js5.default.Query.point(
+      import_matter_js5.default.Composite.allBodies(this.engine.world),
+      position
+    );
+    for (const body of bodies) {
+      const entry = this.findObjectByBody(body);
+      if (entry && entry.tags.includes("grabable")) {
+        this.mouseConstraint.constraint.bodyB = entry.body;
+        this.mouseConstraint.constraint.pointB = {
+          x: position.x - entry.body.position.x,
+          y: position.y - entry.body.position.y
+        };
+        return entry.id;
+      }
+    }
+    return null;
+  }
+  /**
+   * Release any currently grabbed object.
+   */
+  endGrab() {
+    if (this.mouseConstraint) {
+      this.mouseConstraint.constraint.bodyB = null;
+    }
+  }
+  /**
+   * Get the ID of the currently grabbed object.
+   * @returns The ID of the grabbed object, or null if nothing is grabbed
+   */
+  getGrabbedObject() {
+    if (!this.mouseConstraint?.constraint.bodyB) return null;
+    const entry = this.findObjectByBody(this.mouseConstraint.constraint.bodyB);
+    return entry?.id ?? null;
+  }
   // ==================== PHYSICS MANIPULATION METHODS ====================
   /**
    * Apply a force to an object.