@blorkfield/overlay-core 0.5.10 → 0.7.0

package/dist/index.js

@@ -16,7 +16,7 @@ function createRender(engine, canvas, config) {
       width: config.bounds.right - config.bounds.left,
       height: config.bounds.bottom - config.bounds.top,
       wireframes: config.debug ?? false,
-      background: config.background ?? "transparent"
+      background: config.background?.color ?? "transparent"
     }
   });
   return render;
@@ -1110,6 +1110,269 @@ var EffectManager = class {
   }
 };
 
+// src/backgroundManager.ts
+var LOG_PREFIX4 = "BackgroundManager";
+var imageCache = /* @__PURE__ */ new Map();
+var BackgroundManager = class {
+  constructor(managerConfig) {
+    this.config = null;
+    this.loadedImage = null;
+    // Offscreen canvas for caching pre-rendered base layers
+    this.baseLayerCanvas = null;
+    this.baseLayerCtx = null;
+    this.baseLayerDirty = true;
+    this.canvas = managerConfig.canvas;
+    const ctx = managerConfig.canvas.getContext("2d");
+    if (!ctx) {
+      throw new Error("Failed to get 2D context from canvas");
+    }
+    this.ctx = ctx;
+    this.width = managerConfig.width;
+    this.height = managerConfig.height;
+    this.createOffscreenCanvas();
+  }
+  /**
+   * Create or recreate the offscreen canvas for base layer caching.
+   */
+  createOffscreenCanvas() {
+    this.baseLayerCanvas = document.createElement("canvas");
+    this.baseLayerCanvas.width = this.width;
+    this.baseLayerCanvas.height = this.height;
+    this.baseLayerCtx = this.baseLayerCanvas.getContext("2d");
+    this.baseLayerDirty = true;
+  }
+  /**
+   * Set the background configuration.
+   */
+  async setConfig(config) {
+    if (!config) {
+      this.config = null;
+      this.loadedImage = null;
+      this.baseLayerDirty = true;
+      return;
+    }
+    this.config = config;
+    if (config.image?.url) {
+      await this.loadBackgroundImage(config.image.url);
+    } else {
+      this.loadedImage = null;
+    }
+    this.baseLayerDirty = true;
+  }
+  /**
+   * Load and cache a background image.
+   */
+  async loadBackgroundImage(url) {
+    const cached = imageCache.get(url);
+    if (cached) {
+      logger.debug(LOG_PREFIX4, `Using cached image: ${url}`);
+      this.loadedImage = cached;
+      return;
+    }
+    try {
+      logger.debug(LOG_PREFIX4, `Loading background image: ${url}`);
+      const img = await loadImage(url);
+      imageCache.set(url, img);
+      this.loadedImage = img;
+      this.baseLayerDirty = true;
+      logger.debug(LOG_PREFIX4, `Background image loaded`, {
+        width: img.width,
+        height: img.height
+      });
+    } catch (err) {
+      logger.error(LOG_PREFIX4, `Failed to load background image: ${url}`, {
+        error: String(err)
+      });
+      this.loadedImage = null;
+    }
+  }
+  /**
+   * Update the canvas dimensions (call on resize).
+   */
+  resize(width, height) {
+    this.width = width;
+    this.height = height;
+    this.createOffscreenCanvas();
+  }
+  /**
+   * Get the current background config.
+   */
+  getConfig() {
+    return this.config;
+  }
+  /**
+   * Check if we have custom layers to render.
+   * Returns true if we need to handle background ourselves.
+   */
+  hasCustomLayers() {
+    if (!this.config) return false;
+    if (this.config.transparency?.opacity === 1) return true;
+    return !!(this.config.image || this.config.transparency);
+  }
+  /**
+   * Check if background is fully transparent (no color, no image, opacity = 0 or no transparency config).
+   */
+  isFullyTransparent() {
+    if (!this.config) return true;
+    const noColor = !this.config.color;
+    const noImage = !this.config.image;
+    const noOverlay = !this.config.transparency || this.config.transparency.opacity <= 0;
+    return noColor && noImage && noOverlay;
+  }
+  /**
+   * Pre-render the base layers (color + image) to the offscreen canvas.
+   * Only called when the config changes (baseLayerDirty is true).
+   */
+  prerenderBaseLayers() {
+    if (!this.baseLayerCtx || !this.baseLayerCanvas) return;
+    const ctx = this.baseLayerCtx;
+    ctx.clearRect(0, 0, this.width, this.height);
+    if (!this.config) {
+      this.baseLayerDirty = false;
+      return;
+    }
+    if (this.config.color && this.config.color !== "transparent") {
+      ctx.fillStyle = this.config.color;
+      ctx.fillRect(0, 0, this.width, this.height);
+    }
+    if (this.loadedImage && this.config.image) {
+      this.renderImageLayerToContext(ctx, this.loadedImage, this.config.image);
+    }
+    this.baseLayerDirty = false;
+    logger.debug(LOG_PREFIX4, "Base layers pre-rendered to offscreen canvas");
+  }
+  /**
+   * Render the base layers (color + image).
+   * Called BEFORE Matter.js renders physics objects.
+   * Uses cached offscreen canvas for performance.
+   */
+  renderBaseLayers() {
+    if (this.isFullyTransparent()) return;
+    if (this.baseLayerDirty) {
+      this.prerenderBaseLayers();
+    }
+    if (this.baseLayerCanvas && this.config) {
+      this.ctx.drawImage(this.baseLayerCanvas, 0, 0);
+    }
+  }
+  /**
+   * Render the transparency/frosted glass layer.
+   * Called AFTER Matter.js renders physics objects.
+   * This must render every frame since it overlays moving objects.
+   */
+  renderOverlay() {
+    if (!this.config?.transparency) return;
+    this.renderTransparencyLayer(this.config.transparency);
+  }
+  /**
+   * Render the background image to a given context with specified sizing.
+   */
+  renderImageLayerToContext(ctx, img, config) {
+    const sizing = config.sizing ?? "cover";
+    ctx.save();
+    switch (sizing) {
+      case "stretch":
+        ctx.drawImage(img, 0, 0, this.width, this.height);
+        break;
+      case "center":
+        this.drawCenter(ctx, img);
+        break;
+      case "tile":
+        this.drawTile(ctx, img);
+        break;
+      case "cover":
+        this.drawCover(ctx, img);
+        break;
+      case "contain":
+        this.drawContain(ctx, img);
+        break;
+    }
+    ctx.restore();
+  }
+  /**
+   * Draw image centered at original size.
+   */
+  drawCenter(ctx, img) {
+    const x = (this.width - img.width) / 2;
+    const y = (this.height - img.height) / 2;
+    ctx.drawImage(img, x, y);
+  }
+  /**
+   * Draw image tiled (repeating pattern).
+   */
+  drawTile(ctx, img) {
+    const pattern = ctx.createPattern(img, "repeat");
+    if (pattern) {
+      ctx.fillStyle = pattern;
+      ctx.fillRect(0, 0, this.width, this.height);
+    }
+  }
+  /**
+   * Draw image to cover entire area (may crop, maintains aspect ratio).
+   */
+  drawCover(ctx, img) {
+    const imgRatio = img.width / img.height;
+    const canvasRatio = this.width / this.height;
+    let drawWidth, drawHeight;
+    let offsetX = 0, offsetY = 0;
+    if (imgRatio > canvasRatio) {
+      drawHeight = this.height;
+      drawWidth = this.height * imgRatio;
+      offsetX = (this.width - drawWidth) / 2;
+    } else {
+      drawWidth = this.width;
+      drawHeight = this.width / imgRatio;
+      offsetY = (this.height - drawHeight) / 2;
+    }
+    ctx.drawImage(img, offsetX, offsetY, drawWidth, drawHeight);
+  }
+  /**
+   * Draw image to fit within area (may have gaps, maintains aspect ratio).
+   * Gaps are filled by the color layer underneath.
+   */
+  drawContain(ctx, img) {
+    const imgRatio = img.width / img.height;
+    const canvasRatio = this.width / this.height;
+    let drawWidth, drawHeight;
+    let offsetX = 0, offsetY = 0;
+    if (imgRatio > canvasRatio) {
+      drawWidth = this.width;
+      drawHeight = this.width / imgRatio;
+      offsetY = (this.height - drawHeight) / 2;
+    } else {
+      drawHeight = this.height;
+      drawWidth = this.height * imgRatio;
+      offsetX = (this.width - drawWidth) / 2;
+    }
+    ctx.drawImage(img, offsetX, offsetY, drawWidth, drawHeight);
+  }
+  /**
+   * Render the transparency/frosted glass layer.
+   * opacity = 0 means fully transparent (nothing drawn)
+   * opacity = 1 means fully opaque overlay
+   * opacity = 0.3 means light frosted glass
+   */
+  renderTransparencyLayer(config) {
+    if (config.opacity <= 0) return;
+    this.ctx.save();
+    this.ctx.globalAlpha = config.opacity;
+    if (config.tintColor) {
+      this.ctx.fillStyle = config.tintColor;
+    } else {
+      this.ctx.fillStyle = "#ffffff";
+    }
+    this.ctx.fillRect(0, 0, this.width, this.height);
+    this.ctx.restore();
+  }
+  /**
+   * Clear the background image cache.
+   */
+  static clearCache() {
+    imageCache.clear();
+    logger.debug(LOG_PREFIX4, "Image cache cleared");
+  }
+};
+
 // src/OverlayScene.ts
 var OverlayScene = class {
   constructor(canvas, config) {
@@ -1167,6 +1430,22 @@ var OverlayScene = class {
         }
       }
     };
