@blorkfield/overlay-core 0.5.0 → 0.5.2

package/README.md

@@ -48,6 +48,15 @@ Static obstacles track how many dynamic objects are resting on them. When the ac
 
 The floor can be divided into independent segments, each with its own pressure threshold. When a segment receives too much weight, it collapses and objects fall through.
 
+| Option | Description |
+|--------|-------------|
+| `thickness` | Segment height in pixels (single value or array per segment) |
+| `color` | Segment fill color (single value or array per segment) - makes floor visible |
+| `minIntegrity` | Minimum segments required. When remaining segments drop below this, all collapse |
+| `segmentWidths` | Proportional widths for each segment (array that sums to 1.0, e.g., `[0.2, 0.3, 0.5]`) |
+
+Example: With 10 segments and `minIntegrity: 7`, once 4 segments have collapsed (leaving 6), all remaining segments collapse together.
+
 ## Quick Start
 
 ```typescript
@@ -72,6 +81,8 @@ scene.start();
 
 ## Spawning Objects
 
+All objects are created through `spawnObject()` (or `spawnObjectAsync()` for images). The same config supports canvas-rendered shapes, image-based shapes, and DOM elements.
+
 ### Basic Shapes
 
 ```typescript
@@ -118,6 +129,57 @@ const id = await scene.spawnObjectAsync({
 });
 ```
 
+### DOM Elements
+
+Pass a DOM element via the `element` property to link it to physics. The element will move with the physics body when it becomes dynamic.
+
+```typescript
+const contentBox = document.getElementById('content-box');
+
+scene.spawnObject({
+  element: contentBox,
+  x: boxX,
+  y: boxY,
+  width: contentBox.offsetWidth,
+  height: contentBox.offsetHeight,
+  tags: ['grabable'],
+  pressureThreshold: { value: 50 },
+  shadow: { opacity: 0.3 },
+  clickToFall: { clicks: 5 }
+});
+```
+
+When a DOM element collapses:
+- The element's CSS transform is updated each frame to follow physics
+- Shadow creates a cloned DOM element at the original position
+
+### Pressure, Shadow, and Click Behavior
+
+These options work on any spawned object (shapes, images, or DOM elements):
+
+```typescript
+scene.spawnObject({
+  x: 200,
+  y: 300,
+  width: 150,
+  height: 30,
+  fillStyle: '#333',
+  tags: ['grabable'],
+
+  // Collapse when 20 units of pressure accumulate
+  pressureThreshold: { value: 20 },
+
+  // This object contributes 5 pressure when resting on something
+  weight: 5,
+
+  // Leave a faded copy when collapsed (true = 0.3 opacity default)
+  shadow: { opacity: 0.3 },
+
+  // Collapse after being clicked 3 times
+  clickToFall: { clicks: 3 }
+});
+```
+
 ## Text Obstacles
 
 ### PNG Based Text
@@ -263,7 +325,10 @@ const scene = new OverlayScene(canvas, {
   background: '#16213e',
   floorConfig: {
     segments: 10,
-    threshold: 100
+    threshold: 100,
+    thickness: 20,
+    color: '#3a4a6a',   // Makes floor visible
+    minIntegrity: 7     // All collapse if fewer than 7 remain
   },
   despawnBelowFloor: 1.0
 });
@@ -276,7 +341,11 @@ const scene = new OverlayScene(canvas, {
 | `debug` | false | Show collision wireframes |
 | `background` | transparent | Canvas background color |
 | `floorConfig.segments` | 1 | Number of floor segments |
-| `floorConfig.threshold` | none | Pressure threshold for floor collapse |
+| `floorConfig.threshold` | none | Pressure threshold for collapse (number or array per segment) |
+| `floorConfig.thickness` | 50 | Floor thickness in pixels (number or array per segment) |
+| `floorConfig.color` | none | Floor color - makes segments visible (string or array per segment) |
+| `floorConfig.minIntegrity` | none | Minimum segments required, otherwise all collapse |
+| `floorConfig.segmentWidths` | none | Proportional widths for each segment (array that sums to 1.0) |
 | `despawnBelowFloor` | 1.0 | Distance below floor to despawn objects (as fraction of height) |
 
 ## Pressure Tracking

package/dist/index.cjs

@@ -508,7 +508,7 @@ function createBodyFromVertices(id, x, y, vertices, renderOptions) {
 function createBoundariesWithFloorConfig(bounds, floorConfig) {
   const width = bounds.right - bounds.left;
   const height = bounds.bottom - bounds.top;
-  const options = { isStatic: true, render: { visible: false } };
+  const wallOptions = { isStatic: true, render: { visible: false } };
   const walls = [
     // Left wall
     import_matter_js2.default.Bodies.rectangle(
@@ -516,7 +516,7 @@ function createBoundariesWithFloorConfig(bounds, floorConfig) {
       bounds.top + height / 2,
       BOUNDARY_THICKNESS,
       height,
-      { ...options, label: "leftWall" }
+      { ...wallOptions, label: "leftWall" }
     ),
     // Right wall
     import_matter_js2.default.Bodies.rectangle(
@@ -524,23 +524,44 @@ function createBoundariesWithFloorConfig(bounds, floorConfig) {
       bounds.top + height / 2,
       BOUNDARY_THICKNESS,
       height,
-      { ...options, label: "rightWall" }
+      { ...wallOptions, label: "rightWall" }
     )
   ];
   const segmentCount = floorConfig?.segments ?? 1;
-  const segmentWidth = width / segmentCount;
   const floorSegments = [];
+  let segmentWidths;
+  if (floorConfig?.segmentWidths && floorConfig.segmentWidths.length === segmentCount) {
+    const sum = floorConfig.segmentWidths.reduce((a, b) => a + b, 0);
+    segmentWidths = floorConfig.segmentWidths.map((w) => w / sum * width);
+  } else {
+    const equalWidth = width / segmentCount;
+    segmentWidths = Array(segmentCount).fill(equalWidth);
+  }
+  let currentX = bounds.left;
   for (let i = 0; i < segmentCount; i++) {
-    const segmentX = bounds.left + (i + 0.5) * segmentWidth;
+    const segmentWidth = segmentWidths[i];
+    const thickness = floorConfig?.thickness !== void 0 ? Array.isArray(floorConfig.thickness) ? floorConfig.thickness[i] ?? BOUNDARY_THICKNESS : floorConfig.thickness : BOUNDARY_THICKNESS;
+    const color = floorConfig?.color !== void 0 ? Array.isArray(floorConfig.color) ? floorConfig.color[i] : floorConfig.color : void 0;
+    const segmentX = currentX + segmentWidth / 2;
+    const segmentY = bounds.bottom - thickness / 2;
+    const segmentOptions = {
+      isStatic: true,
+      label: `floor-segment-${i}`,
+      render: {
+        visible: color !== void 0,
+        fillStyle: color ?? "#888888"
+      }
+    };
     floorSegments.push(
       import_matter_js2.default.Bodies.rectangle(
         segmentX,
-        bounds.bottom + BOUNDARY_THICKNESS / 2,
+        segmentY,
         segmentWidth,
-        BOUNDARY_THICKNESS,
-        { ...options, label: `floor-segment-${i}` }
+        thickness,
+        segmentOptions
       )
     );
+    currentX += segmentWidth;
   }
   return { walls, floorSegments };
 }
@@ -1232,6 +1253,7 @@ var OverlayScene = class {
     this.boundaries = [...boundariesResult.walls, ...boundariesResult.floorSegments];
     this.floorSegments = boundariesResult.floorSegments;
     import_matter_js5.default.Composite.add(this.engine.world, this.boundaries);
+    this.checkInitialFloorIntegrity();
     this.mouse = import_matter_js5.default.Mouse.create(canvas);
     this.mouseConstraint = import_matter_js5.default.MouseConstraint.create(this.engine, {
       mouse: this.mouse,
@@ -1350,7 +1372,8 @@ var OverlayScene = class {
         if (onObstacles.has(dyn.id)) continue;
         const dynBounds = dyn.body.bounds;
         const horizontalOverlap = dynBounds.max.x > segmentBounds.min.x && dynBounds.min.x < segmentBounds.max.x;
-        if (horizontalOverlap) {
+        const nearFloor = dynBounds.max.y >= segmentBounds.min.y - 10;
+        if (horizontalOverlap && nearFloor) {
           resting.add(dyn.id);
         }
       }
@@ -1376,17 +1399,50 @@ var OverlayScene = class {
       const objectIds = this.floorSegmentPressure.get(i);
       const pressure = objectIds ? this.calculateWeightedPressure(objectIds) : 0;
       if (pressure >= threshold) {
-        this.collapseFloorSegment(i, pressure, threshold);
+        this.collapseFloorSegment(i, `pressure ${pressure} >= threshold ${threshold}`);
       }
     }
   }
   /** Collapse a single floor segment */
-  collapseFloorSegment(index, pressure, threshold) {
+  collapseFloorSegment(index, reason) {
     if (this.collapsedSegments.has(index)) return;
     this.collapsedSegments.add(index);
     const segment = this.floorSegments[index];
     import_matter_js5.default.Composite.remove(this.engine.world, segment);
-    console.log(`[Pressure] Floor segment ${index} collapsed! (pressure: ${pressure} >= ${threshold})`);
+    logger.debug("OverlayScene", `Floor segment ${index} collapsed: ${reason}`);
+    this.checkFloorIntegrity();
+  }
+  /** Check if floor integrity requirement is violated and collapse all remaining if so */
+  checkFloorIntegrity() {
+    const minIntegrity = this.config.floorConfig?.minIntegrity;
+    if (minIntegrity === void 0) return;
+    const totalSegments = this.floorSegments.length;
+    const remainingSegments = totalSegments - this.collapsedSegments.size;
+    if (remainingSegments < minIntegrity && remainingSegments > 0) {
+      logger.debug("OverlayScene", `Floor integrity failed: ${remainingSegments} remaining < ${minIntegrity} required. Collapsing all.`);
+      for (let i = 0; i < totalSegments; i++) {
+        if (!this.collapsedSegments.has(i)) {
+          this.collapsedSegments.add(i);
+          const segment = this.floorSegments[i];
+          import_matter_js5.default.Composite.remove(this.engine.world, segment);
+          logger.debug("OverlayScene", `Floor segment ${i} collapsed: integrity failure cascade`);
+        }
+      }
+    }
+  }
+  /** Check floor integrity on initialization (handles minIntegrity > segments) */
+  checkInitialFloorIntegrity() {
+    const minIntegrity = this.config.floorConfig?.minIntegrity;
+    if (minIntegrity === void 0) return;
+    const totalSegments = this.floorSegments.length;
+    if (totalSegments < minIntegrity) {
+      logger.debug("OverlayScene", `Floor integrity impossible: ${totalSegments} segments < ${minIntegrity} required. Collapsing all immediately.`);
+      for (let i = 0; i < totalSegments; i++) {
+        this.collapsedSegments.add(i);
+        const segment = this.floorSegments[i];
+        import_matter_js5.default.Composite.remove(this.engine.world, segment);
+      }
+    }
   }
   /** Log a summary of pressure on all obstacles, grouped by word */
   logPressureSummary() {
@@ -1505,7 +1561,6 @@ var OverlayScene = class {
       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;
@@ -1642,6 +1697,7 @@ var OverlayScene = class {
     this.collapsedSegments.clear();
     this.floorSegmentPressure.clear();
     import_matter_js5.default.Composite.add(this.engine.world, this.boundaries);
+    this.checkInitialFloorIntegrity();
     this.render.options.width = width;
     this.render.options.height = height;
     this.render.canvas.width = width;
@@ -1658,6 +1714,21 @@ var OverlayScene = class {
    * Without 'falling' tag, object is static.
    */
   spawnObject(config) {
+    if (config.element) {
+      const result = this.addDOMObstacleInternal({
+        element: config.element,
+        x: config.x,
+        y: config.y,
+        width: config.width,
+        height: config.height,
+        tags: config.tags,
+        pressureThreshold: config.pressureThreshold,
+        weight: config.weight,
+        shadow: config.shadow === true ? { opacity: 0.3 } : config.shadow || void 0,
+        clickToFall: config.clickToFall
+      });
+      return result.id;
+    }
     const id = crypto.randomUUID();
     const tags = config.tags ?? [];
     const isStatic = !tags.includes("falling");
@@ -1677,6 +1748,17 @@ var OverlayScene = class {
     } else {
       body = createObstacle(id, config, isStatic);
     }
+    let pressureThreshold;
+    if (config.pressureThreshold) {
+      pressureThreshold = typeof config.pressureThreshold.value === "number" ? config.pressureThreshold.value : config.pressureThreshold.value[0];
+    }
+    let shadow;
+    if (config.shadow === true) {
+      shadow = { opacity: 0.3 };
+    } else if (config.shadow && typeof config.shadow === "object") {
+      shadow = { opacity: config.shadow.opacity ?? 0.3 };
+    }
+    const clicksRemaining = config.clickToFall?.clicks;
     const entry = {
       id,
       body,
@@ -1684,10 +1766,17 @@ var OverlayScene = class {
       spawnTime: performance.now(),
       ttl: config.ttl,
       despawnEffect: config.despawnEffect,
-      weight: config.weight ?? 1
+      weight: config.weight ?? 1,
+      pressureThreshold,
+      shadow,
+      originalPosition: shadow || clicksRemaining !== void 0 ? { x: config.x, y: config.y } : void 0,
+      clicksRemaining
     };
     this.objects.set(id, entry);
     import_matter_js5.default.Composite.add(this.engine.world, body);
+    if (isStatic && pressureThreshold !== void 0) {
+      this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
+    }
     return id;
   }
   /**
@@ -1714,6 +1803,17 @@ var OverlayScene = class {
     } else {
       body = await createObstacleAsync(id, config, isStatic);
     }
+    let pressureThreshold;
+    if (config.pressureThreshold) {
+      pressureThreshold = typeof config.pressureThreshold.value === "number" ? config.pressureThreshold.value : config.pressureThreshold.value[0];
+    }
+    let shadow;
+    if (config.shadow === true) {
+      shadow = { opacity: 0.3 };
+    } else if (config.shadow && typeof config.shadow === "object") {
+      shadow = { opacity: config.shadow.opacity ?? 0.3 };
+    }
+    const clicksRemaining = config.clickToFall?.clicks;
     const entry = {
       id,
       body,
@@ -1721,10 +1821,17 @@ var OverlayScene = class {
       spawnTime: performance.now(),
       ttl: config.ttl,
       despawnEffect: config.despawnEffect,
-      weight: config.weight ?? 1
+      weight: config.weight ?? 1,
+      pressureThreshold,
+      shadow,
+      originalPosition: shadow || clicksRemaining !== void 0 ? { x: config.x, y: config.y } : void 0,
+      clicksRemaining
     };
     this.objects.set(id, entry);
     import_matter_js5.default.Composite.add(this.engine.world, body);
+    if (isStatic && pressureThreshold !== void 0) {
+      this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
+    }
     return id;
   }
   /**
@@ -1983,17 +2090,12 @@ var OverlayScene = class {
   areFontsInitialized() {
     return this.fontsInitialized;
   }
-  // ==================== DOM OBSTACLE METHODS ====================
+  // ==================== DOM OBSTACLE METHODS (INTERNAL) ====================
   /**
-   * 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.
+   * Internal: Attach a DOM element to physics.
+   * Called by spawnObject when element is provided.
    */
-  addDOMObstacle(config) {
+  addDOMObstacleInternal(config) {
     const { element, x, y } = config;
     const width = config.width ?? element.offsetWidth;
     const height = config.height ?? element.offsetHeight;
@@ -2030,6 +2132,7 @@ var OverlayScene = class {
     };
     this.objects.set(id, entry);
     import_matter_js5.default.Composite.add(this.engine.world, body);
+    this.updateDOMElementTransform(entry);
     if (isStatic && pressureThreshold !== void 0) {
       this.obstaclePressure.set(id, /* @__PURE__ */ new Set());
     }
@@ -2136,11 +2239,61 @@ var OverlayScene = class {
       maxDimension = Math.max(maxDimension, dims.width, dims.height);
     }
     if (maxDimension === 0) maxDimension = 100;
+    const calculateLineWidth = (line) => {
+      let width = 0;
+      for (const char of line) {
+        if (char === " ") {
+          width += 20;
+        } else if (/^[A-Za-z0-9]$/.test(char)) {
+          const dims = charDimensions.get(char);
+          if (dims) {
+            const scale = letterSize / Math.max(dims.width, dims.height);
+            const scaledWidth = dims.width * scale;
+            const extraSpacing = config.letterSpacing !== void 0 ? config.letterSpacing - scaledWidth : 0;
+            width += scaledWidth + Math.max(0, extraSpacing);
+          }
+        }
+      }
+      return width;
+    };
+    const lineWidths = lines.map((line) => calculateLineWidth(line));
+    const align = config.align ?? "left";
+    const maxLineWidth = Math.max(...lineWidths, 0);
+    let boundsLeft;
+    let boundsRight;
+    switch (align) {
+      case "center":
+        boundsLeft = config.x - maxLineWidth / 2;
+        boundsRight = config.x + maxLineWidth / 2;
+        break;
+      case "right":
+        boundsLeft = config.x - maxLineWidth;
+        boundsRight = config.x;
+        break;
+      default:
+        boundsLeft = config.x;
+        boundsRight = config.x + maxLineWidth;
+    }
+    const boundsTop = config.y - letterSize / 2;
+    const totalHeight = lines.length > 0 ? (lines.length - 1) * lineHeight + letterSize : 0;
+    const boundsBottom = boundsTop + totalHeight;
     let currentY = config.y;
     let globalCharIndex = 0;
-    for (const line of lines) {
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex];
       const chars = line.split("");
-      let currentX = config.x;
+      const lineWidth = lineWidths[lineIndex];
+      let currentX;
+      switch (align) {
+        case "center":
+          currentX = config.x - lineWidth / 2;
+          break;
+        case "right":
+          currentX = config.x - lineWidth;
+          break;
+        default:
+          currentX = config.x;
+      }
       if (inWord) {
         currentWordIndex++;
         inWord = false;
@@ -2256,12 +2409,21 @@ var OverlayScene = class {
       letterColor,
       lineCount: lines.length
     });
+    const bounds = {
+      left: boundsLeft,
+      right: boundsRight,
+      top: boundsTop,
+      bottom: boundsBottom,
+      width: boundsRight - boundsLeft,
+      height: boundsBottom - boundsTop
+    };
     return {
       letterIds,
       stringTag,
       wordTags,
       letterMap,
-      letterDebugInfo: debugInfo
+      letterDebugInfo: debugInfo,
+      bounds
     };
   }
   /**
@@ -2334,10 +2496,43 @@ var OverlayScene = class {
     const fontInfo = this.fonts.find((f) => f.fontUrl === fontUrl);
     const fontFamily = fontInfo?.name ?? "sans-serif";
     const lines = text.split("\n");
+    const lineWidths = lines.map((line) => measureText(loadedFont, line, fontSize));
+    const align = config.align ?? "left";
+    const maxLineWidth = Math.max(...lineWidths, 0);
+    let boundsLeft;
+    let boundsRight;
+    switch (align) {
+      case "center":
+        boundsLeft = x - maxLineWidth / 2;
+        boundsRight = x + maxLineWidth / 2;
+        break;
+      case "right":
+        boundsLeft = x - maxLineWidth;
+        boundsRight = x;
+        break;
+      default:
+        boundsLeft = x;
+        boundsRight = x + maxLineWidth;
+    }
+    const boundsTop = y - fontSize * 0.8;
+    const totalHeight = lines.length > 0 ? (lines.length - 1) * lineHeight + fontSize : 0;
+    const boundsBottom = boundsTop + totalHeight;
     let currentY = y;
     let globalCharIndex = 0;
-    for (const line of lines) {
-      let currentX = x;
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex];
+      const lineWidth = lineWidths[lineIndex];
+      let currentX;
+      switch (align) {
+        case "center":
+          currentX = x - lineWidth / 2;
+          break;
+        case "right":
+          currentX = x - lineWidth;
+          break;
+        default:
+          currentX = x;
+      }
       if (inWord) {
         currentWordIndex++;
         inWord = false;
@@ -2447,12 +2642,21 @@ var OverlayScene = class {
       wordTags,
       lineCount: lines.length
     });
+    const bounds = {
+      left: boundsLeft,
+      right: boundsRight,
+      top: boundsTop,
+      bottom: boundsBottom,
+      width: boundsRight - boundsLeft,
+      height: boundsBottom - boundsTop
+    };
     return {
       letterIds,
       stringTag,
       wordTags,
       letterMap,
-      letterDebugInfo: []
+      letterDebugInfo: [],
+      bounds
     };
   }
   /**