@blorkfield/overlay-core 0.4.2 → 0.5.0

package/dist/index.d.cts

@@ -353,6 +353,41 @@ interface TTFTextObstacleConfig {
     /** Click to fall config - when set, letters collapse after being clicked N times */
     clickToFall?: ClickToFallConfig;
 }
+/**
+ * Configuration for attaching a DOM element to physics.
+ * The element will follow the physics body and can have pressure/shadow/click behavior.
+ */
+interface DOMObstacleConfig {
+    /** The DOM element to attach to physics */
+    element: HTMLElement;
+    /** X position of the element center */
+    x: number;
+    /** Y position of the element center */
+    y: number;
+    /** Width of the collision body (defaults to element.offsetWidth) */
+    width?: number;
+    /** Height of the collision body (defaults to element.offsetHeight) */
+    height?: number;
+    /** Tags that define object behavior */
+    tags?: string[];
+    /** Pressure threshold config - when reached, element collapses */
+    pressureThreshold?: PressureThresholdConfig;
+    /** Weight for pressure calculation (default: 1) */
+    weight?: number;
+    /** Shadow config - when enabled, a cloned element remains after collapse */
+    shadow?: ShadowConfig;
+    /** Click to fall config - when set, element collapses after being clicked N times */
+    clickToFall?: ClickToFallConfig;
+}
+/**
+ * Result of attaching a DOM element to physics
+ */
+interface DOMObstacleResult {
+    /** ID of the created physics object */
+    id: string;
+    /** The shadow element if shadow was configured (null until collapse) */
+    shadowElement: HTMLElement | null;
+}
 /**
  * Information about an available font
  */