+    /**
+     * Handler for Matter.js beforeRender event.
+     * Draws base background layers (color + image) before physics objects.
+     */
+    this.handleBeforeRender = () => {
+      if (this.backgroundManager.hasCustomLayers()) {
+        this.backgroundManager.renderBaseLayers();
+      }
+    };
+    /**
+     * Handler for Matter.js afterRender event.
+     * Draws transparency/frosted glass layer after physics objects.
+     */
+    this.handleAfterRender = () => {
+      this.backgroundManager.renderOverlay();
+    };
     // ==================== PRIVATE ====================
     this.loop = () => {
       this.effectManager.update();
@@ -1200,7 +1479,6 @@ var OverlayScene = class {
       gravity: 1,
       wrapHorizontal: true,
       debug: false,
-      background: "transparent",
       ...config
     };
     this.engine = createEngine(this.config.gravity);
@@ -1235,6 +1513,23 @@ var OverlayScene = class {
       (cfg) => this.spawnObjectAsync(cfg),
       (id) => this.objects.get(id)?.body ?? null
     );
+    const width = this.config.bounds.right - this.config.bounds.left;
+    const height = this.config.bounds.bottom - this.config.bounds.top;
+    this.backgroundManager = new BackgroundManager({
+      canvas,
+      width,
+      height
+    });
+    this.backgroundManager.setConfig(this.config.background).catch((err) => {
+      logger.error("OverlayScene", "Failed to initialize background", {
+        error: String(err)
+      });
+    });
+    if (this.backgroundManager.hasCustomLayers()) {
+      this.render.options.background = "transparent";
+    }
+    Matter5.Events.on(this.render, "beforeRender", this.handleBeforeRender);
+    Matter5.Events.on(this.render, "afterRender", this.handleAfterRender);
   }
   static createContainer(parent, options = {}) {
     const canvas = document.createElement("canvas");
@@ -1637,6 +1932,8 @@ var OverlayScene = class {
       Matter5.Events.off(this.mouseConstraint, "startdrag", this.handleStartDrag);
     }
     this.canvas.removeEventListener("click", this.handleCanvasClick);
+    Matter5.Events.off(this.render, "beforeRender", this.handleBeforeRender);
+    Matter5.Events.off(this.render, "afterRender", this.handleAfterRender);
     Matter5.Engine.clear(this.engine);
     this.objects.clear();
     this.obstaclePressure.clear();
@@ -1655,6 +1952,18 @@ var OverlayScene = class {
       }
     }
   }
