@blorkfield/overlay-core 0.8.8 → 0.8.10

package/README.md

@@ -22,13 +22,24 @@ pnpm add @blorkfield/overlay-core
 
 ### Tag Based Behavior
 
-Objects don't have fixed types. Instead, their behavior is determined by string tags:
+Objects don't have fixed types. Instead, their behavior is determined by string tags. Import the tag constants to avoid magic strings:
 
-| Tag | Behavior |
-|-----|----------|
-| `falling` | Object is dynamic and affected by gravity |
-| `window_follow` | Object follows mouse position when grounded |
-| `grabable` | Object can be dragged via mouse constraint |
+```typescript
+import { TAGS, TAG_FALLING, TAG_GRABABLE, TAG_FOLLOW_WINDOW } from '@blorkfield/overlay-core';
+
+// Use individual constants
+scene.spawnObject({ tags: [TAG_FALLING, TAG_GRABABLE], ... });
+
+// Or destructure from TAGS object
+const { FALLING, GRABABLE } = TAGS;
+scene.spawnObject({ tags: [FALLING, GRABABLE], ... });
+```
+
+| Constant | Value | Behavior |
+|----------|-------|----------|
+| `TAG_FALLING` / `TAGS.FALLING` | `'falling'` | Object is dynamic and affected by gravity |
+| `TAG_FOLLOW_WINDOW` / `TAGS.FOLLOW_WINDOW` | `'follow_window'` | Object follows mouse position when grounded |
+| `TAG_GRABABLE` / `TAGS.GRABABLE` | `'grabable'` | Object can be grabbed and moved with mouse |
 
 Without the `falling` tag, objects are static and won't move.
 
@@ -378,6 +389,8 @@ The offset calculation is your responsibility - overlay-core uses whatever posit
 
 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.
 
+Grab detection uses a two-pass approach to handle fast-moving bodies. The first pass does an exact point query at the click position. If that misses (the body tunneled through the cursor between frames), a second pass sweeps the body's recent position history (last 5 frames, 20px radius) to catch it. This means you can grab entities even when they are moving quickly.
+
 ```typescript
 // Grab object at current mouse position (only 'grabable' tagged objects)
 const grabbedId = scene.startGrab();
@@ -712,6 +725,12 @@ import type {
   UpdateCallbackData,
 
   // Logging
-  LogLevel
+  LogLevel,
+
+  // Tags
+  Tag
 } from '@blorkfield/overlay-core';
+
+// Tag constants (values, not types)
+import { TAGS, TAG_FALLING, TAG_GRABABLE, TAG_FOLLOW_WINDOW } from '@blorkfield/overlay-core';
 ```

package/dist/index.cjs