@@ -550,6 +585,20 @@ declare class OverlayScene {
      * Check if fonts have been initialized.
      */
     areFontsInitialized(): boolean;
+    /**
+     * Attach a DOM element to physics. The element will follow the physics body
+     * and can have pressure threshold, shadow, and click-to-fall behavior.
+     *
+     * When the element collapses (becomes dynamic), its CSS transform will be
+     * updated each frame to match the physics body position and rotation.
+     *
+     * Shadow creates a cloned DOM element that stays at the original position.
+     */
+    addDOMObstacle(config: DOMObstacleConfig): DOMObstacleResult;
+    /**
+     * Get the shadow element for a DOM obstacle (available after collapse).
+     */
+    getDOMObstacleShadow(id: string): HTMLElement | null;
     /**
      * Create text obstacles from a string. Each character becomes an individual obstacle
      * with shape extracted from the corresponding letter PNG image.
@@ -639,6 +688,10 @@ declare class OverlayScene {
      * Draw TTF glyphs using canvas fillText for clean text rendering
      */
     private drawTTFGlyphs;
+    /**
+     * Update a DOM element's CSS transform to match its physics body position and rotation.
+     */
+    private updateDOMElementTransform;
     private checkTTLExpiration;
     /** Despawn objects that have fallen below the floor by the configured distance */
     private checkDespawnBelowFloor;
@@ -697,4 +750,4 @@ declare function measureText(loadedFont: LoadedFont, text: string, fontSize: num
  */
 declare function clearFontCache(): void;
 
-export { type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };
+export { type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DOMObstacleConfig, type DOMObstacleResult, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };

package/dist/index.d.ts

@@ -353,6 +353,41 @@ interface TTFTextObstacleConfig {
     /** Click to fall config - when set, letters collapse after being clicked N times */
     clickToFall?: ClickToFallConfig;
 }
+/**
+ * Configuration for attaching a DOM element to physics.
+ * The element will follow the physics body and can have pressure/shadow/click behavior.
+ */
+interface DOMObstacleConfig {
+    /** The DOM element to attach to physics */
+    element: HTMLElement;
+    /** X position of the element center */
+    x: number;
+    /** Y position of the element center */
+    y: number;
+    /** Width of the collision body (defaults to element.offsetWidth) */
+    width?: number;
+    /** Height of the collision body (defaults to element.offsetHeight) */
+    height?: number;
+    /** Tags that define object behavior */
+    tags?: string[];
+    /** Pressure threshold config - when reached, element collapses */
+    pressureThreshold?: PressureThresholdConfig;
+    /** Weight for pressure calculation (default: 1) */
+    weight?: number;
+    /** Shadow config - when enabled, a cloned element remains after collapse */
+    shadow?: ShadowConfig;
+    /** Click to fall config - when set, element collapses after being clicked N times */
+    clickToFall?: ClickToFallConfig;
+}
+/**
+ * Result of attaching a DOM element to physics
+ */
+interface DOMObstacleResult {
+    /** ID of the created physics object */
+    id: string;
+    /** The shadow element if shadow was configured (null until collapse) */
+    shadowElement: HTMLElement | null;
+}
 /**
  * Information about an available font
  */
@@ -550,6 +585,20 @@ declare class OverlayScene {
      * Check if fonts have been initialized.
      */
     areFontsInitialized(): boolean;
+    /**
+     * Attach a DOM element to physics. The element will follow the physics body
+     * and can have pressure threshold, shadow, and click-to-fall behavior.
+     *
+     * When the element collapses (becomes dynamic), its CSS transform will be
+     * updated each frame to match the physics body position and rotation.
+     *
+     * Shadow creates a cloned DOM element that stays at the original position.
+     */
+    addDOMObstacle(config: DOMObstacleConfig): DOMObstacleResult;
+    /**
+     * Get the shadow element for a DOM obstacle (available after collapse).
+     */
+    getDOMObstacleShadow(id: string): HTMLElement | null;
     /**
      * Create text obstacles from a string. Each character becomes an individual obstacle
      * with shape extracted from the corresponding letter PNG image.
@@ -639,6 +688,10 @@ declare class OverlayScene {
      * Draw TTF glyphs using canvas fillText for clean text rendering
      */
     private drawTTFGlyphs;
+    /**
+     * Update a DOM element's CSS transform to match its physics body position and rotation.
+     */
+    private updateDOMElementTransform;
     private checkTTLExpiration;
     /** Despawn objects that have fallen below the floor by the configured distance */
     private checkDespawnBelowFloor;
@@ -697,4 +750,4 @@ declare function measureText(loadedFont: LoadedFont, text: string, fontSize: num
  */
 declare function clearFontCache(): void;
 
-export { type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };
+export { type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DOMObstacleConfig, type DOMObstacleResult, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };

package/dist/index.js

@@ -1160,6 +1160,9 @@ var OverlayScene = class {
         if (this.config.wrapHorizontal && entry.tags.includes("falling")) {
           wrapHorizontal(entry.body, this.config.bounds);
         }
+        if (entry.domElement && entry.tags.includes("falling")) {
+          this.updateDOMElementTransform(entry);
+        }
       }
       if (!this.config.debug) {
         this.drawTTFGlyphs();
@@ -1194,6 +1197,13 @@ var OverlayScene = class {
       }
     });
     Matter5.Composite.add(this.engine.world, this.mouseConstraint);
+    const wheelHandler = this.mouse.mousewheel;
+    if (wheelHandler) {
+      canvas.removeEventListener("mousewheel", wheelHandler);
+      canvas.removeEventListener("DOMMouseScroll", wheelHandler);
+      canvas.removeEventListener("wheel", wheelHandler);
+    }
+    canvas.style.touchAction = "pan-x pan-y";
     Matter5.Events.on(this.mouseConstraint, "startdrag", this.handleStartDrag);
     canvas.addEventListener("click", this.handleCanvasClick);
     this.render.mouse = this.mouse;
@@ -1447,6 +1457,15 @@ var OverlayScene = class {
     if (!entry.originalPosition) return;
     const opacity = entry.shadow?.opacity ?? 0.3;
     const shadowId = `shadow-${entry.id}`;
+    if (entry.domElement) {
+      const shadowElement = entry.domElement.cloneNode(true);
+      shadowElement.style.opacity = String(opacity);
+      shadowElement.style.pointerEvents = "none";
+      shadowElement.style.transform = entry.domOriginalTransform || "";
+      entry.domElement.parentNode?.insertBefore(shadowElement, entry.domElement);
+      entry.domShadowElement = shadowElement;
+      return;
+    }
     if (entry.ttfGlyph) {
       const body = Matter5.Bodies.circle(entry.originalPosition.x, entry.originalPosition.y, 1, {
         isStatic: true,
@@ -1920,6 +1939,84 @@ var OverlayScene = class {
   areFontsInitialized() {
     return this.fontsInitialized;
   }
+  // ==================== DOM OBSTACLE METHODS ====================
+  /**
+   * Attach a DOM element to physics. The element will follow the physics body
+   * and can have pressure threshold, shadow, and click-to-fall behavior.
+   *
+   * When the element collapses (becomes dynamic), its CSS transform will be
+   * updated each frame to match the physics body position and rotation.
+   *
+   * Shadow creates a cloned DOM element that stays at the original position.
+   */
+  addDOMObstacle(config) {
+    const { element, x, y } = config;
+    const width = config.width ?? element.offsetWidth;
+    const height = config.height ?? element.offsetHeight;
+    const tags = config.tags ?? [];
+    const isStatic = !tags.includes("falling");
+    const body = Matter5.Bodies.rectangle(x, y, width, height, {
+      isStatic,
+      label: `dom-${crypto.randomUUID().slice(0, 8)}`,
+      render: { visible: false }
+      // Don't render the body, DOM element is the visual
+    });
+    const id = body.label;
+    let pressureThreshold;
+    if (config.pressureThreshold) {
+      pressureThreshold = typeof config.pressureThreshold.value === "number" ? config.pressureThreshold.value : config.pressureThreshold.value[0];
+    }
+    const shadow = config.shadow ? { opacity: config.shadow.opacity ?? 0.3 } : void 0;
+    const clicksRemaining = config.clickToFall?.clicks;
+    const originalTransform = element.style.transform || "";
+    element.style.position = "absolute";
+    element.style.transformOrigin = "center center";
+    const entry = {
+      id,
+      body,
+      tags,
+      spawnTime: performance.now(),
+      pressureThreshold,
+      weight: config.weight ?? 1,
+      shadow,
+      originalPosition: shadow || clicksRemaining !== void 0 ? { x, y } : void 0,
+      clicksRemaining,
+      domElement: element,
+      domOriginalTransform: originalTransform
+    };
+    this.objects.set(id, entry);
+    Matter5.Composite.add(this.engine.world, body);
+    if (isStatic && pressureThreshold !== void 0) {
+      this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
+    }
+    if (clicksRemaining !== void 0) {
+      const clickHandler = () => {
+        const currentEntry = this.objects.get(id);
+        if (!currentEntry) return;
+        if (currentEntry.tags.includes("falling")) return;
+        if (currentEntry.clicksRemaining === void 0) return;
+        currentEntry.clicksRemaining--;
+        logger.debug("OverlayScene", `Click on DOM element: ${currentEntry.clicksRemaining} clicks remaining`);
+        if (currentEntry.clicksRemaining <= 0) {
+          this.collapseObstacle(currentEntry);
+          element.removeEventListener("click", clickHandler);
+        }
+      };
+      element.addEventListener("click", clickHandler);
+    }
+    return {
+      id,
+      shadowElement: null
+      // Will be populated on collapse
+    };
+  }
+  /**
+   * Get the shadow element for a DOM obstacle (available after collapse).
+   */
+  getDOMObstacleShadow(id) {
+    const entry = this.objects.get(id);
+    return entry?.domShadowElement ?? null;
+  }
   // ==================== TEXT OBSTACLE METHODS ====================
   /**
    * Create text obstacles from a string. Each character becomes an individual obstacle
@@ -2416,6 +2513,22 @@ var OverlayScene = class {
       ctx.restore();
     }
   }
+  /**
+   * Update a DOM element's CSS transform to match its physics body position and rotation.
+   */
+  updateDOMElementTransform(entry) {
+    if (!entry.domElement) return;
+    const body = entry.body;
+    const x = body.position.x;
+    const y = body.position.y;
+    const angle = body.angle;
+    const angleDeg = angle * (180 / Math.PI);
+    const width = entry.domElement.offsetWidth;
+    const height = entry.domElement.offsetHeight;
+    entry.domElement.style.left = `${x - width / 2}px`;
+    entry.domElement.style.top = `${y - height / 2}px`;
+    entry.domElement.style.transform = `rotate(${angleDeg}deg)`;
+  }
   checkTTLExpiration() {
     const now = performance.now();
     const expiredObjects = [];