+  /**
+   * Update the background configuration at runtime.
+   */
+  async setBackground(config) {
+    await this.backgroundManager.setConfig(config);
+    if (this.backgroundManager.hasCustomLayers()) {
+      this.render.options.background = "transparent";
+    } else {
+      const bgConfig = this.backgroundManager.getConfig();
+      this.render.options.background = bgConfig?.color ?? "transparent";
+    }
+  }
   resize(width, height) {
     this.canvas.width = width;
     this.canvas.height = height;
@@ -1672,6 +1981,7 @@ var OverlayScene = class {
     this.render.canvas.width = width;
     this.render.canvas.height = height;
     this.effectManager.setBounds(this.config.bounds);
+    this.backgroundManager.resize(width, height);
   }
   // ==================== OBJECT METHODS ====================
   /**
@@ -2270,7 +2580,8 @@ var OverlayScene = class {
       for (let i = 0; i < chars.length; i++) {
         const char = chars[i];
         if (char === " ") {
-          currentX += 20;
+          const spaceWidth = config.letterSpacing ?? letterSize;
+          currentX += spaceWidth;
           globalCharIndex++;
           if (inWord) {
             currentWordIndex++;
@@ -2793,6 +3104,7 @@ var OverlayScene = class {
   }
 };
 export {
+  BackgroundManager,
   OverlayScene,
   clearFontCache,
   getGlyphData,