@@ -32,6 +32,10 @@ var index_exports = {};
 __export(index_exports, {
   BackgroundManager: () => BackgroundManager,
   OverlayScene: () => OverlayScene,
+  TAGS: () => TAGS,
+  TAG_FALLING: () => TAG_FALLING,
+  TAG_FOLLOW_WINDOW: () => TAG_FOLLOW_WINDOW,
+  TAG_GRABABLE: () => TAG_GRABABLE,
   clearFontCache: () => clearFontCache,
   getGlyphData: () => getGlyphData,
   getKerning: () => getKerning,
@@ -1447,6 +1451,12 @@ var OverlayScene = class {
     this.lastGrabMousePosition = null;
     this.grabbedWasDynamic = false;
     this.grabVelocity = { x: 0, y: 0 };
+    // Position history for sweep-based grab detection (catches fast-moving bodies)
+    this.bodyPositionHistory = /* @__PURE__ */ new Map();
+    this.grabHistoryFrames = 5;
+    this.grabHistoryRadius = 20;
+    // Number of physics substeps per frame — more substeps = better collision at high speeds, more CPU
+    this.substeps = 2;
     /** Handle mouse down - start grab via programmatic API */
     this.handleMouseDown = (event) => {
       const rect = this.canvas.getBoundingClientRect();
@@ -1523,6 +1533,10 @@ var OverlayScene = class {
     };
     // ==================== PRIVATE ====================
     this.loop = () => {
+      const substepDelta = 1e3 / 60 / this.substeps;
+      for (let i = 0; i < this.substeps; i++) {
+        import_matter_js5.default.Engine.update(this.engine, substepDelta);
+      }
       this.effectManager.update();
       this.checkTTLExpiration();
       this.checkDespawnBelowFloor();
@@ -1547,7 +1561,7 @@ var OverlayScene = class {
         const isDragging = this.grabbedObjectId === entry.id;
         if (!isDragging) {
           for (const tag of entry.tags) {
-            const key = tag === "window_follow" ? "mouse" : tag.startsWith("follow-") ? tag.slice(7) : null;
+            const key = tag === "follow_window" ? "mouse" : tag.startsWith("follow-") ? tag.slice(7) : null;
             if (key) {
               const target = this.followTargets.get(key);
               if (target) {
@@ -1566,6 +1580,14 @@ var OverlayScene = class {
         if (entry.domElement && entry.tags.includes("falling")) {
           this.updateDOMElementTransform(entry);
         }
+        if (entry.tags.includes("grabable") && !entry.body.isStatic) {
+          const history = this.bodyPositionHistory.get(entry.body.id) ?? [];
+          history.push({ x: entry.body.position.x, y: entry.body.position.y });
+          if (history.length > this.grabHistoryFrames) {
+            history.shift();
+          }
+          this.bodyPositionHistory.set(entry.body.id, history);
+        }
       }
       if (!this.config.debug) {
         this.drawTTFGlyphs();
@@ -1827,7 +1849,7 @@ var OverlayScene = class {
       }
     }
     if (parts.length > 0) {
-      console.log("[Pressure]", parts.join(" "));
+      logger.debug("[Pressure]", parts.join(" "));
     }
   }
   /** Calculate weighted pressure from a set of object IDs */
@@ -2004,7 +2026,6 @@ var OverlayScene = class {
   }
   start() {
     import_matter_js5.default.Render.run(this.render);
-    import_matter_js5.default.Runner.run(this.runner, this.engine);
     this.loop();
   }
   stop() {
@@ -2082,7 +2103,7 @@ var OverlayScene = class {
    * Spawn an object synchronously.
    * Object behavior is determined by tags:
    * - 'falling': Object is dynamic (affected by gravity)
-   * - 'window_follow': Object follows mouse when grounded (walks toward mouse)
+   * - 'follow_window': Object follows mouse when grounded (walks toward mouse)
    * - 'grabable': Object can be grabbed and moved with mouse
    * Without 'falling' tag, object is static.
    */
@@ -2378,6 +2399,7 @@ var OverlayScene = class {
       import_matter_js5.default.Composite.allBodies(this.engine.world),
       position
     );
+    logger.debug("OverlayScene", "Grabbed position " + position + ', had "' + bodies.length + '"');
     for (const body of bodies) {
       const entry = this.findObjectByBody(body);
       if (entry && entry.tags.includes("grabable")) {
@@ -2389,6 +2411,24 @@ var OverlayScene = class {
         return entry.id;
       }
     }
+    const r2 = this.grabHistoryRadius * this.grabHistoryRadius;
+    for (const entry of this.objects.values()) {
+      if (!entry.tags.includes("grabable")) continue;
+      const history = this.bodyPositionHistory.get(entry.body.id);
+      if (!history) continue;
+      for (const pastPos of history) {
+        const dx = position.x - pastPos.x;
+        const dy = position.y - pastPos.y;
+        if (dx * dx + dy * dy <= r2) {
+          this.grabbedObjectId = entry.id;
+          this.lastGrabMousePosition = { x: position.x, y: position.y };
+          this.grabVelocity = { x: 0, y: 0 };
+          this.grabbedWasDynamic = !entry.body.isStatic;
+          import_matter_js5.default.Body.setStatic(entry.body, true);
+          return entry.id;
+        }
+      }
+    }
     return null;
   }
   /**
@@ -2402,6 +2442,7 @@ var OverlayScene = class {
         import_matter_js5.default.Sleeping.set(entry.body, false);
         import_matter_js5.default.Body.setVelocity(entry.body, this.grabVelocity);
         import_matter_js5.default.Body.setAngularVelocity(entry.body, 0);
+        this.bodyPositionHistory.delete(entry.body.id);
       }
     }
     this.grabbedObjectId = null;
@@ -3394,10 +3435,24 @@ var OverlayScene = class {
     this.updateCallbacks.forEach((cb) => cb(data));
   }
 };
+
+// src/tags.ts
+var TAG_FALLING = "falling";
+var TAG_FOLLOW_WINDOW = "follow_window";
+var TAG_GRABABLE = "grabable";
+var TAGS = {
+  FALLING: TAG_FALLING,
+  FOLLOW_WINDOW: TAG_FOLLOW_WINDOW,
+  GRABABLE: TAG_GRABABLE
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BackgroundManager,
   OverlayScene,
+  TAGS,
+  TAG_FALLING,
+  TAG_FOLLOW_WINDOW,
+  TAG_GRABABLE,
   clearFontCache,
   getGlyphData,
   getKerning,