aspect-grid-collageify 1.0.0

package/dist/index.mjs

@@ -0,0 +1,771 @@
+// src/index.ts
+var AspectGridCollageify = class {
+  constructor(config, canvasElement) {
+    this.canvas = null;
+    this.ctx = null;
+    // Cache for loaded images
+    this.imageCache = /* @__PURE__ */ new Map();
+    this.loadingImages = /* @__PURE__ */ new Set();
+    // Interactive states
+    this.activeImageId = null;
+    this.draggedImageId = null;
+    this.dragStartOffset = { x: 0, y: 0 };
+    this.dragCurrentPos = { x: 0, y: 0 };
+    this.draggedOverCell = null;
+    this.hoveredPlaceholder = null;
+    this.isDragging = false;
+    // Callback events
+    this.changeCallbacks = [];
+    this.activeCallbacks = [];
+    this.clickCallbacks = [];
+    this.config = {
+      showGridlines: true,
+      placementSize: "medium",
+      containerBgColor: "#ffffff",
+      useTransparentBg: false,
+      imageBorderRadius2K: 24,
+      imageShadowBlur2K: 0,
+      imageShadowOffset2K: 0,
+      imageShadowOpacity: 0.2,
+      ...config
+    };
+    if (canvasElement) {
+      this.canvas = canvasElement;
+      this.ctx = canvasElement.getContext("2d");
+      this.initEvents();
+    }
+  }
+  // --- API Configuration Get/Set ---
+  getConfig() {
+    return this.config;
+  }
+  updateConfig(newConfig) {
+    this.config = { ...this.config, ...newConfig };
+    this.render();
+  }
+  getImages() {
+    return this.config.images;
+  }
+  setImages(images) {
+    this.config.images = images;
+    this.triggerChange();
+    this.render();
+  }
+  getActiveImageId() {
+    return this.activeImageId;
+  }
+  setActiveImageId(id) {
+    this.activeImageId = id;
+    this.triggerActiveChange();
+    this.render();
+  }
+  // --- Event Callbacks registration ---
+  onImagesChanged(callback) {
+    this.changeCallbacks.push(callback);
+  }
+  onActiveImageChanged(callback) {
+    this.activeCallbacks.push(callback);
+  }
+  onCellClicked(callback) {
+    this.clickCallbacks.push(callback);
+  }
+  triggerChange() {
+    this.changeCallbacks.forEach((cb) => cb(this.config.images));
+  }
+  triggerActiveChange() {
+    this.activeCallbacks.forEach((cb) => cb(this.activeImageId));
+  }
+  triggerCellClick(x, y) {
+    this.clickCallbacks.forEach((cb) => cb(x, y));
+  }
+  // --- Image Cache helpers ---
+  getOrLoadImage(src) {
+    if (this.imageCache.has(src)) {
+      return this.imageCache.get(src);
+    }
+    if (this.loadingImages.has(src)) {
+      return null;
+    }
+    this.loadingImages.add(src);
+    const img = new Image();
+    img.crossOrigin = "anonymous";
+    img.onload = () => {
+      this.imageCache.set(src, img);
+      this.loadingImages.delete(src);
+      this.render();
+    };
+    img.onerror = () => {
+      this.loadingImages.delete(src);
+      console.error("Failed to load image:", src);
+    };
+    img.src = src;
+    return null;
+  }
+  async preloadAllImages() {
+    const promises = this.config.images.map((imgData) => {
+      if (this.imageCache.has(imgData.src)) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => {
+        const img = new Image();
+        img.crossOrigin = "anonymous";
+        img.onload = () => {
+          this.imageCache.set(imgData.src, img);
+          resolve();
+        };
+        img.onerror = () => {
+          console.error("Preload failed:", imgData.src);
+          resolve();
+        };
+        img.src = imgData.src;
+      });
+    });
+    await Promise.all(promises);
+  }
+  // --- Grid placement collision validation ---
+  canPlaceImage(imgId, x, y, spanSize, gridRows) {
+    if (x + spanSize > this.config.gridColumns || y + spanSize > gridRows || x < 0 || y < 0) return false;
+    for (const img of this.config.images) {
+      if (imgId && img.id === imgId) continue;
+      const overlap = !(x + spanSize <= img.gridX || img.gridX + img.span <= x || y + spanSize <= img.gridY || img.gridY + img.span <= y);
+      if (overlap) return false;
+    }
+    return true;
+  }
+  // --- Placed Images Editing Actions ---
+  addImage(img) {
+    this.config.images = [...this.config.images, img];
+    this.activeImageId = img.id;
+    this.triggerChange();
+    this.triggerActiveChange();
+    this.render();
+  }
+  removeImage(imgId) {
+    this.config.images = this.config.images.filter((img) => img.id !== imgId);
+    if (this.activeImageId === imgId) {
+      this.activeImageId = null;
+      this.triggerActiveChange();
+    }
+    this.triggerChange();
+    this.render();
+  }
+  updateImage(imgId, updates) {
+    this.config.images = this.config.images.map(
+      (img) => img.id === imgId ? { ...img, ...updates } : img
+    );
+    this.triggerChange();
+    this.render();
+  }
+  modifyImageSpan(imgId, delta, gridRows) {
+    const img = this.config.images.find((i) => i.id === imgId);
+    if (!img) return false;
+    const newSpan = Math.max(1, Math.min(this.config.gridColumns, img.span + delta));
+    if (newSpan === img.span) return false;
+    if (this.canPlaceImage(imgId, img.gridX, img.gridY, newSpan, gridRows)) {
+      this.config.images = this.config.images.map(
+        (i) => i.id === imgId ? { ...i, span: newSpan } : i
+      );
+      this.triggerChange();
+      this.render();
+      return true;
+    }
+    return false;
+  }
+  stepImagePosition(imgId, dir, gridRows) {
+    const img = this.config.images.find((i) => i.id === imgId);
+    if (!img) return false;
+    let targetX = img.gridX;
+    let targetY = img.gridY;
+    if (dir === "up") targetY = Math.max(0, targetY - 1);
+    if (dir === "down") targetY = Math.min(gridRows - img.span, targetY + 1);
+    if (dir === "left") targetX = Math.max(0, targetX - 1);
+    if (dir === "right") targetX = Math.min(this.config.gridColumns - img.span, targetX + 1);
+    if (targetX === img.gridX && targetY === img.gridY) return false;
+    if (this.canPlaceImage(imgId, targetX, targetY, img.span, gridRows)) {
+      this.config.images = this.config.images.map(
+        (i) => i.id === imgId ? { ...i, gridX: targetX, gridY: targetY } : i
+      );
+      this.triggerChange();
+      this.render();
+      return true;
+    }
+    return false;
+  }
+  pushDownBelow(imgId, gridRows) {
+    const activeImg = this.config.images.find((i) => i.id === imgId);
+    if (!activeImg) return false;
+    const boundaryY = activeImg.gridY + activeImg.span;
+    const targets = this.config.images.filter((img) => img.id !== imgId && img.gridY >= boundaryY);
+    const canShiftAll = targets.every((img) => img.gridY + img.span + 1 <= gridRows);
+    if (!canShiftAll) return false;
+    this.config.images = this.config.images.map((img) => {
+      if (img.id !== imgId && img.gridY >= boundaryY) {
+        return { ...img, gridY: img.gridY + 1 };
+      }
+      return img;
+    });
+    this.triggerChange();
+    this.render();
+    return true;
+  }
+  pullUpBelow(imgId) {
+    const activeImg = this.config.images.find((i) => i.id === imgId);
+    if (!activeImg) return false;
+    const boundaryY = activeImg.gridY + activeImg.span;
+    const tempImages = this.config.images.map((img) => {
+      if (img.id !== imgId && img.gridY >= boundaryY) {
+        return { ...img, gridY: img.gridY - 1 };
+      }
+      return img;
+    });
+    let isValid = true;
+    for (let i = 0; i < tempImages.length; i++) {
+      const img = tempImages[i];
+      if (img.gridY < 0) {
+        isValid = false;
+        break;
+      }
+      for (let j = i + 1; j < tempImages.length; j++) {
+        const other = tempImages[j];
+        const overlap = !(img.gridX + img.span <= other.gridX || other.gridX + other.span <= img.gridX || img.gridY + img.span <= other.gridY || other.gridY + other.span <= img.gridY);
+        if (overlap) {
+          isValid = false;
+          break;
+        }
+      }
+      if (!isValid) break;
+    }
+    if (!isValid) return false;
+    this.config.images = tempImages;
+    this.triggerChange();
+    this.render();
+    return true;
+  }
+  // --- Layout Calculations (Geometric Math) ---
+  calculateLayout(width, height) {
+    const containerRatioVal = (() => {
+      if (this.config.containerRatio === "custom") {
+        return (this.config.customContainerW || 3) / (this.config.customContainerH || 4);
+      }
+      const parts = this.config.containerRatio.split(":");
+      return Number(parts[0]) / Number(parts[1]);
+    })();
+    const imageRatioVal = (() => {
+      if (this.config.imageRatio === "custom") {
+        return (this.config.customImageW || 16) / (this.config.customImageH || 9);
+      }
+      const parts = this.config.imageRatio.split(":");
+      return Number(parts[0]) / Number(parts[1]);
+    })();
+    const scale = width / 2048;
+    const padding = this.config.padding2K * scale;
+    const gap = this.config.gap2K * scale;
+    const contentW = Math.max(50, width - padding * 2);
+    const contentH = Math.max(50, height - padding * 2);
+    const cellW = (contentW - (this.config.gridColumns - 1) * gap) / this.config.gridColumns;
+    const cellH = (cellW + gap) / imageRatioVal - gap;
+    const gridRows = Math.floor((contentH + gap) / (cellH + gap));
+    const gridW = this.config.gridColumns * cellW + (this.config.gridColumns - 1) * gap;
+    const gridH = gridRows * cellH + (gridRows - 1) * gap;
+    const offsetX = padding + (contentW - gridW) / 2;
+    const offsetY = padding + (contentH - gridH) / 2;
+    return {
+      scale,
+      padding,
+      gap,
+      cellW,
+      cellH,
+      gridRows,
+      offsetX,
+      offsetY,
+      gridW,
+      gridH,
+      containerRatioVal,
+      imageRatioVal
+    };
+  }
+  // --- Visual mode mouse interaction listeners ---
+  initEvents() {
+    if (!this.canvas) return;
+    const getMouseCoords = (e) => {
+      const rect = this.canvas.getBoundingClientRect();
+      return {
+        x: e.clientX - rect.left,
+        y: e.clientY - rect.top
+      };
+    };
+    this.canvas.addEventListener("mousedown", (e) => {
+      const mouse = getMouseCoords(e);
+      const rect = this.canvas.getBoundingClientRect();
+      const layout = this.calculateLayout(rect.width || this.canvas.width, rect.height || this.canvas.height);
+      const hitImg = this.hitTest(mouse.x, mouse.y, layout);
+      if (hitImg) {
+        this.activeImageId = hitImg.id;
+        this.draggedImageId = hitImg.id;
+        this.isDragging = true;
+        const imgRect = this.getImageRect(hitImg, layout);
+        this.dragStartOffset = {
+          x: mouse.x - imgRect.x,
+          y: mouse.y - imgRect.y
+        };
+        this.dragCurrentPos = { x: mouse.x, y: mouse.y };
+        this.triggerActiveChange();
+        this.render();
+        return;
+      }
+      const targetSpan = this.getCurrentTargetSpan();
+      const placeholders = this.getPlaceholders(targetSpan, layout.gridRows);
+      const hitPlaceholder = placeholders.find((slot) => {
+        const slotX = layout.offsetX + slot.gridX * (layout.cellW + layout.gap);
+        const slotY = layout.offsetY + slot.gridY * (layout.cellH + layout.gap);
+        const slotW = slot.span * layout.cellW + (slot.span - 1) * layout.gap;
+        const slotH = slot.span * layout.cellH + (slot.span - 1) * layout.gap;
+        return mouse.x >= slotX && mouse.x <= slotX + slotW && mouse.y >= slotY && mouse.y <= slotY + slotH;
+      });
+      if (hitPlaceholder) {
+        this.triggerCellClick(hitPlaceholder.gridX, hitPlaceholder.gridY);
+        return;
+      }
+      if (this.activeImageId) {
+        this.activeImageId = null;
+        this.triggerActiveChange();
+        this.render();
+      }
+    });
+    this.canvas.addEventListener("mousemove", (e) => {
+      const mouse = getMouseCoords(e);
+      const rect = this.canvas.getBoundingClientRect();
+      const layout = this.calculateLayout(rect.width || this.canvas.width, rect.height || this.canvas.height);
+      if (this.isDragging && this.draggedImageId) {
+        this.dragCurrentPos = { x: mouse.x, y: mouse.y };
+        const snapX = mouse.x - this.dragStartOffset.x;
+        const snapY = mouse.y - this.dragStartOffset.y;
+        const col = Math.round((snapX - layout.offsetX) / (layout.cellW + layout.gap));
+        const row = Math.round((snapY - layout.offsetY) / (layout.cellH + layout.gap));
+        const draggedImg = this.config.images.find((img) => img.id === this.draggedImageId);
+        if (draggedImg) {
+          const targetX = Math.max(0, Math.min(this.config.gridColumns - draggedImg.span, col));
+          const targetY = Math.max(0, Math.min(layout.gridRows - draggedImg.span, row));
+          if (!this.draggedOverCell || this.draggedOverCell.x !== targetX || this.draggedOverCell.y !== targetY) {
+            this.draggedOverCell = { x: targetX, y: targetY };
+          }
+        }
+        this.render();
+      } else {
+        const targetSpan = this.getCurrentTargetSpan();
+        const placeholders = this.getPlaceholders(targetSpan, layout.gridRows);
+        const hitPlaceholder = placeholders.find((slot) => {
+          const slotX = layout.offsetX + slot.gridX * (layout.cellW + layout.gap);
+          const slotY = layout.offsetY + slot.gridY * (layout.cellH + layout.gap);
+          const slotW = slot.span * layout.cellW + (slot.span - 1) * layout.gap;
+          const slotH = slot.span * layout.cellH + (slot.span - 1) * layout.gap;
+          return mouse.x >= slotX && mouse.x <= slotX + slotW && mouse.y >= slotY && mouse.y <= slotY + slotH;
+        });
+        if (hitPlaceholder) {
+          if (!this.hoveredPlaceholder || this.hoveredPlaceholder.gridX !== hitPlaceholder.gridX || this.hoveredPlaceholder.gridY !== hitPlaceholder.gridY) {
+            this.hoveredPlaceholder = { gridX: hitPlaceholder.gridX, gridY: hitPlaceholder.gridY };
+            this.canvas.style.cursor = "pointer";
+            this.render();
+          }
+        } else {
+          if (this.hoveredPlaceholder) {
+            this.hoveredPlaceholder = null;
+            this.canvas.style.cursor = "default";
+            this.render();
+          }
+          const hitImg = this.hitTest(mouse.x, mouse.y, layout);
+          this.canvas.style.cursor = hitImg ? "move" : "default";
+        }
+      }
+    });
+    window.addEventListener("mouseup", () => {
+      if (this.isDragging && this.draggedImageId && this.draggedOverCell) {
+        const sourceImg = this.config.images.find((img) => img.id === this.draggedImageId);
+        if (sourceImg) {
+          const rect = this.canvas.getBoundingClientRect();
+          const layout = this.calculateLayout(rect.width || this.canvas.width, rect.height || this.canvas.height);
+          const targetX = this.draggedOverCell.x;
+          const targetY = this.draggedOverCell.y;
+          if (this.canPlaceImage(this.draggedImageId, targetX, targetY, sourceImg.span, layout.gridRows)) {
+            this.config.images = this.config.images.map(
+              (img) => img.id === this.draggedImageId ? { ...img, gridX: targetX, gridY: targetY } : img
+            );
+            this.triggerChange();
+          } else {
+            const targetImg = this.config.images.find((img) => img.gridX === targetX && img.gridY === targetY);
+            if (targetImg && targetImg.span === sourceImg.span && this.canPlaceImage(this.draggedImageId, targetImg.gridX, targetImg.gridY, sourceImg.span, layout.gridRows)) {
+              this.config.images = this.config.images.map((img) => {
+                if (img.id === sourceImg.id) return { ...img, gridX: targetImg.gridX, gridY: targetImg.gridY };
+                if (img.id === targetImg.id) return { ...img, gridX: sourceImg.gridX, gridY: sourceImg.gridY };
+                return img;
+              });
+              this.triggerChange();
+            }
+          }
+        }
+      }
+      this.isDragging = false;
+      this.draggedImageId = null;
+      this.draggedOverCell = null;
+      this.render();
+    });
+  }
+  hitTest(x, y, layout) {
+    for (let i = this.config.images.length - 1; i >= 0; i--) {
+      const img = this.config.images[i];
+      const rect = this.getImageRect(img, layout);
+      if (x >= rect.x && x <= rect.x + rect.w && y >= rect.y && y <= rect.y + rect.h) {
+        return img;
+      }
+    }
+    return null;
+  }
+  getImageRect(img, layout) {
+    const w = img.span * layout.cellW + (img.span - 1) * layout.gap;
+    const h = img.span * layout.cellH + (img.span - 1) * layout.gap;
+    const x = layout.offsetX + img.gridX * (layout.cellW + layout.gap);
+    const y = layout.offsetY + img.gridY * (layout.cellH + layout.gap);
+    return { x, y, w, h };
+  }
+  getCurrentTargetSpan() {
+    const size = this.config.placementSize || "medium";
+    const gridColumns = this.config.gridColumns;
+    switch (gridColumns) {
+      case 4:
+        return { small: 1, medium: 2, large: 3 }[size];
+      case 6:
+        return { small: 1, medium: 2, large: 3 }[size];
+      case 8:
+        return { small: 2, medium: 3, large: 4 }[size];
+      case 12:
+        return { small: 3, medium: 4, large: 6 }[size];
+      default:
+        const s = Math.max(1, Math.floor(gridColumns / 4));
+        const m = Math.min(gridColumns, Math.max(s + 1, Math.floor(gridColumns / 3)));
+        const l = Math.min(gridColumns, Math.max(m + 1, Math.floor(gridColumns / 2)));
+        return { small: s, medium: m, large: l }[size];
+    }
+  }
+  getPlaceholders(targetSpan, gridRows) {
+    const gridColumns = this.config.gridColumns;
+    const occupied = Array.from({ length: gridColumns }, () => Array(gridRows).fill(false));
+    for (const img of this.config.images) {
+      for (let dx = 0; dx < img.span; dx++) {
+        for (let dy = 0; dy < img.span; dy++) {
+          const cx = img.gridX + dx;
+          const ry = img.gridY + dy;
+          if (cx < gridColumns && ry < gridRows) {
+            occupied[cx][ry] = true;
+          }
+        }
+      }
+    }
+    const result = [];
+    const tempOccupied = occupied.map((row) => [...row]);
+    for (let r = 0; r <= gridRows - targetSpan; r++) {
+      for (let c = 0; c <= gridColumns - targetSpan; c++) {
+        let isFree = true;
+        for (let dx = 0; dx < targetSpan; dx++) {
+          for (let dy = 0; dy < targetSpan; dy++) {
+            if (tempOccupied[c + dx][r + dy]) {
+              isFree = false;
+              break;
+            }
+          }
+          if (!isFree) break;
+        }
+        if (isFree) {
+          result.push({ gridX: c, gridY: r, span: targetSpan });
+          for (let dx = 0; dx < targetSpan; dx++) {
+            for (let dy = 0; dy < targetSpan; dy++) {
+              tempOccupied[c + dx][r + dy] = true;
+            }
+          }
+        }
+      }
+    }
+    return result;
+  }
+  // --- Rendering Pipeline ---
+  render(drawUI = true) {
+    if (!this.canvas || !this.ctx) return;
+    const dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
+    const rect = this.canvas.getBoundingClientRect();
+    const w = rect.width > 0 ? rect.width : this.canvas.width / dpr || 300;
+    const h = rect.height > 0 ? rect.height : this.canvas.height / dpr || 400;
+    const targetWidth = Math.round(w * dpr);
+    const targetHeight = Math.round(h * dpr);
+    if (this.canvas.width !== targetWidth || this.canvas.height !== targetHeight) {
+      this.canvas.width = targetWidth;
+      this.canvas.height = targetHeight;
+      this.canvas.style.width = `${w}px`;
+      this.canvas.style.height = `${h}px`;
+    }
+    this.ctx.save();
+    this.ctx.clearRect(0, 0, targetWidth, targetHeight);
+    this.ctx.scale(dpr, dpr);
+    this.draw(this.ctx, w, h, drawUI);
+    this.ctx.restore();
+  }
+  /**
+   * The master draw function: compiles background, images, and overlays.
+   * Can be shared between interactive Canvas on the page and high-res offscreen Canvas.
+   */
+  draw(ctx, width, height, drawUI) {
+    const layout = this.calculateLayout(width, height);
+    if (!this.config.useTransparentBg) {
+      ctx.fillStyle = this.config.containerBgColor || "#ffffff";
+      ctx.fillRect(0, 0, width, height);
+    } else {
+      ctx.clearRect(0, 0, width, height);
+    }
+    let draggedImgData = null;
+    let draggedImgRect = null;
+    for (const img of this.config.images) {
+      const rect = this.getImageRect(img, layout);
+      const isDraggedSelf = this.isDragging && this.draggedImageId === img.id;
+      const borderRadius = (img.borderRadius2K ?? this.config.imageBorderRadius2K ?? 24) * layout.scale;
+      if (isDraggedSelf && drawUI) {
+        draggedImgData = img;
+        draggedImgRect = rect;
+        ctx.save();
+        ctx.strokeStyle = "rgba(148, 163, 184, 0.4)";
+        ctx.lineWidth = 1.5;
+        ctx.setLineDash([4, 4]);
+        ctx.fillStyle = "rgba(241, 245, 249, 0.05)";
+        ctx.beginPath();
+        ctx.roundRect(rect.x, rect.y, rect.w, rect.h, borderRadius);
+        ctx.fill();
+        ctx.stroke();
+        ctx.restore();
+        continue;
+      }
+      ctx.save();
+      const shadowBlur = (img.shadowBlur2K ?? this.config.imageShadowBlur2K ?? 0) * layout.scale;
+      const shadowOffset = (img.shadowOffset2K ?? this.config.imageShadowOffset2K ?? 0) * layout.scale;
+      const shadowOpacity = img.shadowOpacity ?? this.config.imageShadowOpacity ?? 0.2;
+      if (shadowBlur > 0 || shadowOffset > 0) {
+        ctx.save();
+        ctx.shadowColor = `rgba(15, 23, 42, ${shadowOpacity})`;
+        ctx.shadowBlur = shadowBlur;
+        ctx.shadowOffsetX = shadowOffset;
+        ctx.shadowOffsetY = shadowOffset;
+        ctx.fillStyle = "#ffffff";
+        ctx.beginPath();
+        ctx.roundRect(rect.x, rect.y, rect.w, rect.h, borderRadius);
+        ctx.fill();
+        ctx.restore();
+      }
+      ctx.save();
+      ctx.beginPath();
+      ctx.roundRect(rect.x, rect.y, rect.w, rect.h, borderRadius);
+      ctx.clip();
+      const imgElement = this.getOrLoadImage(img.src);
+      if (imgElement) {
+        drawImageCover(ctx, imgElement, rect.x, rect.y, rect.w, rect.h);
+      } else {
+        ctx.fillStyle = "#e2e8f0";
+        ctx.fillRect(rect.x, rect.y, rect.w, rect.h);
+        ctx.fillStyle = "#94a3b8";
+        ctx.font = `bold 12px sans-serif`;
+        ctx.textAlign = "center";
+        ctx.textBaseline = "middle";
+        ctx.fillText("\u52A0\u8F7D\u4E2D...", rect.x + rect.w / 2, rect.y + rect.h / 2);
+      }
+      ctx.restore();
+      ctx.strokeStyle = "rgba(148, 163, 184, 0.4)";
+      ctx.lineWidth = Math.max(1, 1 * layout.scale);
+      ctx.beginPath();
+      ctx.roundRect(rect.x, rect.y, rect.w, rect.h, borderRadius);
+      ctx.stroke();
+      ctx.restore();
+    }
+    if (drawUI) {
+      ctx.strokeStyle = "rgba(79, 70, 229, 0.15)";
+      ctx.lineWidth = 1.5;
+      ctx.setLineDash([6, 6]);
+      ctx.beginPath();
+      ctx.roundRect(layout.padding, layout.padding, width - layout.padding * 2, height - layout.padding * 2, 12);
+      ctx.stroke();
+      ctx.setLineDash([]);
+      if (this.config.showGridlines) {
+        ctx.strokeStyle = "rgba(203, 213, 225, 0.35)";
+        ctx.lineWidth = 1;
+        ctx.setLineDash([4, 4]);
+        for (let i = 1; i < this.config.gridColumns; i++) {
+          const lineX = layout.offsetX + i * layout.cellW + (i - 1) * layout.gap + layout.gap / 2;
+          ctx.beginPath();
+          ctx.moveTo(lineX, layout.padding);
+          ctx.lineTo(lineX, layout.padding + layout.gridH);
+          ctx.stroke();
+        }
+        for (let i = 1; i < layout.gridRows; i++) {
+          const lineY = layout.offsetY + i * layout.cellH + (i - 1) * layout.gap + layout.gap / 2;
+          ctx.beginPath();
+          ctx.moveTo(layout.padding, lineY);
+          ctx.lineTo(layout.padding + layout.gridW, lineY);
+          ctx.stroke();
+        }
+        ctx.setLineDash([]);
+      }
+      const targetSpan = this.getCurrentTargetSpan();
+      const placeholders = this.getPlaceholders(targetSpan, layout.gridRows);
+      for (const slot of placeholders) {
+        const slotX = layout.offsetX + slot.gridX * (layout.cellW + layout.gap);
+        const slotY = layout.offsetY + slot.gridY * (layout.cellH + layout.gap);
+        const slotW = slot.span * layout.cellW + (slot.span - 1) * layout.gap;
+        const slotH = slot.span * layout.cellH + (slot.span - 1) * layout.gap;
+        const isHovered = this.hoveredPlaceholder && this.hoveredPlaceholder.gridX === slot.gridX && this.hoveredPlaceholder.gridY === slot.gridY;
+        ctx.save();
+        ctx.strokeStyle = isHovered ? "rgba(79, 70, 229, 0.5)" : "rgba(79, 70, 229, 0.2)";
+        ctx.lineWidth = isHovered ? 2 : 1.5;
+        ctx.setLineDash([5, 5]);
+        ctx.fillStyle = isHovered ? "rgba(79, 70, 229, 0.05)" : "transparent";
+        const slotRadius = Math.max(6, (this.config.imageBorderRadius2K ?? 24) * layout.scale);
+        ctx.beginPath();
+        ctx.roundRect(slotX, slotY, slotW, slotH, slotRadius);
+        ctx.fill();
+        ctx.stroke();
+        const color = isHovered ? "rgba(79, 70, 229, 0.8)" : "rgba(148, 163, 184, 0.5)";
+        ctx.strokeStyle = color;
+        ctx.lineWidth = 2;
+        ctx.setLineDash([]);
+        const showText = slotW >= 90 && slotH >= 65;
+        const centerCX = slotX + slotW / 2;
+        const centerCY = showText ? slotY + slotH / 2 - 10 : slotY + slotH / 2;
+        const plusSize = 7;
+        ctx.beginPath();
+        ctx.moveTo(centerCX - plusSize, centerCY);
+        ctx.lineTo(centerCX + plusSize, centerCY);
+        ctx.moveTo(centerCX, centerCY - plusSize);
+        ctx.lineTo(centerCX, centerCY + plusSize);
+        ctx.stroke();
+        if (showText) {
+          ctx.fillStyle = isHovered ? "rgba(79, 70, 229, 1)" : "rgba(148, 163, 184, 0.7)";
+          ctx.font = `500 12px sans-serif`;
+          ctx.textAlign = "center";
+          ctx.textBaseline = "top";
+          ctx.fillText("\u70B9\u51FB\u4E0A\u4F20\u6216\u62D6\u5165", slotX + slotW / 2, centerCY + plusSize + 6);
+          ctx.fillStyle = "rgba(148, 163, 184, 0.4)";
+          ctx.font = `10px monospace`;
+          ctx.fillText(`(${slot.gridX + 1}, ${slot.gridY + 1})`, slotX + slotW / 2, centerCY + plusSize + 22);
+        }
+        ctx.restore();
+      }
+      if (this.activeImageId) {
+        const activeImg = this.config.images.find((img) => img.id === this.activeImageId);
+        if (activeImg) {
+          const rect = this.getImageRect(activeImg, layout);
+          ctx.save();
+          ctx.strokeStyle = "rgba(79, 70, 229, 1)";
+          ctx.lineWidth = 3;
+          ctx.beginPath();
+          const offset = 3;
+          const activeBorderRadius = (activeImg.borderRadius2K ?? this.config.imageBorderRadius2K ?? 24) * layout.scale;
+          const ringRadius = activeBorderRadius + offset;
+          ctx.roundRect(
+            rect.x - offset,
+            rect.y - offset,
+            rect.w + offset * 2,
+            rect.h + offset * 2,
+            ringRadius
+          );
+          ctx.stroke();
+          ctx.restore();
+        }
+      }
+      if (this.isDragging && this.draggedOverCell && this.draggedImageId) {
+        const draggedImg = this.config.images.find((img) => img.id === this.draggedImageId);
+        if (draggedImg) {
+          const previewX = layout.offsetX + this.draggedOverCell.x * (layout.cellW + layout.gap);
+          const previewY = layout.offsetY + this.draggedOverCell.y * (layout.cellH + layout.gap);
+          const previewW = draggedImg.span * layout.cellW + (draggedImg.span - 1) * layout.gap;
+          const previewH = draggedImg.span * layout.cellH + (draggedImg.span - 1) * layout.gap;
+          ctx.save();
+          ctx.strokeStyle = "rgba(79, 70, 229, 1)";
+          ctx.lineWidth = 1.5;
+          ctx.setLineDash([6, 4]);
+          ctx.fillStyle = "rgba(79, 70, 229, 0.12)";
+          const previewRadius = (draggedImg.borderRadius2K ?? this.config.imageBorderRadius2K ?? 24) * layout.scale;
+          ctx.beginPath();
+          ctx.roundRect(previewX, previewY, previewW, previewH, previewRadius);
+          ctx.fill();
+          ctx.stroke();
+          ctx.restore();
+        }
+      }
+      if (this.isDragging && draggedImgData && draggedImgRect) {
+        const floatX = this.dragCurrentPos.x - this.dragStartOffset.x;
+        const floatY = this.dragCurrentPos.y - this.dragStartOffset.y;
+        const floatW = draggedImgRect.w;
+        const floatH = draggedImgRect.h;
+        const borderRadius = (draggedImgData.borderRadius2K ?? this.config.imageBorderRadius2K ?? 24) * layout.scale;
+        ctx.save();
+        ctx.beginPath();
+        ctx.roundRect(floatX, floatY, floatW, floatH, borderRadius);
+        ctx.shadowColor = "rgba(15, 23, 42, 0.4)";
+        ctx.shadowBlur = 16;
+        ctx.shadowOffsetX = 0;
+        ctx.shadowOffsetY = 8;
+        ctx.fillStyle = "#ffffff";
+        ctx.fill();
+        ctx.restore();
+        ctx.save();
+        ctx.globalAlpha = 0.85;
+        ctx.beginPath();
+        ctx.roundRect(floatX, floatY, floatW, floatH, borderRadius);
+        ctx.clip();
+        const imgElement = this.getOrLoadImage(draggedImgData.src);
+        if (imgElement) {
+          drawImageCover(ctx, imgElement, floatX, floatY, floatW, floatH);
+        } else {
+          ctx.fillStyle = "#e2e8f0";
+          ctx.fillRect(floatX, floatY, floatW, floatH);
+        }
+        ctx.restore();
+        ctx.save();
+        ctx.strokeStyle = "rgba(79, 70, 229, 0.9)";
+        ctx.lineWidth = 2;
+        ctx.beginPath();
+        ctx.roundRect(floatX, floatY, floatW, floatH, borderRadius);
+        ctx.stroke();
+        ctx.restore();
+      }
+    }
+  }
+  // --- Headless Offscreen Export PNG ---
+  async exportPNG(targetWidth = 2048) {
+    const containerRatioVal = (() => {
+      if (this.config.containerRatio === "custom") {
+        return (this.config.customContainerW || 3) / (this.config.customContainerH || 4);
+      }
+      const parts = this.config.containerRatio.split(":");
+      return Number(parts[0]) / Number(parts[1]);
+    })();
+    const exportHeight = Math.round(targetWidth / containerRatioVal);
+    const offscreenCanvas = document.createElement("canvas");
+    offscreenCanvas.width = targetWidth;
+    offscreenCanvas.height = exportHeight;
+    const offscreenCtx = offscreenCanvas.getContext("2d");
+    if (!offscreenCtx) throw new Error("Could not create 2D offscreen canvas context");
+    await this.preloadAllImages();
+    this.draw(offscreenCtx, targetWidth, exportHeight, false);
+    return offscreenCanvas.toDataURL("image/png");
+  }
+};
+function drawImageCover(ctx, img, x, y, w, h) {
+  const imgRatio = img.width / img.height;
+  const targetRatio = w / h;
+  let sx = 0, sy = 0, sw = img.width, sh = img.height;
+  if (imgRatio > targetRatio) {
+    sw = img.height * targetRatio;
+    sx = (img.width - sw) / 2;
+  } else {
+    sh = img.width / targetRatio;
+    sy = (img.height - sh) / 2;
+  }
+  ctx.drawImage(img, sx, sy, sw, sh, x, y, w, h);
+}
+export {
+  AspectGridCollageify
+};