@bensitu/image-editor 1.1.2 → 1.2.1

package/dist/image-editor.js

@@ -0,0 +1,2001 @@
+(() => {
+  // src/image-editor.js
+  /**
+   * @file image-editor.js
+   * @module image-editor
+   * @version 1.2.1
+   * @author Ben Situ
+   * @license MIT
+   * @description Lightweight canvas-based image editor with masking/transform/export support.
+   *
+   * This source file is free software, available under the MIT license.
+   * It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+   * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+   * See the license files for details.
+   */
+  var fabric = null;
+  function getGlobalScope() {
+    if (typeof globalThis !== "undefined")
+      return globalThis;
+    if (typeof self !== "undefined")
+      return self;
+    if (typeof window !== "undefined")
+      return window;
+    return null;
+  }
+  function getGlobalFabric() {
+    const scope2 = getGlobalScope();
+    return scope2 && scope2.fabric ? scope2.fabric : null;
+  }
+  function setFabric(fabricInstance) {
+    fabric = fabricInstance || getGlobalFabric();
+    return fabric;
+  }
+  function ensureFabric() {
+    if (!fabric)
+      setFabric();
+    return fabric;
+  }
+  var ImageEditor = class {
+    constructor(options = {}) {
+      const defaultLabel = {
+        getText: (mask) => mask.maskName,
+        textOptions: {
+          fontSize: 12,
+          fill: "#fff",
+          backgroundColor: "rgba(0,0,0,0.7)",
+          padding: 2,
+          fontFamily: "monospace",
+          fontWeight: "bold",
+          selectable: false,
+          evented: false,
+          originX: "left",
+          originY: "top"
+        }
+      };
+      const defaultCrop = {
+        minWidth: 100,
+        minHeight: 100,
+        padding: 10,
+        hideMasksDuringCrop: true,
+        preserveMasksAfterCrop: false,
+        allowRotationOfCropRect: false
+      };
+      const userLabel = options.label || {};
+      const userCrop = options.crop || {};
+      this.options = {
+        canvasWidth: 800,
+        canvasHeight: 600,
+        backgroundColor: "transparent",
+        animationDuration: 300,
+        minScale: 0.1,
+        maxScale: 5,
+        scaleStep: 0.05,
+        rotationStep: 90,
+        expandCanvasToImage: true,
+        fitImageToCanvas: false,
+        coverImageToCanvas: false,
+        downsampleOnLoad: true,
+        downsampleMaxWidth: 4e3,
+        downsampleMaxHeight: 3e3,
+        downsampleQuality: 0.92,
+        exportMultiplier: 1,
+        exportImageAreaByDefault: true,
+        defaultMaskWidth: 50,
+        defaultMaskHeight: 80,
+        maskRotatable: false,
+        maskLabelOnSelect: true,
+        maskLabelOffset: 3,
+        maskName: "mask",
+        groupSelection: false,
+        showPlaceholder: true,
+        initialImageBase64: null,
+        // Provide a base64 'data:image/...' string here if you want auto-load
+        defaultDownloadFileName: "edited_image.jpg",
+        onError: null,
+        onWarning: null,
+        ...options,
+        label: {
+          ...defaultLabel,
+          ...userLabel,
+          textOptions: {
+            ...defaultLabel.textOptions,
+            ...userLabel.textOptions || {}
+          }
+        },
+        crop: {
+          ...defaultCrop,
+          ...userCrop
+        }
+      };
+      this._fabricLoaded = !!ensureFabric();
+      if (!this._fabricLoaded) {
+        this._reportError("fabric.js is not loaded. Please include fabric.js first. Initialization will be aborted.");
+      }
+      this.canvas = null;
+      this.canvasEl = null;
+      this.containerEl = null;
+      this.placeholderEl = null;
+      this.originalImage = null;
+      this.baseImageScale = 1;
+      this.currentScale = 1;
+      this.currentRotation = 0;
+      this.maskCounter = 0;
+      this.isAnimating = false;
+      this.elements = {};
+      this.isImageLoadedToCanvas = false;
+      this.maxHistorySize = 50;
+      this._boundHandlers = {};
+      this._lastMask = null;
+      this._lastMaskInitialLeft = null;
+      this._lastMaskInitialTop = null;
+      this._lastMaskInitialWidth = null;
+      this._cropMode = false;
+      this._cropRect = null;
+      this._cropHandlers = [];
+      this.onImageLoaded = typeof options.onImageLoaded === "function" ? options.onImageLoaded : null;
+      this.animQueue = new AnimationQueue();
+      this.historyManager = new HistoryManager(this.maxHistorySize);
+    }
+    /**
+     * Initializes the editor, binds to DOM elements, sets up event handlers,
+     * and (optionally) loads an initial image.
+     * Use this method to set up the editor UI before interacting with it.
+     *
+     * @param {Object} [idMap={}] - Optional mapping from logical element names to actual DOM element IDs.
+     *   Supported keys include: canvas, canvasContainer, imgPlaceholder, scaleRate, rotationLeftInput, rotationRightInput,
+     *   rotateLeftBtn, rotateRightBtn, addMaskBtn, removeMaskBtn, removeAllMasksBtn, mergeBtn, downloadBtn, maskList,
+     *   zoomInBtn, zoomOutBtn, resetBtn, imageInput. Unknown keys are ignored.
+     *
+     * @returns {void}
+     *
+     * @public
+     *
+     * @example
+     * editor.init({
+     *   canvas: 'myFabricCanvasId',
+     *   downloadBtn: 'myDownloadButtonId'
+     * });
+     */
+    init(idMap = {}) {
+      if (!this._fabricLoaded)
+        return;
+      const defaults = {
+        canvas: "fabricCanvas",
+        canvasContainer: null,
+        // Pass an ID here if you have a scrollable viewport container
+        imgPlaceholder: "imgPlaceholder",
+        scaleRate: "scaleRate",
+        rotationLeftInput: "rotationLeftInput",
+        rotationRightInput: "rotationRightInput",
+        rotateLeftBtn: "rotateLeftBtn",
+        rotateRightBtn: "rotateRightBtn",
+        addMaskBtn: "addMaskBtn",
+        removeMaskBtn: "removeMaskBtn",
+        removeAllMasksBtn: "removeAllMasksBtn",
+        mergeBtn: "mergeBtn",
+        downloadBtn: "downloadBtn",
+        maskList: "maskList",
+        zoomInBtn: "zoomInBtn",
+        zoomOutBtn: "zoomOutBtn",
+        resetBtn: "resetBtn",
+        undoBtn: "undoBtn",
+        redoBtn: "redoBtn",
+        imageInput: "imageInput",
+        cropBtn: "cropBtn",
+        applyCropBtn: "applyCropBtn",
+        cancelCropBtn: "cancelCropBtn"
+      };
+      this.elements = { ...defaults, ...idMap };
+      this._initCanvas();
+      this._bindEvents();
+      this._updateInputs();
+      this._updateMaskList();
+      this._updateUI();
+      if (this.options.initialImageBase64) {
+        this.loadImage(this.options.initialImageBase64);
+      } else {
+        this._updatePlaceholderStatus();
+      }
+    }
+    _reportError(message, error = null) {
+      const handler = this.options && this.options.onError;
+      if (typeof handler !== "function")
+        return;
+      try {
+        handler(error, message);
+      } catch {
+      }
+    }
+    _reportWarning(message, error = null) {
+      const handler = this.options && this.options.onWarning;
+      if (typeof handler !== "function")
+        return;
+      try {
+        handler(error, message);
+      } catch {
+      }
+    }
+    /**
+     * Canvas setup helpers
+     * @private
+     */
+    _initCanvas() {
+      const canvasEl = document.getElementById(this.elements.canvas);
+      if (!canvasEl)
+        throw new Error("Canvas is not found: " + this.elements.canvas);
+      this.canvasEl = canvasEl;
+      if (this.elements.canvasContainer) {
+        const ce = document.getElementById(this.elements.canvasContainer);
+        this.containerEl = ce || canvasEl.parentElement;
+      } else {
+        this.containerEl = canvasEl.parentElement;
+      }
+      this.placeholderEl = document.getElementById(this.elements.imgPlaceholder) || null;
+      let initialW = this.options.canvasWidth;
+      let initialH = this.options.canvasHeight;
+      if (this.containerEl) {
+        const cw = Math.floor(this.containerEl.clientWidth);
+        const ch = Math.floor(this.containerEl.clientHeight);
+        if (cw > 0 && ch > 0) {
+          initialW = cw;
+          initialH = ch;
+        }
+      }
+      this.canvas = new fabric.Canvas(canvasEl, {
+        width: initialW,
+        height: initialH,
+        backgroundColor: this.options.backgroundColor,
+        selection: this.options.groupSelection,
+        preserveObjectStacking: true
+      });
+      this.canvas.on("selection:created", (e) => this._onSelectionChanged(e.selected));
+      this.canvas.on("selection:updated", (e) => this._onSelectionChanged(e.selected));
+      this.canvas.on("selection:cleared", () => this._onSelectionChanged([]));
+      this.canvas.on("object:moving", (e) => {
+        if (e.target && e.target.maskId)
+          this._syncMaskLabel(e.target);
+      });
+      this.canvas.on("object:scaling", (e) => {
+        if (e.target && e.target.maskId)
+          this._syncMaskLabel(e.target);
+      });
+      this.canvas.on("object:rotating", (e) => {
+        if (e.target && e.target.maskId)
+          this._syncMaskLabel(e.target);
+      });
+      this.canvas.on("object:modified", (e) => {
+        if (e.target && e.target.maskId)
+          this._syncMaskLabel(e.target);
+      });
+      this.canvasEl.style.display = "block";
+    }
+    /** 
+     * DOM / UI bindings
+     * @private
+     */
+    _bindEvents() {
+      this._bindIfExists("uploadArea", "click", () => document.getElementById(this.elements.imageInput)?.click());
+      const inputEl = document.getElementById(this.elements.imageInput);
+      if (inputEl) {
+        inputEl.addEventListener("change", (e) => {
+          const f = e.target.files && e.target.files[0];
+          if (f)
+            this._loadImageFile(f);
+        });
+      }
+      this._bindIfExists("zoomInBtn", "click", () => this.scaleImage(this.currentScale + this.options.scaleStep));
+      this._bindIfExists("zoomOutBtn", "click", () => this.scaleImage(this.currentScale - this.options.scaleStep));
+      this._bindIfExists("resetBtn", "click", () => {
+        this.reset();
+      });
+      this._bindIfExists("addMaskBtn", "click", () => this.addMask());
+      this._bindIfExists("removeMaskBtn", "click", () => this.removeSelectedMask());
+      this._bindIfExists("removeAllMasksBtn", "click", () => this.removeAllMasks());
+      this._bindIfExists("mergeBtn", "click", () => this.merge());
+      this._bindIfExists("downloadBtn", "click", () => this.downloadImage());
+      this._bindIfExists("undoBtn", "click", () => this.undo());
+      this._bindIfExists("redoBtn", "click", () => this.redo());
+      const rotLeftBtn = document.getElementById(this.elements.rotateLeftBtn);
+      const rotRightBtn = document.getElementById(this.elements.rotateRightBtn);
+      if (rotLeftBtn)
+        rotLeftBtn.addEventListener("click", () => {
+          const el = document.getElementById(this.elements.rotationLeftInput);
+          let step = this.options.rotationStep;
+          if (el) {
+            const p = parseFloat(el.value);
+            if (!isNaN(p))
+              step = p;
+          }
+          this.rotateImage(this.currentRotation - step);
+        });
+      if (rotRightBtn)
+        rotRightBtn.addEventListener("click", () => {
+          const el = document.getElementById(this.elements.rotationRightInput);
+          let step = this.options.rotationStep;
+          if (el) {
+            const p = parseFloat(el.value);
+            if (!isNaN(p))
+              step = p;
+          }
+          this.rotateImage(this.currentRotation + step);
+        });
+      this._bindIfExists("cropBtn", "click", () => this.enterCropMode());
+      this._bindIfExists("applyCropBtn", "click", () => {
+        this.applyCrop().catch((e) => this._reportError("applyCrop failed", e));
+      });
+      this._bindIfExists("cancelCropBtn", "click", () => this.cancelCrop());
+    }
+    /** 
+     * Event binding element check
+     * 
+     * @param {*} event 
+     * @param {*} handler 
+     * @param {*} key 
+     * @private
+     */
+    _bindIfExists(key, event, handler) {
+      const el = document.getElementById(this.elements[key]);
+      if (el) {
+        el.addEventListener(event, handler);
+        this._boundHandlers = this._boundHandlers || {};
+        if (!this._boundHandlers[key])
+          this._boundHandlers[key] = [];
+        this._boundHandlers[key].push({ event, handler });
+      }
+    }
+    /** 
+     * Image loading helpers
+     * 
+     * @param {File} file 
+     * @private
+     */
+    _loadImageFile(file) {
+      if (!file || !file.type.startsWith("image/"))
+        return;
+      const reader = new FileReader();
+      reader.onload = (e) => this.loadImage(e.target.result);
+      reader.onerror = (e) => {
+        this._reportError("Image file could not be read", e);
+      };
+      reader.readAsDataURL(file);
+    }
+    /**
+    * Load a base64 encoded image string into fabric.
+    * @async
+    * @param {String} base64 
+    */
+    async loadImage(base64) {
+      if (!this._fabricLoaded)
+        return;
+      if (!this.canvas)
+        return;
+      if (!base64 || typeof base64 !== "string" || !base64.startsWith("data:image/"))
+        return;
+      this._setPlaceholderVisible(false);
+      const imgEl = await this._createImageElement(base64);
+      let loadSrc = base64;
+      if (this.options.downsampleOnLoad) {
+        const needResize = imgEl.naturalWidth > this.options.downsampleMaxWidth || imgEl.naturalHeight > this.options.downsampleMaxHeight;
+        if (needResize) {
+          const ratio = Math.min(
+            this.options.downsampleMaxWidth / imgEl.naturalWidth,
+            this.options.downsampleMaxHeight / imgEl.naturalHeight
+          );
+          const tw = Math.round(imgEl.naturalWidth * ratio);
+          const th = Math.round(imgEl.naturalHeight * ratio);
+          loadSrc = this._resampleImageToDataURL(imgEl, tw, th, this.options.downsampleQuality);
+        }
+      }
+      return new Promise((resolve, reject) => {
+        fabric.Image.fromURL(loadSrc, (fimg) => {
+          try {
+            if (!fimg)
+              throw new Error("Image could not be loaded");
+            this.canvas.discardActiveObject();
+            this._hideAllMaskLabels();
+            this.canvas.clear();
+            this.canvas.setBackgroundColor(this.options.backgroundColor, this.canvas.renderAll.bind(this.canvas));
+            fimg.set({ originX: "left", originY: "top", selectable: false, evented: false });
+            const imgW = fimg.width;
+            const imgH = fimg.height;
+            const minW = this.containerEl ? Math.floor(this.containerEl.clientWidth || this.options.canvasWidth) : this.options.canvasWidth;
+            const minH = this.containerEl ? Math.floor(this.containerEl.clientHeight || this.options.canvasHeight) : this.options.canvasHeight;
+            if (this.options.fitImageToCanvas) {
+              const cw = Math.max(1, Math.min(this.options.canvasWidth, minW) - 1);
+              const ch = Math.max(1, Math.min(this.options.canvasHeight, minH) - 1);
+              this._setCanvasSizeInt(cw, ch);
+              const fitScale = Math.min(cw / imgW, ch / imgH, 1);
+              fimg.set({ left: 0, top: 0 });
+              fimg.scale(fitScale);
+              this.baseImageScale = fimg.scaleX || 1;
+            } else if (this.options.coverImageToCanvas) {
+              const cw = Math.max(this.options.canvasWidth, minW);
+              const ch = Math.max(this.options.canvasHeight, minH);
+              this._setCanvasSizeInt(cw, ch);
+              const coverScale = Math.min(1, Math.max(cw / imgW, ch / imgH));
+              fimg.set({ left: 0, top: 0 });
+              fimg.scale(coverScale);
+              this.baseImageScale = fimg.scaleX || 1;
+            } else if (this.options.expandCanvasToImage) {
+              const cw = Math.max(minW, Math.floor(imgW));
+              const ch = Math.max(minH, Math.floor(imgH));
+              this._setCanvasSizeInt(cw, ch);
+              fimg.set({ left: 0, top: 0 });
+              fimg.scale(1);
+              this.baseImageScale = 1;
+            } else {
+              const cw = Math.max(this.options.canvasWidth, minW);
+              const ch = Math.max(this.options.canvasHeight, minH);
+              this._setCanvasSizeInt(cw, ch);
+              const fitScale = Math.min(cw / imgW, ch / imgH, 1);
+              fimg.set({ left: 0, top: 0 });
+              fimg.scale(fitScale);
+              this.baseImageScale = fimg.scaleX || 1;
+            }
+            this.originalImage = fimg;
+            this.canvas.add(fimg);
+            this.canvas.sendToBack(fimg);
+            this._lastMask = null;
+            this._lastMaskInitialLeft = null;
+            this._lastMaskInitialTop = null;
+            this._lastMaskInitialWidth = null;
+            this.maskCounter = 0;
+            this.currentScale = 1;
+            this.currentRotation = 0;
+            this._updateInputs();
+            this._updateMaskList();
+            this.isImageLoadedToCanvas = true;
+            this._updateUI();
+            this.canvas.renderAll();
+            if (typeof this.onImageLoaded === "function") {
+              this.onImageLoaded();
+            }
+            resolve();
+          } catch (err) {
+            reject(err);
+          }
+        }, { crossOrigin: "anonymous" });
+      });
+    }
+    /**
+     * Checks whether there is a loaded image on the current canvas.
+     * @returns {boolean} true if loaded, false if not
+     */
+    isImageLoaded() {
+      const fabricInstance = ensureFabric();
+      return !!(this.originalImage && fabricInstance && this.originalImage instanceof fabricInstance.Image && this.originalImage.width > 0 && this.originalImage.height > 0);
+    }
+    /**
+     * Creates an HTMLImageElement from a given data URL.
+     * 
+     * @param {string} dataURL - A data URL representing the image (e.g., "data:image/png;base64,...").
+     * @returns {Promise<HTMLImageElement>} A promise that resolves to the created image element when loaded, or rejects on error.
+     * @private
+     */
+    _createImageElement(dataURL) {
+      return new Promise((res, rej) => {
+        const img = new Image();
+        img.onload = () => {
+          img.onload = null;
+          img.onerror = null;
+          res(img);
+        };
+        img.onerror = (e) => {
+          img.onload = null;
+          img.onerror = null;
+          rej(e);
+        };
+        img.src = dataURL;
+      });
+    }
+    /**
+     * Resamples the given image element to a new width and height and returns the result as a JPEG data URL.
+     * 
+     * @param {HTMLImageElement} imgEl - The image element to resample.
+     * @param {number} w - Target width (in pixels) for the resampled image.
+     * @param {number} h - Target height (in pixels) for the resampled image.
+     * @param {number} [quality=0.92] - JPEG image quality between 0 and 1 (optional, default 0.92).
+     * @returns {string} A data URL representing the resampled image as JPEG.
+     * @private
+     */
+    _resampleImageToDataURL(imgEl, w, h, quality = 0.92) {
+      const oc = document.createElement("canvas");
+      oc.width = w;
+      oc.height = h;
+      const ctx = oc.getContext("2d");
+      ctx.drawImage(imgEl, 0, 0, imgEl.naturalWidth, imgEl.naturalHeight, 0, 0, w, h);
+      return oc.toDataURL("image/jpeg", quality);
+    }
+    /** 
+     * Sets canvas size to integer width and height values to prevent scrollbars due to sub-pixel rendering.
+     * Also updates the corresponding style attributes.
+     * 
+     * @param {number} w - Canvas width (in pixels).
+     * @param {number} h - Canvas height (in pixels).
+     * @private
+     */
+    _setCanvasSizeInt(w, h) {
+      const iw = Math.max(1, Math.round(Number(w) || 1));
+      const ih = Math.max(1, Math.round(Number(h) || 1));
+      this.canvas.setWidth(iw);
+      this.canvas.setHeight(ih);
+      if (typeof this.canvas.calcOffset === "function")
+        this.canvas.calcOffset();
+      if (this.canvasEl) {
+        this.canvasEl.style.width = iw + "px";
+        this.canvasEl.style.height = ih + "px";
+        this.canvasEl.style.maxWidth = "none";
+      }
+    }
+    /** 
+     * Gets the top-left corner coordinates of the given object.
+     * Used for geometry calculations (e.g., scale, rotate).
+     * 
+     * @param {Object} obj - The object for which to get the top-left coordinates. Should support setCoords and getCoords/getBoundingRect methods.
+     * @returns {{x: number, y: number}} The top-left corner point as an object with x and y properties.
+     * @private
+     */
+    _getObjectTopLeftPoint(obj) {
+      if (!obj)
+        return { x: 0, y: 0 };
+      obj.setCoords();
+      const coords = typeof obj.getCoords === "function" ? obj.getCoords() : null;
+      if (coords && coords.length)
+        return coords[0];
+      const br = obj.getBoundingRect(true, true);
+      return { x: br.left, y: br.top };
+    }
+    /**
+     * Sets the object's origin at the specified origin point, keeping a reference point fixed in position.
+     * 
+     * @param {Object} obj - The object to modify. Should support set, setPositionByOrigin, and setCoords.
+     * @param {string} originX - The new originX ("left", "center", "right", etc.).
+     * @param {string} originY - The new originY ("top", "center", "bottom", etc.).
+     * @param {{x: number, y: number}} refPoint - The point to keep fixed while setting the new origins.
+     * @private
+     */
+    _setObjectOriginKeepingPosition(obj, originX, originY, refPoint) {
+      if (!obj || !refPoint || !obj.setPositionByOrigin)
+        return;
+      obj.set({ originX, originY });
+      obj.setPositionByOrigin(refPoint, originX, originY);
+      obj.setCoords();
+    }
+    /**
+     * Moves the object so its bounding box aligns with the canvas's top-left corner (0, 0).
+     * 
+     * @param {Object} obj - The object to align.
+     * @private
+     */
+    _alignObjectBoundingBoxToCanvasTopLeft(obj) {
+      if (!obj)
+        return;
+      obj.setCoords();
+      const br = obj.getBoundingRect(true, true);
+      const dx = br.left;
+      const dy = br.top;
+      obj.set({ left: (obj.left || 0) - dx, top: (obj.top || 0) - dy });
+      obj.setCoords();
+      this.canvas.renderAll();
+    }
+    /**
+     * Updates the canvas size to match the bounding box of the original image,
+     * ensuring that the canvas is always at least as large as its container.
+     * @private
+     */
+    _updateCanvasSizeToImageBounds() {
+      if (!this.originalImage)
+        return;
+      this.originalImage.setCoords();
+      const br = this.originalImage.getBoundingRect(true, true);
+      const containerW = this.containerEl ? Math.ceil(this.containerEl.clientWidth || 0) : 0;
+      const containerH = this.containerEl ? Math.ceil(this.containerEl.clientHeight || 0) : 0;
+      if (containerW > 0 && containerH > 0 && br.width <= containerW && br.height <= containerH) {
+        this._setCanvasSizeInt(containerW, containerH);
+        return;
+      }
+      const newW = Math.max(containerW || 0, Math.floor(br.width));
+      const newH = Math.max(containerH || 0, Math.floor(br.height));
+      this._setCanvasSizeInt(newW, newH);
+    }
+    /** 
+     * Scales the original image by a given factor, with animation.
+     * Returns a promise that resolves when the scale animation is complete.
+     * @param {number} factor - The scaling factor (will be clamped between `options.minScale` and `options.maxScale`).
+     * @returns {Promise<void>} Promise that resolves once the scaling animation finishes.
+     * @public
+     */
+    scaleImage(factor) {
+      return this.animQueue.add(() => this._scaleImageImpl(factor));
+    }
+    /** 
+     * Scales the original image by a given factor, with animation.
+     * Returns a promise that resolves when the scale animation is complete.
+     * @param {number} factor - The scaling factor (will be clamped between `options.minScale` and `options.maxScale`).
+     * @returns {Promise<void>} Promise that resolves once the scaling animation finishes.
+     * @private
+     */
+    _scaleImageImpl(factor) {
+      if (!this.originalImage)
+        return Promise.resolve();
+      if (this.isAnimating)
+        return Promise.resolve();
+      factor = Math.max(this.options.minScale, Math.min(this.options.maxScale, factor));
+      this.currentScale = factor;
+      this.isAnimating = true;
+      this._updateUI();
+      const targetAbs = this.baseImageScale * factor;
+      const topLeft = this._getObjectTopLeftPoint(this.originalImage);
+      this._setObjectOriginKeepingPosition(this.originalImage, "left", "top", topLeft);
+      const p1 = new Promise((res) => {
+        this.originalImage.animate("scaleX", targetAbs, {
+          duration: this.options.animationDuration,
+          onChange: this.canvas.renderAll.bind(this.canvas),
+          onComplete: res
+        });
+      });
+      const p2 = new Promise((res) => {
+        this.originalImage.animate("scaleY", targetAbs, {
+          duration: this.options.animationDuration,
+          onChange: this.canvas.renderAll.bind(this.canvas),
+          onComplete: res
+        });
+      });
+      return Promise.all([p1, p2]).then(() => {
+        this.originalImage.set({ scaleX: targetAbs, scaleY: targetAbs });
+        this.originalImage.setCoords();
+        if (this.options.expandCanvasToImage)
+          this._updateCanvasSizeToImageBounds();
+        this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
+        this.canvas.getObjects().forEach((o) => {
+          if (o.maskId)
+            this._syncMaskLabel(o);
+        });
+        this.isAnimating = false;
+        this._updateInputs();
+        this._updateUI();
+        this.saveState();
+      }).catch(() => {
+        this.isAnimating = false;
+        this._updateUI();
+      });
+    }
+    /** 
+     * Rotates the original image by a given number of degrees, with animation.
+     * Returns a promise that resolves when the rotation animation is complete.
+     * @param {number} degrees - The angle in degrees to rotate the image.
+     * @returns {Promise<void>} Promise that resolves once the rotation animation finishes.
+     * @public
+     */
+    rotateImage(deg) {
+      return this.animQueue.add(() => this._rotateImageImpl(deg));
+    }
+    /** 
+     * Rotates the original image by a given number of degrees, with animation.
+     * Returns a promise that resolves when the rotation animation is complete.
+     * @param {number} degrees - The angle in degrees to rotate the image.
+     * @returns {Promise<void>} Promise that resolves once the rotation animation finishes.
+     * @private
+     */
+    _rotateImageImpl(degrees) {
+      if (!this.originalImage)
+        return Promise.resolve();
+      if (this.isAnimating)
+        return Promise.resolve();
+      if (isNaN(degrees))
+        return Promise.resolve();
+      this.currentRotation = degrees;
+      this.isAnimating = true;
+      this._updateUI();
+      const center = this.originalImage.getCenterPoint();
+      this._setObjectOriginKeepingPosition(this.originalImage, "center", "center", center);
+      const p = new Promise((res) => {
+        this.originalImage.animate("angle", degrees, {
+          duration: this.options.animationDuration,
+          onChange: this.canvas.renderAll.bind(this.canvas),
+          onComplete: res
+        });
+      });
+      return p.then(() => {
+        this.originalImage.set("angle", degrees);
+        this.originalImage.setCoords();
+        if (this.options.expandCanvasToImage)
+          this._updateCanvasSizeToImageBounds();
+        this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
+        const newTopLeft = this._getObjectTopLeftPoint(this.originalImage);
+        this._setObjectOriginKeepingPosition(this.originalImage, "left", "top", newTopLeft);
+        this.canvas.getObjects().forEach((o) => {
+          if (o.maskId)
+            this._syncMaskLabel(o);
+        });
+        this.isAnimating = false;
+        this._updateInputs();
+        this._updateUI();
+        this.saveState();
+      }).catch(() => {
+        this.isAnimating = false;
+        this._updateUI();
+      });
+    }
+    /**
+     * Resets the image: scales to 1 and rotates to 0 degrees.
+     * @returns {Promise<void>} Promise that resolves when reset is complete.
+     */
+    reset() {
+      if (!this.originalImage)
+        return Promise.resolve();
+      return this.scaleImage(1).then(() => this.rotateImage(0)).then(() => {
+        this.saveState();
+      }).catch((err) => {
+        this._reportError("reset() failed", err);
+      });
+    }
+    /**
+     * Restores a canvas state that was previously stored by saveState().
+     * @param {string} jsonString - the JSON string returned by fabric.toJSON().
+     */
+    loadFromState(jsonString) {
+      if (!jsonString || !this.canvas)
+        return;
+      try {
+        const json = typeof jsonString === "string" ? JSON.parse(jsonString) : jsonString;
+        this.canvas.loadFromJSON(json, () => {
+          try {
+            this._hideAllMaskLabels();
+            const objs = this.canvas.getObjects();
+            this.originalImage = objs.find((o) => o.type === "image" && !o.maskId) || null;
+            if (this.originalImage) {
+              this.originalImage.set({ originX: "left", originY: "top", selectable: false, evented: false, hasControls: false, hoverCursor: "default" });
+              this.canvas.sendToBack(this.originalImage);
+            }
+            const masks = objs.filter((o) => o.maskId);
+            this.maskCounter = masks.reduce((max, m) => Math.max(max, m.maskId), 0);
+            this._lastMask = masks.length ? masks[masks.length - 1] : null;
+            if (!this._lastMask) {
+              this._lastMaskInitialLeft = null;
+              this._lastMaskInitialTop = null;
+              this._lastMaskInitialWidth = null;
+            }
+            this.isImageLoadedToCanvas = !!this.originalImage;
+            this.canvas.renderAll();
+            this._updateMaskList();
+            this._updatePlaceholderStatus();
+            this._updateUI();
+          } catch (callbackError) {
+            this._reportError("loadFromState() failed", callbackError);
+          }
+        });
+      } catch (e) {
+        this._reportError("loadFromState() failed", e);
+      }
+    }
+    /**
+     * Saves the current state of the canvas to history, storing any mask/raster label information.
+     */
+    saveState() {
+      if (!this.canvas)
+        return;
+      const activeObj = this.canvas.getActiveObject();
+      this._hideAllMaskLabels();
+      try {
+        const jsonObj = this.canvas.toJSON(["maskId", "maskName", "isCropRect"]);
+        if (Array.isArray(jsonObj.objects)) {
+          jsonObj.objects = jsonObj.objects.filter((o) => !o.isCropRect);
+        }
+        const after = JSON.stringify(jsonObj);
+        const before = this._lastSnapshot || after;
+        let executedOnce = false;
+        const cmd = new Command(
+          () => {
+            if (executedOnce) {
+              this.loadFromState(after);
+            }
+            executedOnce = true;
+          },
+          () => {
+            this.loadFromState(before);
+          }
+        );
+        this.historyManager.execute(cmd);
+        this._lastSnapshot = after;
+        if (activeObj && activeObj.maskId) {
+          this._showLabelForMask(activeObj);
+        }
+        this._updateUI();
+      } catch (err) {
+        this._reportWarning("saveState: failed to save canvas snapshot", err);
+      }
+    }
+    /**
+     * Undo the last state change, if possible.
+     */
+    undo() {
+      this.historyManager.undo();
+    }
+    /**
+     * Redo the next state change, if possible.
+     */
+    redo() {
+      this.historyManager.redo();
+    }
+    /** 
+     * Adds a rectangular mask to the canvas.
+     * Mask placement and properties are determined by the provided config and instance options.
+     * Canvas and list UI are updated accordingly.
+     * @param {Object} [config={}] - Optional mask configuration overrides:
+     *   @param {string} [config.shape='rect'] - 'rect', 'circle', 'ellipse', 'polygon', ...
+     *   @param {Object|Array} [config.points] - Required for polygon: [{x, y}, ...] or [[x, y], ...]
+     *   @param {number|function} [config.width/height/rx/ry/radius] - Can be number or function(canvas, options) 
+     *   @param {number|string|function} [config.left/top] - Absolute, %, or function
+     *   @param {number|string} [config.angle] - Rotation angle (degree)
+     *   @param {string} [config.color] - Fill color in CSS color format (default 'rgba(0,0,0,0.5)')
+     *   @param {number} [config.alpha] - Opacity, from 0 to 1 (default 0.5)
+     *   @param {boolean} [config.selectable=true]
+     *   @param {Object} [config.styles] - Custom styles (stroke, dashArray, etc)
+     *   @param {function} [config.onCreate] - Callback after mask created (receives Fabric object)
+     *   @param {function} [config.fabricGenerator] - (cfg) => new FabricObj
+     * @returns {fabric.Rect|null} The created mask object, or null if canvas is not available.
+     * @public
+     */
+    addMask(config = {}) {
+      if (!this.canvas)
+        return null;
+      const shapeType = config.shape || "rect";
+      const cfg = {
+        shape: shapeType,
+        width: this.options.defaultMaskWidth,
+        height: this.options.defaultMaskHeight,
+        color: "rgba(0,0,0,0.5)",
+        alpha: 0.5,
+        gap: 5,
+        left: void 0,
+        top: void 0,
+        angle: 0,
+        selectable: true,
+        ...config
+      };
+      const firstOffset = 10;
+      let left = firstOffset;
+      let top = firstOffset;
+      const resolveValue = (val, fallback) => {
+        if (typeof val === "function")
+          return val(this.canvas, this.options);
+        if (typeof val === "string" && val.endsWith("%")) {
+          const percent = parseFloat(val) / 100;
+          return Math.floor((this.canvas ? this.canvas.getWidth() : 0) * percent);
+        }
+        return val != null ? val : fallback;
+      };
+      if (cfg.left === void 0 && this._lastMask) {
+        const prev = this._lastMask;
+        let prevRight = prev.left;
+        if (prev.getScaledWidth) {
+          prevRight += prev.getScaledWidth();
+        } else if (prev.width) {
+          prevRight += prev.width * (prev.scaleX ?? 1);
+        }
+        left = Math.round(prevRight + cfg.gap);
+        top = prev.top ?? firstOffset;
+      } else {
+        left = resolveValue(cfg.left, firstOffset);
+        top = resolveValue(cfg.top, firstOffset);
+      }
+      cfg.width = resolveValue(cfg.width, this.options.defaultMaskWidth);
+      cfg.height = resolveValue(cfg.height, this.options.defaultMaskHeight);
+      if (this.options.expandCanvasToImage && shapeType === "rect") {
+        const requiredW = Math.ceil(left + cfg.width + 10);
+        const requiredH = Math.ceil(top + cfg.height + 10);
+        const minW = this.containerEl ? Math.floor(this.containerEl.clientWidth || 0) : 0;
+        const minH = this.containerEl ? Math.floor(this.containerEl.clientHeight || 0) : 0;
+        const newW = Math.max(this.canvas.getWidth(), minW, requiredW);
+        const newH = Math.max(this.canvas.getHeight(), minH, requiredH);
+        this._setCanvasSizeInt(newW, newH);
+      }
+      let mask;
+      if (typeof cfg.fabricGenerator === "function") {
+        mask = cfg.fabricGenerator(cfg, this.canvas, this.options);
+      } else {
+        switch (shapeType) {
+          case "circle":
+            mask = new fabric.Circle({
+              left,
+              top,
+              radius: resolveValue(cfg.radius, Math.min(cfg.width, cfg.height) / 2),
+              fill: cfg.color,
+              opacity: cfg.alpha,
+              angle: cfg.angle,
+              ...cfg.styles
+            });
+            break;
+          case "ellipse":
+            mask = new fabric.Ellipse({
+              left,
+              top,
+              rx: resolveValue(cfg.rx, cfg.width / 2),
+              ry: resolveValue(cfg.ry, cfg.height / 2),
+              fill: cfg.color,
+              opacity: cfg.alpha,
+              angle: cfg.angle,
+              ...cfg.styles
+            });
+            break;
+          case "polygon": {
+            let polyPoints = cfg.points || [];
+            if (Array.isArray(polyPoints) && polyPoints.length && typeof polyPoints[0] === "object") {
+              polyPoints = polyPoints.map((pt) => ({ x: Number(pt.x), y: Number(pt.y) }));
+            }
+            mask = new fabric.Polygon(polyPoints, {
+              left,
+              top,
+              fill: cfg.color,
+              opacity: cfg.alpha,
+              angle: cfg.angle,
+              ...cfg.styles
+            });
+            break;
+          }
+          case "rect":
+          default:
+            mask = new fabric.Rect({
+              left,
+              top,
+              width: resolveValue(cfg.width, this.options.defaultMaskWidth),
+              height: resolveValue(cfg.height, this.options.defaultMaskHeight),
+              fill: cfg.color,
+              opacity: cfg.alpha,
+              angle: cfg.angle,
+              rx: cfg.rx,
+              // Rounded Corners
+              ry: cfg.ry,
+              ...cfg.styles
+            });
+        }
+      }
+      mask.selectable = cfg.selectable !== false;
+      mask.hasControls = "hasControls" in cfg ? cfg.hasControls : true;
+      mask.lockRotation = !this.options.maskRotatable;
+      mask.borderColor = cfg.borderColor || "red";
+      mask.cornerColor = cfg.cornerColor || "black";
+      mask.cornerSize = cfg.cornerSize || 8;
+      mask.transparentCorners = "transparentCorners" in cfg ? cfg.transparentCorners : false;
+      mask.stroke = cfg.styles && cfg.styles.stroke || "#ccc";
+      mask.strokeWidth = cfg.styles && cfg.styles.strokeWidth || 1;
+      mask.strokeUniform = "strokeUniform" in cfg ? cfg.strokeUniform : true;
+      if (cfg.styles && cfg.styles.strokeDashArray)
+        mask.strokeDashArray = cfg.styles.strokeDashArray;
+      mask.originalAlpha = cfg.alpha;
+      const normalStyle = { stroke: mask.stroke, strokeWidth: mask.strokeWidth, opacity: mask.originalAlpha };
+      const hoverStyle = { stroke: "#ff5500", strokeWidth: 2, opacity: Math.min(mask.originalAlpha + 0.2, 1) };
+      mask.on("mouseover", () => {
+        mask.set(hoverStyle);
+        mask.canvas.requestRenderAll();
+      });
+      mask.on("mouseout", () => {
+        mask.set(normalStyle);
+        mask.canvas.requestRenderAll();
+      });
+      this._lastMaskInitialLeft = left;
+      this._lastMaskInitialTop = top;
+      this._lastMaskInitialWidth = resolveValue(cfg.width, this.options.defaultMaskWidth);
+      mask.maskId = ++this.maskCounter;
+      mask.maskName = `${this.options.maskName}${mask.maskId}`;
+      this._lastMask = mask;
+      this.canvas.add(mask);
+      this.canvas.bringToFront(mask);
+      if (cfg.selectable)
+        this.canvas.setActiveObject(mask);
+      this._onSelectionChanged([mask]);
+      this._updateMaskList();
+      this._updateUI();
+      this.canvas.renderAll();
+      this.saveState();
+      if (typeof cfg.onCreate === "function")
+        cfg.onCreate(mask, this.canvas);
+      return mask;
+    }
+    /**
+     * Removes the currently selected mask from the canvas, if any.
+     * The associated label is also removed. UI and mask list are updated.
+     */
+    removeSelectedMask() {
+      const active = this.canvas.getActiveObject();
+      if (!active || !active.maskId)
+        return;
+      this._removeLabelForMask(active);
+      this.canvas.remove(active);
+      if (this._lastMask === active) {
+        const masks = this.canvas.getObjects().filter((o) => o.maskId);
+        this._lastMask = masks.length ? masks[masks.length - 1] : null;
+        if (!this._lastMask) {
+          this._lastMaskInitialLeft = null;
+          this._lastMaskInitialTop = null;
+          this._lastMaskInitialWidth = null;
+        }
+      }
+      this.canvas.discardActiveObject();
+      this._updateMaskList();
+      this._updateUI();
+      this.canvas.renderAll();
+      this.saveState();
+    }
+    /**
+     * Removes all masks from the canvas, including their labels.
+     * UI and internal mask placement memory are reset.
+     */
+    removeAllMasks() {
+      const masks = this.canvas.getObjects().filter((o) => o.maskId);
+      masks.forEach((m) => this._removeLabelForMask(m));
+      masks.forEach((m) => this.canvas.remove(m));
+      this.canvas.discardActiveObject();
+      this._lastMask = null;
+      this._lastMaskInitialLeft = null;
+      this._lastMaskInitialTop = null;
+      this._lastMaskInitialWidth = null;
+      this._updateMaskList();
+      this._updateUI();
+      this.canvas.renderAll();
+      this.saveState();
+    }
+    /**
+     * Removes the label associated with the specified mask object, if it exists.
+     * 
+     * @param {fabric.Object} mask - The mask object whose label should be removed.
+     * @private
+     */
+    _removeLabelForMask(mask) {
+      if (!mask || !this.canvas)
+        return;
+      if (mask.__label) {
+        try {
+          const objs = this.canvas.getObjects();
+          if (objs.includes(mask.__label)) {
+            this.canvas.remove(mask.__label);
+          }
+        } catch (e) {
+        }
+        try {
+          delete mask.__label;
+        } catch (e) {
+        }
+      }
+    }
+    /**
+     * Creates and adds a custom label (fabric.Text or fabric.IText) for the mask.
+     * The label is default bound to the top-left of the mask and managed as a non-interactive overlay.
+     * 
+     * @param {fabric.Object} mask - The mask to create a label for.
+     * @private
+     */
+    _createLabelForMask(mask) {
+      if (!mask || !this.options.maskLabelOnSelect)
+        return;
+      this._removeLabelForMask(mask);
+      let textObj = null;
+      if (this.options.label && typeof this.options.label.create === "function") {
+        textObj = this.options.label.create(mask, fabric);
+      }
+      if (!textObj) {
+        let txt = mask.maskName;
+        let textOptions = {
+          left: 0,
+          top: 0,
+          fontSize: 12,
+          fill: "#fff",
+          backgroundColor: "rgba(0,0,0,0.7)",
+          selectable: false,
+          evented: false,
+          padding: 2,
+          originX: "left",
+          originY: "top"
+        };
+        if (this.options.label) {
+          if (typeof this.options.label.getText === "function") {
+            txt = this.options.label.getText(mask, this.maskCounter);
+          }
+          if (this.options.label.textOptions) {
+            Object.assign(textOptions, this.options.label.textOptions);
+          }
+        }
+        textObj = new fabric.Text(txt, textOptions);
+      }
+      textObj.maskLabel = true;
+      mask.__label = textObj;
+      this.canvas.add(textObj);
+      this.canvas.bringToFront(textObj);
+      this._syncMaskLabel(mask);
+    }
+    /**
+     * Hides (removes) all mask labels from the canvas.
+     * Internal label references on mask objects are also deleted.
+     * @private
+     */
+    _hideAllMaskLabels() {
+      if (!this.canvas)
+        return;
+      const objs = this.canvas.getObjects();
+      const labels = objs.filter((o) => o.maskLabel);
+      labels.forEach((l) => {
+        try {
+          if (objs.includes(l))
+            this.canvas.remove(l);
+        } catch (e) {
+        }
+      });
+      objs.forEach((o) => {
+        if (o.maskId && o.__label) {
+          try {
+            delete o.__label;
+          } catch (e) {
+          }
+        }
+      });
+    }
+    /**
+     * Synchronizes the position, angle, and visibility of the mask's label so that it appears properly above the mask.
+     * 
+     * @param {fabric.Object} mask - The mask whose label should be repositioned.
+     * @private
+     */
+    _syncMaskLabel(mask) {
+      if (!mask)
+        return;
+      if (!this.options.maskLabelOnSelect)
+        return;
+      if (!mask.__label)
+        return;
+      const coords = mask.getCoords ? mask.getCoords() : null;
+      if (!coords || coords.length < 4)
+        return;
+      const tl = coords[0];
+      const center = mask.getCenterPoint();
+      const vx = center.x - tl.x;
+      const vy = center.y - tl.y;
+      const dist = Math.sqrt(vx * vx + vy * vy) || 1;
+      const ux = vx / dist;
+      const uy = vy / dist;
+      const offset = Math.max(0, this.options.maskLabelOffset ?? 3);
+      const px = tl.x + ux * offset;
+      const py = tl.y + uy * offset;
+      mask.__label.set({
+        left: Math.round(px),
+        top: Math.round(py),
+        angle: mask.angle || 0,
+        originX: "left",
+        originY: "top",
+        visible: true
+      });
+      mask.__label.setCoords();
+      this.canvas.renderAll();
+    }
+    /**
+     * Shows the label for the given mask, creating it if necessary and synchronizing its position.
+     * 
+     * @param {fabric.Object} mask - The mask whose label should be shown.
+     * @private
+     */
+    _showLabelForMask(mask) {
+      if (!mask)
+        return;
+      if (!this.options.maskLabelOnSelect)
+        return;
+      if (!mask.__label)
+        this._createLabelForMask(mask);
+      mask.__label.visible = true;
+      this._syncMaskLabel(mask);
+    }
+    /**
+     * Handles changes to the selection of canvas objects (masks),
+     * updates mask stroke and label display, and syncs mask list selection.
+     *
+     * @param {Array<Object>} selected - The currently selected objects (e.g. [mask] or []).
+     * @private
+     */
+    _onSelectionChanged(selected) {
+      const selectedMask = (selected || []).find((o) => o.maskId);
+      const masks = this.canvas.getObjects().filter((o) => o.maskId);
+      masks.forEach((m) => {
+        if (m !== selectedMask) {
+          if (m.__label) {
+            try {
+              this.canvas.remove(m.__label);
+            } catch (e) {
+            }
+            delete m.__label;
+          }
+          m.set({ stroke: "#ccc", strokeWidth: 1 });
+        } else {
+          m.set({ stroke: "#ff0000", strokeWidth: 1 });
+        }
+      });
+      if (selectedMask)
+        this._showLabelForMask(selectedMask);
+      this._updateMaskListSelection(selectedMask);
+      this.canvas.renderAll();
+      this._updateUI();
+    }
+    /**
+     * Updates the mask list in the DOM to reflect the current masks on the canvas.
+     * Each list entry becomes a clickable element for mask selection.
+     * @private
+     */
+    _updateMaskList() {
+      const listEl = document.getElementById(this.elements.maskList);
+      if (!listEl)
+        return;
+      listEl.innerHTML = "";
+      const masks = this.canvas.getObjects().filter((o) => o.maskId);
+      masks.forEach((mask) => {
+        const li = document.createElement("li");
+        li.className = "list-group-item mask-item";
+        li.textContent = mask.maskName;
+        li.onclick = () => {
+          this.canvas.setActiveObject(mask);
+          this._onSelectionChanged([mask]);
+        };
+        listEl.appendChild(li);
+      });
+    }
+    /**
+     * Updates the visual selection (CSS 'active') state for the mask list in the DOM.
+     * 
+     * @param {Object|null} selectedMask - The currently selected mask, or null if none selected.
+     * @private
+     */
+    _updateMaskListSelection(selectedMask) {
+      const listEl = document.getElementById(this.elements.maskList);
+      if (!listEl)
+        return;
+      const items = listEl.querySelectorAll(".mask-item");
+      items.forEach((item) => {
+        const isSelected = !!selectedMask && item.textContent === selectedMask.maskName;
+        item.classList.toggle("active", isSelected);
+      });
+    }
+    /**
+     * Merges current masks into the image: exports a masked/cropped image, removes all masks, and re-imports the merged image.
+     * Will not run if no original image or no masks exist.
+     * @async
+     * @returns {Promise<void>} Resolves when merge and load are complete.
+     */
+    async merge() {
+      if (!this.originalImage)
+        return;
+      const masks = this.canvas.getObjects().filter((o) => o.maskId);
+      if (!masks.length)
+        return;
+      this.canvas.discardActiveObject();
+      this.canvas.renderAll();
+      try {
+        const merged = await this.getImageBase64({ exportImageArea: true, multiplier: this.options.exportMultiplier });
+        this.removeAllMasks();
+        await this.loadImage(merged);
+        this.saveState();
+      } catch (err) {
+        this._reportError("merge error", err);
+        if (this.canvasEl)
+          this.canvasEl.style.visibility = "";
+      }
+    }
+    /**
+     * Triggers a JPEG image download of the current canvas (image plus masks if configured).
+     * The image area and multiplier are controlled by options.
+     * @param {string} [fileName=this.options.defaultDownloadFileName] - Desired download file name.
+     */
+    downloadImage(fileName = this.options.defaultDownloadFileName) {
+      if (!this.originalImage)
+        return;
+      const exportImageArea = this.options.exportImageAreaByDefault;
+      this.getImageBase64({ exportImageArea, multiplier: this.options.exportMultiplier }).then((base64) => {
+        const link = document.createElement("a");
+        link.download = fileName;
+        link.href = base64;
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+      }).catch((err) => this._reportError("download error", err));
+    }
+    /**
+     * Exports the image as a Base64-encoded JPEG.
+     * Can export either the original, or the current view including masks (clipped/cropped).
+     * Will restore masks' state after temporary modifications for export.
+     * @async
+     * @param {Object} [opts={}] - Export options.
+     * @param {boolean} [opts.exportImageArea] - If true, exports only the image bounding area with masks cropped and blended.
+     * @param {number} [opts.multiplier=1] - Scaling multiplier for output (resolution).
+     * @returns {Promise<string>} Promise resolving to a JPEG image data URL.
+     * @throws {Error} If there is no image loaded.
+     */
+    async getImageBase64(opts = {}) {
+      if (!this.originalImage)
+        throw new Error("No image loaded");
+      const exportImageArea = typeof opts.exportImageArea === "boolean" ? opts.exportImageArea : this.options.exportImageAreaByDefault;
+      const multiplier = opts.multiplier || this.options.exportMultiplier || 1;
+      if (!exportImageArea) {
+        const imgEl = this.originalImage.getElement ? this.originalImage.getElement() : this.originalImage._element || null;
+        if (!imgEl)
+          return this.canvas.toDataURL({ format: "jpeg", quality: this.options.downsampleQuality, multiplier });
+        const w = this.originalImage.width;
+        const h = this.originalImage.height;
+        const oc = document.createElement("canvas");
+        oc.width = w;
+        oc.height = h;
+        const ctx = oc.getContext("2d");
+        ctx.drawImage(imgEl, 0, 0, w, h);
+        return oc.toDataURL("image/jpeg", this.options.downsampleQuality);
+      }
+      const masks = this.canvas.getObjects().filter((o) => o.maskId);
+      const masksBackup = masks.map((m) => ({
+        obj: m,
+        opacity: m.opacity,
+        fill: m.fill,
+        strokeWidth: m.strokeWidth,
+        stroke: m.stroke,
+        selectable: m.selectable,
+        lockRotation: m.lockRotation
+      }));
+      let finalBase64;
+      try {
+        masks.forEach((m) => this._removeLabelForMask(m));
+        this.canvas.discardActiveObject();
+        this.canvas.renderAll();
+        masks.forEach((m) => {
+          m.set({ opacity: 1, fill: "#000000", strokeWidth: 0, stroke: null, selectable: false });
+          m.setCoords();
+        });
+        this.canvas.renderAll();
+        this.originalImage.setCoords();
+        const imgBr = this.originalImage.getBoundingRect(true, true);
+        const sx = Math.max(0, Math.round(imgBr.left));
+        const sy = Math.max(0, Math.round(imgBr.top));
+        const sw = Math.max(1, Math.round(imgBr.width));
+        const sh = Math.max(1, Math.round(imgBr.height));
+        finalBase64 = await new Promise((resolve, reject) => {
+          try {
+            const fullDataUrl = this.canvas.toDataURL({
+              format: "jpeg",
+              quality: this.options.downsampleQuality,
+              multiplier
+            });
+            const img = new Image();
+            img.onload = () => {
+              try {
+                const sxM = Math.round(sx * multiplier);
+                const syM = Math.round(sy * multiplier);
+                const swM = Math.round(sw * multiplier);
+                const shM = Math.round(sh * multiplier);
+                const oc = document.createElement("canvas");
+                oc.width = swM;
+                oc.height = shM;
+                const ctx = oc.getContext("2d");
+                ctx.drawImage(img, sxM, syM, swM, shM, 0, 0, swM, shM);
+                const out = oc.toDataURL("image/jpeg", this.options.downsampleQuality);
+                resolve(out);
+              } catch (e) {
+                reject(e);
+              }
+            };
+            img.onerror = reject;
+            img.src = fullDataUrl;
+          } catch (e) {
+            reject(e);
+          }
+        });
+      } finally {
+        masksBackup.forEach((b) => {
+          try {
+            b.obj.set({
+              opacity: b.opacity,
+              fill: b.fill,
+              strokeWidth: b.strokeWidth,
+              stroke: b.stroke,
+              selectable: b.selectable,
+              lockRotation: b.lockRotation
+            });
+            b.obj.setCoords();
+          } catch (e) {
+          }
+        });
+        this.canvas.renderAll();
+      }
+      return finalBase64;
+    }
+    /**
+     * Exports the current canvas (with or without masks) as a File object.
+     * Allows you to choose whether to merge masks and specify file type (jpeg/png/webp).
+     * 
+     * @async
+     * @param {Object} [opts={}] - Export options.
+     * @param {boolean} [opts.mergeMask=true] - If true, export image area with masks merged; if false, export the plain image without masks.
+     * @param {string} [opts.fileType='jpeg'] - Output file type ('jpeg' | 'png' | 'webp'). Defaults to 'jpeg' on invalid input.
+     * @param {number} [opts.quality=0.92] - Image quality for lossy types (0-1, default based on options.downsampleQuality).
+     * @param {number} [opts.multiplier=1] - Output resolution multiplier.
+     * @param {string} [opts.fileName] - Optional file name (only used for download).
+     * @returns {Promise<File>} Resolves with the exported image as a File object.
+     * 
+     * @example
+     *   const file = await this.exportImageFile({ mergeMask: false, fileType: 'png' });
+     */
+    async exportImageFile(opts = {}) {
+      if (!this.originalImage)
+        throw new Error("No image loaded");
+      const {
+        mergeMask = true,
+        fileType = "jpeg",
+        quality = this.options.downsampleQuality ?? 0.92,
+        multiplier = this.options.exportMultiplier ?? 1,
+        fileName = this.options.defaultDownloadFileName ?? "exported_image.jpg"
+      } = opts;
+      const typeMapping = {
+        "jpeg": "jpeg",
+        "jpg": "jpeg",
+        "image/jpeg": "jpeg",
+        "png": "png",
+        "image/png": "png",
+        "webp": "webp",
+        "image/webp": "webp"
+      };
+      const safeFileType = typeMapping[String(fileType).toLowerCase()] || "jpeg";
+      let base64;
+      if (mergeMask) {
+        base64 = await this.getImageBase64({
+          exportImageArea: true,
+          multiplier
+        });
+      } else {
+        base64 = await this.getImageBase64({
+          exportImageArea: false,
+          multiplier
+        });
+      }
+      let imageDataUrl = base64;
+      if (!imageDataUrl.startsWith(`data:image/${safeFileType}`)) {
+        imageDataUrl = await new Promise((resolve, reject) => {
+          const img = new window.Image();
+          img.crossOrigin = "Anonymous";
+          img.onload = () => {
+            try {
+              const oc = document.createElement("canvas");
+              oc.width = img.width;
+              oc.height = img.height;
+              const ctx = oc.getContext("2d");
+              ctx.drawImage(img, 0, 0);
+              const durl = oc.toDataURL(`image/${safeFileType}`, quality);
+              resolve(durl);
+            } catch (e) {
+              reject(e);
+            }
+          };
+          img.onerror = reject;
+          img.src = base64;
+        });
+      }
+      const bstr = atob(imageDataUrl.split(",")[1]);
+      const mime = `image/${safeFileType}`;
+      let n = bstr.length;
+      const u8arr = new Uint8Array(n);
+      while (n--) {
+        u8arr[n] = bstr.charCodeAt(n);
+      }
+      const file = new File([u8arr], fileName, { type: mime });
+      return file;
+    }
+    /**
+     * Enter crop mode: create a resizable/movable selection rect on top of the image.
+     * @public
+     */
+    enterCropMode() {
+      if (!this.canvas || !this.originalImage || this._cropMode)
+        return;
+      if (!this.isImageLoaded())
+        return;
+      this._cropMode = true;
+      this._prevSelectionSetting = this.canvas.selection;
+      this.canvas.selection = false;
+      this.canvas.discardActiveObject();
+      this.originalImage.setCoords();
+      const imgBr = this.originalImage.getBoundingRect(true, true);
+      const padding = this.options.crop && this.options.crop.padding ? this.options.crop.padding : 10;
+      const left = Math.max(0, Math.floor(imgBr.left + padding));
+      const top = Math.max(0, Math.floor(imgBr.top + padding));
+      const width = Math.min(this.options.crop.minWidth || 50, Math.floor(imgBr.width - padding * 2));
+      const height = Math.min(this.options.crop.minHeight || 50, Math.floor(imgBr.height - padding * 2));
+      const cropRect = new fabric.Rect({
+        left,
+        top,
+        width,
+        height,
+        fill: "rgba(0,0,0,0.12)",
+        stroke: "#00aaff",
+        strokeDashArray: [6, 4],
+        strokeWidth: 1,
+        strokeUniform: true,
+        selectable: true,
+        hasRotatingPoint: !!(this.options.crop && this.options.crop.allowRotationOfCropRect),
+        lockRotation: !(this.options.crop && this.options.crop.allowRotationOfCropRect),
+        cornerSize: 8,
+        objectCaching: false,
+        originX: "left",
+        originY: "top"
+      });
+      this.canvas.add(cropRect);
+      cropRect.isCropRect = true;
+      this.canvas.bringToFront(cropRect);
+      this.canvas.setActiveObject(cropRect);
+      this._cropRect = cropRect;
+      this._cropPrevEvented = [];
+      this.canvas.getObjects().forEach((o) => {
+        if (o !== cropRect) {
+          this._cropPrevEvented.push({ obj: o, evented: o.evented, selectable: o.selectable });
+          try {
+            o.evented = false;
+            o.selectable = false;
+          } catch (e) {
+          }
+        }
+      });
+      const onModified = () => {
+        try {
+          cropRect.setCoords();
+          this.canvas.requestRenderAll();
+        } catch (e) {
+        }
+      };
+      cropRect.on("modified", onModified);
+      cropRect.on("moving", onModified);
+      cropRect.on("scaling", onModified);
+      this._cropHandlers.push({ target: cropRect, handlers: [{ evt: "modified", fn: onModified }, { evt: "moving", fn: onModified }, { evt: "scaling", fn: onModified }] });
+      this._updateUI();
+      this.canvas.renderAll();
+    }
+    /**
+     * Cancel crop mode and remove the temporary selection rect.
+     * @public
+     */
+    cancelCrop() {
+      if (!this.canvas || !this._cropMode)
+        return;
+      if (this._cropRect) {
+        try {
+          if (this._cropHandlers && this._cropHandlers.length) {
+            this._cropHandlers.forEach((h) => {
+              h.handlers.forEach((rec) => h.target.off(rec.evt, rec.fn));
+            });
+          }
+        } catch (e) {
+        }
+        try {
+          this.canvas.remove(this._cropRect);
+        } catch (e) {
+        }
+        this._cropRect = null;
+      }
+      if (Array.isArray(this._cropPrevEvented)) {
+        this._cropPrevEvented.forEach((i) => {
+          try {
+            i.obj.evented = i.evented;
+            i.obj.selectable = i.selectable;
+          } catch (e) {
+          }
+        });
+      }
+      this._cropPrevEvented = null;
+      this._cropHandlers = [];
+      this._cropMode = false;
+      this.canvas.selection = !!this._prevSelectionSetting;
+      this._prevSelectionSetting = void 0;
+      this.canvas.discardActiveObject();
+      this._updateUI();
+      this.canvas.renderAll();
+    }
+    /**
+     * Apply the current crop rectangle.
+     * remove all masks and export canvas snapshot and crop via offscreen canvas
+     * @public
+     */
+    async applyCrop() {
+      if (!this.canvas || !this._cropMode || !this._cropRect)
+        return;
+      this._cropRect.setCoords();
+      const rectBounds = this._cropRect.getBoundingRect(true, true);
+      const sx = Math.max(0, Math.round(rectBounds.left));
+      const sy = Math.max(0, Math.round(rectBounds.top));
+      const sw = Math.max(1, Math.round(Math.min(rectBounds.width, this.canvas.getWidth() - sx)));
+      const sh = Math.max(1, Math.round(Math.min(rectBounds.height, this.canvas.getHeight() - sy)));
+      let beforeJson = null;
+      try {
+        const jsonObj = this.canvas.toJSON(["maskId", "maskName", "isCropRect"]);
+        if (Array.isArray(jsonObj.objects)) {
+          jsonObj.objects = jsonObj.objects.filter((o) => !o.isCropRect);
+        }
+        beforeJson = JSON.stringify(jsonObj);
+      } catch (e) {
+        this._reportWarning("applyCrop: could not serialize before state", e);
+        beforeJson = null;
+      }
+      try {
+        const masks = this.canvas.getObjects().filter((o) => o.maskId);
+        if (masks && masks.length) {
+          masks.forEach((m) => {
+            try {
+              this._removeLabelForMask(m);
+              this.canvas.remove(m);
+            } catch (err) {
+              this._reportWarning("applyCrop: failed to remove mask", err);
+            }
+          });
+          this._lastMask = null;
+          this._lastMaskInitialLeft = null;
+          this._lastMaskInitialTop = null;
+          this._lastMaskInitialWidth = null;
+          this.canvas.discardActiveObject();
+          this.canvas.renderAll();
+        }
+      } catch (e) {
+        this._reportWarning("applyCrop: error while removing masks", e);
+      }
+      try {
+        if (this._cropRect) {
+          try {
+            if (this._cropHandlers && this._cropHandlers.length) {
+              this._cropHandlers.forEach((h) => {
+                h.handlers.forEach((rec) => h.target.off(rec.evt, rec.fn));
+              });
+            }
+          } catch (e) {
+          }
+          try {
+            this.canvas.remove(this._cropRect);
+          } catch (e) {
+          }
+          this._cropRect = null;
+        }
+      } catch (e) {
+      }
+      this._cropMode = false;
+      this.canvas.selection = !!this._prevSelectionSetting;
+      this._prevSelectionSetting = void 0;
+      let croppedBase64;
+      try {
+        const fullDataUrl = this.canvas.toDataURL({
+          format: "jpeg",
+          quality: this.options.downsampleQuality || 0.92,
+          multiplier: 1
+        });
+        croppedBase64 = await new Promise((resolve, reject) => {
+          const img = new Image();
+          img.onload = () => {
+            try {
+              const oc = document.createElement("canvas");
+              oc.width = sw;
+              oc.height = sh;
+              const ctx = oc.getContext("2d");
+              ctx.drawImage(img, sx, sy, sw, sh, 0, 0, sw, sh);
+              const out = oc.toDataURL("image/jpeg", this.options.downsampleQuality || 0.92);
+              resolve(out);
+            } catch (err) {
+              reject(err);
+            }
+          };
+          img.onerror = (e) => reject(e);
+          img.src = fullDataUrl;
+        });
+      } catch (e) {
+        this._reportError("applyCrop: failed to create cropped image", e);
+        this._updateUI();
+        return;
+      }
+      try {
+        await this.loadImage(croppedBase64);
+      } catch (e) {
+        this._reportError("applyCrop: loadImage(croppedBase64) failed", e);
+        this._updateUI();
+        return;
+      }
+      let afterJson = null;
+      try {
+        const jsonObj2 = this.canvas.toJSON(["maskId", "maskName", "isCropRect"]);
+        if (Array.isArray(jsonObj2.objects)) {
+          jsonObj2.objects = jsonObj2.objects.filter((o) => !o.isCropRect);
+        }
+        afterJson = JSON.stringify(jsonObj2);
+      } catch (e) {
+        this._reportWarning("applyCrop: failed to serialize after state", e);
+        afterJson = null;
+      }
+      try {
+        const self2 = this;
+        const cmd = new Command(
+          () => {
+            if (afterJson)
+              self2.loadFromState(afterJson);
+          },
+          () => {
+            if (beforeJson)
+              self2.loadFromState(beforeJson);
+          }
+        );
+        if (!this.historyManager)
+          this.historyManager = new HistoryManager(this.maxHistorySize || 50);
+        if (this.historyManager.currentIndex < this.historyManager.history.length - 1) {
+          this.historyManager.history = this.historyManager.history.slice(0, this.historyManager.currentIndex + 1);
+        }
+        this.historyManager.history.push(cmd);
+        if (this.historyManager.history.length > this.historyManager.maxSize) {
+          this.historyManager.history.shift();
+        } else {
+          this.historyManager.currentIndex++;
+        }
+      } catch (e) {
+        this._reportWarning("applyCrop: failed to push history command", e);
+      }
+      this._updateUI();
+      this.canvas.renderAll();
+    }
+    /* ---------- Misc / UI ---------- */
+    /**
+     * Updates the scale input field in the UI to reflect the current scale.
+     * Sets the value (as percentage) if the element is present.
+     * @private
+     */
+    _updateInputs() {
+      const scaleEl = document.getElementById(this.elements.scaleRate);
+      if (scaleEl)
+        scaleEl.value = Math.round(this.currentScale * 100);
+    }
+    /**
+     * Updates the enabled/disabled state of various UI controls (buttons)
+     * based on the current application state (image/mask presence, animation, etc).
+     * @private
+     */
+    _updateUI() {
+      const hasImg = !!this.originalImage;
+      const masks = hasImg ? this.canvas.getObjects().filter((o) => o.maskId) : [];
+      const hasMasks = masks.length > 0;
+      const active = this.canvas.getActiveObject();
+      const hasSelectedMask = active && active.maskId;
+      const isDefault = this.currentScale === 1 && this.currentRotation === 0;
+      const canUndo = this.historyManager?.canUndo();
+      const canRedo = this.historyManager?.canRedo();
+      const inCrop = !!this._cropMode;
+      if (inCrop) {
+        for (const k of Object.keys(this.elements || {})) {
+          const el = document.getElementById(this.elements[k]);
+          if (!el)
+            continue;
+          if (k === "applyCropBtn" || k === "cancelCropBtn") {
+            el.disabled = false;
+          } else {
+            el.disabled = true;
+          }
+        }
+        return;
+      }
+      this._setDisabled("zoomInBtn", !hasImg || this.isAnimating || this.currentScale >= this.options.maxScale);
+      this._setDisabled("zoomOutBtn", !hasImg || this.isAnimating || this.currentScale <= this.options.minScale);
+      this._setDisabled("rotateLeftBtn", !hasImg || this.isAnimating);
+      this._setDisabled("rotateRightBtn", !hasImg || this.isAnimating);
+      this._setDisabled("addMaskBtn", !hasImg || this.isAnimating);
+      this._setDisabled("removeMaskBtn", !hasSelectedMask || this.isAnimating);
+      this._setDisabled("removeAllMasksBtn", !hasMasks || this.isAnimating);
+      this._setDisabled("mergeBtn", !hasImg || !hasMasks || this.isAnimating);
+      this._setDisabled("downloadBtn", !hasImg || this.isAnimating);
+      this._setDisabled("resetBtn", !hasImg || isDefault || this.isAnimating);
+      this._setDisabled("undoBtn", !hasImg || this.isAnimating || !canUndo);
+      this._setDisabled("redoBtn", !hasImg || this.isAnimating || !canRedo);
+      this._setDisabled("cropBtn", !hasImg || this.isAnimating);
+      this._setDisabled("applyCropBtn", true);
+      this._setDisabled("cancelCropBtn", true);
+    }
+    /**
+     * Enables or disables a specific UI element (typically a button) by its key.
+     * 
+     * @param {string} key - Key of the element in this.elements (e.g. 'zoomInBtn').
+     * @param {boolean} disabled - If true, disables the element; otherwise enables.
+     * @private
+     */
+    _setDisabled(key, disabled) {
+      const el = document.getElementById(this.elements[key]);
+      if (el)
+        el.disabled = !!disabled;
+    }
+    /**
+     * Automatically display and hide placeholders and containers based on the current image content
+     * @private
+     */
+    _updatePlaceholderStatus() {
+      if (!this.options.showPlaceholder)
+        return;
+      this._setPlaceholderVisible(!this.originalImage);
+    }
+    /**
+     * Controls the display/hiding of the Placeholder and Canvas container.
+     * @param {boolean} show - true displays the placeholder, false displays the canvas container
+     * @private
+     */
+    _setPlaceholderVisible(show) {
+      if (!this.placeholderEl)
+        return;
+      if (show) {
+        this.placeholderEl.classList.remove("d-none");
+        this.placeholderEl.classList.add("d-flex");
+        this.containerEl.classList.add("d-none");
+      } else {
+        this.placeholderEl.classList.remove("d-flex");
+        this.placeholderEl.classList.add("d-none");
+        this.containerEl.classList.remove("d-none");
+      }
+    }
+    /**
+     * Cleans up and disposes of the canvas and related references.
+     * Call this method to free memory and remove canvas listeners when the editor is no longer needed.
+     * @public
+     */
+    dispose() {
+      try {
+        for (const key in this._boundHandlers || {}) {
+          const handlers = this._boundHandlers[key] || [];
+          const el = document.getElementById(this.elements[key]);
+          if (!el)
+            continue;
+          handlers.forEach((h) => {
+            try {
+              el.removeEventListener(h.event, h.handler);
+            } catch (e) {
+            }
+          });
+        }
+      } catch (e) {
+      }
+      if (this._cropRect) {
+        try {
+          this.canvas.remove(this._cropRect);
+        } catch (e) {
+        }
+        this._cropRect = null;
+      }
+      if (this.canvas) {
+        try {
+          this.canvas.dispose();
+        } catch (e) {
+        }
+        this.canvas = null;
+        this.canvasEl = null;
+        this.isImageLoadedToCanvas = false;
+      }
+      this._boundHandlers = {};
+    }
+  };
+  var AnimationQueue = class {
+    /**
+     * Creates a new AnimationQueue.
+     *
+     * @constructor
+     */
+    constructor() {
+      this.queue = [];
+      this.running = false;
+    }
+    /**
+     * Adds an animation function to the queue.
+     *
+     * @param   {Function} animationFn  A function that returns a Promise or any await-able.
+     * @returns {Promise<*>}            A Promise that resolves/rejects with the animation result.
+     */
+    async add(animationFn) {
+      return new Promise((resolve, reject) => {
+        this.queue.push({ fn: animationFn, resolve, reject });
+        if (!this.running) {
+          this.processQueue();
+        }
+      });
+    }
+    /**
+     * Internal helper that processes the animation queue sequentially until it is empty.
+     *
+     * @private
+     * @returns {Promise<void>}
+     */
+    async processQueue() {
+      if (this.queue.length === 0) {
+        this.running = false;
+        return;
+      }
+      this.running = true;
+      const { fn, resolve, reject } = this.queue.shift();
+      try {
+        const result = await fn();
+        resolve(result);
+      } catch (error) {
+        reject(error);
+      }
+      this.processQueue();
+    }
+  };
+  var Command = class {
+    /**
+     * @param {Function} execute  The function that performs the action.
+     * @param {Function} undo     The function that reverts the action.
+     */
+    constructor(execute, undo) {
+      this.execute = execute;
+      this.undo = undo;
+    }
+  };
+  var HistoryManager = class {
+    /**
+     * @param {number} [maxSize=50]  Maximum number of commands to keep in history.
+     */
+    constructor(maxSize = 50) {
+      this.history = [];
+      this.currentIndex = -1;
+      this.maxSize = maxSize;
+    }
+    /**
+     * Executes a new command and pushes it onto the history stack.
+     * Truncates any "future" history when branching.
+     *
+     * @param {Command} command  The command to execute.
+     * @returns {void}
+     */
+    execute(command) {
+      command.execute();
+      if (this.currentIndex < this.history.length - 1) {
+        this.history = this.history.slice(0, this.currentIndex + 1);
+      }
+      this.history.push(command);
+      if (this.history.length > this.maxSize) {
+        this.history.shift();
+      } else {
+        this.currentIndex++;
+      }
+    }
+    /**
+     * Checks whether an undo operation is possible.
+     *
+     * @returns {boolean}  True if undo can be performed.
+     */
+    canUndo() {
+      return this.currentIndex >= 0;
+    }
+    /**
+     * Checks whether a redo operation is possible.
+     *
+     * @returns {boolean}  True if redo can be performed.
+     */
+    canRedo() {
+      return this.currentIndex < this.history.length - 1;
+    }
+    /**
+     * Undoes the last executed command if possible.
+     *
+     * @returns {void}
+     */
+    undo() {
+      if (this.currentIndex >= 0) {
+        this.history[this.currentIndex].undo();
+        this.currentIndex--;
+      }
+    }
+    /**
+     * Redoes the next command in history if possible.
+     *
+     * @returns {void}
+     */
+    redo() {
+      if (this.currentIndex < this.history.length - 1) {
+        this.currentIndex++;
+        this.history[this.currentIndex].execute();
+      }
+    }
+  };
+  var image_editor_default = ImageEditor;
+
+  // src/browser.js
+  var scope = typeof globalThis !== "undefined" ? globalThis : typeof self !== "undefined" ? self : typeof window !== "undefined" ? window : null;
+  setFabric(scope && scope.fabric);
+  if (scope) {
+    scope.ImageEditor = image_editor_default;
+  }
+})();
+//# sourceMappingURL=image-editor.js.map