@bensitu/image-editor 1.2.1 → 1.3.0

package/dist/image-editor.js

@@ -3,15 +3,10 @@
   /**
    * @file image-editor.js
    * @module image-editor
-   * @version 1.2.1
+   * @version 1.3.0
    * @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() {
@@ -79,6 +74,7 @@
         downsampleMaxWidth: 4e3,
         downsampleMaxHeight: 3e3,
         downsampleQuality: 0.92,
+        imageLoadTimeoutMs: 3e4,
         exportMultiplier: 1,
         exportImageAreaByDefault: true,
         defaultMaskWidth: 50,
@@ -113,9 +109,9 @@
         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.canvasElement = null;
+      this.containerElement = null;
+      this.placeholderElement = null;
       this.originalImage = null;
       this.baseImageScale = 1;
       this.currentScale = 1;
@@ -125,27 +121,69 @@
       this.elements = {};
       this.isImageLoadedToCanvas = false;
       this.maxHistorySize = 50;
-      this._boundHandlers = {};
+      this._handlersByElementKey = {};
       this._lastMask = null;
       this._lastMaskInitialLeft = null;
       this._lastMaskInitialTop = null;
       this._lastMaskInitialWidth = null;
+      this._lastSnapshot = null;
       this._cropMode = false;
       this._cropRect = null;
       this._cropHandlers = [];
+      this._cropPrevEvented = null;
+      this._prevSelectionSetting = void 0;
+      this._containerOriginalOverflow = void 0;
+      this._scrollbarSizeCache = null;
       this.onImageLoaded = typeof options.onImageLoaded === "function" ? options.onImageLoaded : null;
-      this.animQueue = new AnimationQueue();
+      this.animationQueue = new AnimationQueue();
       this.historyManager = new HistoryManager(this.maxHistorySize);
     }
+    /**
+     * Backward-compatible alias for {@link ImageEditor#canvasElement}.
+     *
+     * @deprecated Use canvasElement instead. This alias will be removed in v2.0.0.
+     * @returns {HTMLCanvasElement|null} The canvas element currently owned by the editor.
+     */
+    get canvasEl() {
+      return this.canvasElement;
+    }
+    set canvasEl(value) {
+      this.canvasElement = value;
+    }
+    /**
+     * Backward-compatible alias for {@link ImageEditor#containerElement}.
+     *
+     * @deprecated Use containerElement instead. This alias will be removed in v2.0.0.
+     * @returns {HTMLElement|null} The canvas viewport/container element.
+     */
+    get containerEl() {
+      return this.containerElement;
+    }
+    set containerEl(value) {
+      this.containerElement = value;
+    }
+    /**
+     * Backward-compatible alias for {@link ImageEditor#placeholderElement}.
+     *
+     * @deprecated Use placeholderElement instead. This alias will be removed in v2.0.0.
+     * @returns {HTMLElement|null} The placeholder element shown before an image loads.
+     */
+    get placeholderEl() {
+      return this.placeholderElement;
+    }
+    set placeholderEl(value) {
+      this.placeholderElement = value;
+    }
     /**
      * 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.
+     *   Supported keys include: canvas, canvasContainer, imgPlaceholder, scaleRate, rotationLeftInput,
+     *   rotationRightInput, rotateLeftBtn, rotateRightBtn, addMaskBtn, removeMaskBtn, removeAllMasksBtn,
+     *   mergeBtn, downloadBtn, maskList, zoomInBtn, zoomOutBtn, resetBtn, undoBtn, redoBtn, imageInput,
+     *   uploadArea, cropBtn, applyCropBtn, and cancelCropBtn. Unknown keys are ignored.
      *
      * @returns {void}
      *
@@ -217,225 +255,310 @@
       }
     }
     /**
-     * Canvas setup helpers
+     * Initializes the Fabric canvas, viewport elements, and selection event handlers.
+     *
+     * @returns {void}
      * @private
      */
     _initCanvas() {
-      const canvasEl = document.getElementById(this.elements.canvas);
-      if (!canvasEl)
+      const canvasElement = document.getElementById(this.elements.canvas);
+      if (!canvasElement)
         throw new Error("Canvas is not found: " + this.elements.canvas);
-      this.canvasEl = canvasEl;
+      this.canvasElement = canvasElement;
       if (this.elements.canvasContainer) {
-        const ce = document.getElementById(this.elements.canvasContainer);
-        this.containerEl = ce || canvasEl.parentElement;
+        const containerElement = document.getElementById(this.elements.canvasContainer);
+        this.containerElement = containerElement || canvasElement.parentElement;
       } else {
-        this.containerEl = canvasEl.parentElement;
+        this.containerElement = canvasElement.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.placeholderElement = document.getElementById(this.elements.imgPlaceholder) || null;
+      let initialWidth = this.options.canvasWidth;
+      let initialHeight = this.options.canvasHeight;
+      if (this.containerElement) {
+        const containerWidth = Math.floor(this.containerElement.clientWidth);
+        const containerHeight = Math.floor(this.containerElement.clientHeight);
+        if (containerWidth > 0 && containerHeight > 0) {
+          initialWidth = containerWidth;
+          initialHeight = containerHeight;
         }
       }
-      this.canvas = new fabric.Canvas(canvasEl, {
-        width: initialW,
-        height: initialH,
+      this.canvas = new fabric.Canvas(canvasElement, {
+        width: initialWidth,
+        height: initialHeight,
         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("selection:created", (event) => this._handleSelectionChanged(event.selected));
+      this.canvas.on("selection:updated", (event) => this._handleSelectionChanged(event.selected));
+      this.canvas.on("selection:cleared", () => this._handleSelectionChanged([]));
+      this.canvas.on("object:moving", (event) => {
+        if (event.target && event.target.maskId)
+          this._syncMaskLabel(event.target);
       });
-      this.canvas.on("object:scaling", (e) => {
-        if (e.target && e.target.maskId)
-          this._syncMaskLabel(e.target);
+      this.canvas.on("object:scaling", (event) => {
+        if (event.target && event.target.maskId)
+          this._syncMaskLabel(event.target);
       });
-      this.canvas.on("object:rotating", (e) => {
-        if (e.target && e.target.maskId)
-          this._syncMaskLabel(e.target);
+      this.canvas.on("object:rotating", (event) => {
+        if (event.target && event.target.maskId)
+          this._syncMaskLabel(event.target);
       });
-      this.canvas.on("object:modified", (e) => {
-        if (e.target && e.target.maskId)
-          this._syncMaskLabel(e.target);
+      this.canvas.on("object:modified", (event) => this._handleObjectModified(event.target));
+      this.canvasElement.style.display = "block";
+    }
+    /**
+     * Records a history entry after Fabric finishes modifying one or more masks.
+     *
+     * @param {fabric.Object|fabric.ActiveSelection|null} target - Modified Fabric object or selection.
+     * @returns {void}
+     * @private
+     */
+    _handleObjectModified(target) {
+      const masks = this._getModifiedMasks(target);
+      if (!masks.length)
+        return;
+      masks.forEach((mask) => {
+        if (typeof mask.setCoords === "function")
+          mask.setCoords();
+        this._syncMaskLabel(mask);
       });
-      this.canvasEl.style.display = "block";
+      this._expandCanvasToFitObjects(masks);
+      this.saveState();
+    }
+    /**
+     * Extracts editable mask objects from a Fabric modification target.
+     *
+     * @param {fabric.Object|fabric.ActiveSelection|null} target - Fabric object or active selection.
+     * @returns {Array<fabric.Object>} Modified mask objects.
+     * @private
+     */
+    _getModifiedMasks(target) {
+      if (!target)
+        return [];
+      if (target.maskId)
+        return [target];
+      const objects = typeof target.getObjects === "function" ? target.getObjects() : [];
+      return Array.isArray(objects) ? objects.filter((object) => object && object.maskId) : [];
+    }
+    /**
+     * Updates container overflow behavior for fit and cover image modes.
+     *
+     * @param {Object} [options={}] - Overflow update options.
+     * @param {boolean} [options.preserveScroll=false] - If true, keeps the current scroll offsets.
+     * @returns {void}
+     * @private
+     */
+    _syncContainerOverflow(options = {}) {
+      if (!this.containerElement || !this.containerElement.style)
+        return;
+      if (this._containerOriginalOverflow === void 0) {
+        this._containerOriginalOverflow = this.containerElement.style.overflow || "";
+      }
+      const shouldPreserveScroll = options.preserveScroll === true;
+      if (this.options.coverImageToCanvas) {
+        this.containerElement.style.overflow = "scroll";
+        if (!shouldPreserveScroll) {
+          this.containerElement.scrollLeft = 0;
+          this.containerElement.scrollTop = 0;
+        }
+      } else if (this.options.fitImageToCanvas) {
+        this.containerElement.style.overflow = "auto";
+        if (!shouldPreserveScroll) {
+          this.containerElement.scrollLeft = 0;
+          this.containerElement.scrollTop = 0;
+        }
+      } else {
+        this.containerElement.style.overflow = this._containerOriginalOverflow;
+      }
     }
     /** 
      * 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("uploadArea", "click", () => {
+        const uploadAreaElement = document.getElementById(this.elements.uploadArea);
+        if (this._isElementDisabled(uploadAreaElement))
+          return;
+        document.getElementById(this.elements.imageInput)?.click();
+      });
+      this._bindIfExists("imageInput", "change", (event) => {
+        const file = event.target.files && event.target.files[0];
+        if (file)
+          this._loadImageFile(file);
+      });
       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.resetImageTransform();
       });
-      this._bindIfExists("addMaskBtn", "click", () => this.addMask());
+      this._bindIfExists("addMaskBtn", "click", () => this.createMask());
       this._bindIfExists("removeMaskBtn", "click", () => this.removeSelectedMask());
       this._bindIfExists("removeAllMasksBtn", "click", () => this.removeAllMasks());
-      this._bindIfExists("mergeBtn", "click", () => this.merge());
+      this._bindIfExists("mergeBtn", "click", () => this.mergeMasks());
       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("rotateLeftBtn", "click", () => {
+        const rotationInputElement = document.getElementById(this.elements.rotationLeftInput);
+        let step = this.options.rotationStep;
+        if (rotationInputElement) {
+          const parsedStep = parseFloat(rotationInputElement.value);
+          if (!isNaN(parsedStep))
+            step = parsedStep;
+        }
+        this.rotateImage(this.currentRotation - step);
+      });
+      this._bindIfExists("rotateRightBtn", "click", () => {
+        const rotationInputElement = document.getElementById(this.elements.rotationRightInput);
+        let step = this.options.rotationStep;
+        if (rotationInputElement) {
+          const parsedStep = parseFloat(rotationInputElement.value);
+          if (!isNaN(parsedStep))
+            step = parsedStep;
+        }
+        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.applyCrop().catch((error) => this._reportError("applyCrop failed", error));
       });
       this._bindIfExists("cancelCropBtn", "click", () => this.cancelCrop());
     }
-    /** 
-     * Event binding element check
-     * 
-     * @param {*} event 
-     * @param {*} handler 
-     * @param {*} key 
+    /**
+     * Binds a DOM event listener when the configured element exists and records it for disposal.
+     *
+     * @param {string} key - Key in this.elements for the target DOM element.
+     * @param {string} eventName - DOM event name to listen for.
+     * @param {EventListener} handler - Event listener callback.
      * @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 });
+    _bindIfExists(key, eventName, handler) {
+      const element = document.getElementById(this.elements[key]);
+      if (element) {
+        element.addEventListener(eventName, handler);
+        this._handlersByElementKey = this._handlersByElementKey || {};
+        if (!this._handlersByElementKey[key])
+          this._handlersByElementKey[key] = [];
+        this._handlersByElementKey[key].push({ eventName, handler });
       }
     }
-    /** 
-     * Image loading helpers
-     * 
-     * @param {File} file 
+    /**
+     * Reads an image File as a data URL and loads it into the Fabric canvas.
+     *
+     * @param {File} file - Image file selected by the user.
      * @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.onload = (event) => this.loadImage(event.target.result);
+      reader.onerror = (event) => {
+        this._reportError("Image file could not be read", event);
       };
       reader.readAsDataURL(file);
     }
     /**
-    * Load a base64 encoded image string into fabric.
-    * @async
-    * @param {String} base64 
-    */
-    async loadImage(base64) {
+     * Warns when more than one mutually exclusive image layout mode is enabled.
+     *
+     * @returns {void}
+     * @private
+     */
+    _warnOnImageLayoutOptionConflict() {
+      const activeModes = [
+        ["fitImageToCanvas", this.options.fitImageToCanvas],
+        ["coverImageToCanvas", this.options.coverImageToCanvas],
+        ["expandCanvasToImage", this.options.expandCanvasToImage]
+      ].filter(([, isEnabled]) => !!isEnabled).map(([name]) => name);
+      if (activeModes.length <= 1)
+        return;
+      this._reportWarning(
+        `Only one image layout mode should be enabled. Active modes: ${activeModes.join(", ")}.`
+      );
+    }
+    /**
+     * Loads a base64 data URL into the Fabric canvas as the base image.
+     *
+     * @async
+     * @param {string} imageBase64 - Image data URL beginning with `data:image/`.
+     * @param {LoadImageOptions} [options={}] - Optional load behavior.
+     * @returns {Promise<void>} Resolves after the Fabric image is added to the canvas.
+     * @public
+     */
+    async loadImage(imageBase64, options = {}) {
       if (!this._fabricLoaded)
         return;
       if (!this.canvas)
         return;
-      if (!base64 || typeof base64 !== "string" || !base64.startsWith("data:image/"))
+      if (!imageBase64 || typeof imageBase64 !== "string" || !imageBase64.startsWith("data:image/"))
         return;
+      this._warnOnImageLayoutOptionConflict();
       this._setPlaceholderVisible(false);
-      const imgEl = await this._createImageElement(base64);
-      let loadSrc = base64;
+      this._syncContainerOverflow({ preserveScroll: options.preserveScroll === true });
+      const imageElement = await this._createImageElement(imageBase64);
+      let loadSource = imageBase64;
       if (this.options.downsampleOnLoad) {
-        const needResize = imgEl.naturalWidth > this.options.downsampleMaxWidth || imgEl.naturalHeight > this.options.downsampleMaxHeight;
-        if (needResize) {
+        const shouldResize = imageElement.naturalWidth > this.options.downsampleMaxWidth || imageElement.naturalHeight > this.options.downsampleMaxHeight;
+        if (shouldResize) {
           const ratio = Math.min(
-            this.options.downsampleMaxWidth / imgEl.naturalWidth,
-            this.options.downsampleMaxHeight / imgEl.naturalHeight
+            this.options.downsampleMaxWidth / imageElement.naturalWidth,
+            this.options.downsampleMaxHeight / imageElement.naturalHeight
           );
-          const tw = Math.round(imgEl.naturalWidth * ratio);
-          const th = Math.round(imgEl.naturalHeight * ratio);
-          loadSrc = this._resampleImageToDataURL(imgEl, tw, th, this.options.downsampleQuality);
+          const targetWidth = Math.round(imageElement.naturalWidth * ratio);
+          const targetHeight = Math.round(imageElement.naturalHeight * ratio);
+          loadSource = this._resampleImageToDataURL(imageElement, targetWidth, targetHeight, this.options.downsampleQuality);
         }
       }
       return new Promise((resolve, reject) => {
-        fabric.Image.fromURL(loadSrc, (fimg) => {
+        fabric.Image.fromURL(loadSource, (fabricImage) => {
           try {
-            if (!fimg)
+            if (!fabricImage)
               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;
+            fabricImage.set({ originX: "left", originY: "top", selectable: false, evented: false });
+            const imageWidth = fabricImage.width;
+            const imageHeight = fabricImage.height;
+            const viewport = this._getContainerViewportSize();
+            const minWidth = viewport.width;
+            const minHeight = viewport.height;
             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;
+              const canvasWidth = Math.max(1, minWidth - 1);
+              const canvasHeight = Math.max(1, minHeight - 1);
+              this._setCanvasSizeInt(canvasWidth, canvasHeight);
+              const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
+              fabricImage.set({ left: 0, top: 0 });
+              fabricImage.scale(fitScale);
+              this.baseImageScale = fabricImage.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;
+              const layout = this._calculateCoverCanvasLayout(imageWidth, imageHeight);
+              this._setCanvasSizeInt(layout.canvasWidth, layout.canvasHeight);
+              fabricImage.set({ left: 0, top: 0 });
+              fabricImage.scale(layout.scale);
+              this.baseImageScale = fabricImage.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);
+              const canvasWidth = Math.max(minWidth, Math.floor(imageWidth));
+              const canvasHeight = Math.max(minHeight, Math.floor(imageHeight));
+              this._setCanvasSizeInt(canvasWidth, canvasHeight);
+              fabricImage.set({ left: 0, top: 0 });
+              fabricImage.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;
+              const canvasWidth = Math.max(this.options.canvasWidth, minWidth);
+              const canvasHeight = Math.max(this.options.canvasHeight, minHeight);
+              this._setCanvasSizeInt(canvasWidth, canvasHeight);
+              const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
+              fabricImage.set({ left: 0, top: 0 });
+              fabricImage.scale(fitScale);
+              this.baseImageScale = fabricImage.scaleX || 1;
             }
-            this.originalImage = fimg;
-            this.canvas.add(fimg);
-            this.canvas.sendToBack(fimg);
+            this.originalImage = fabricImage;
+            this.canvas.add(fabricImage);
+            this.canvas.sendToBack(fabricImage);
             this._lastMask = null;
             this._lastMaskInitialLeft = null;
             this._lastMaskInitialTop = null;
@@ -448,12 +571,17 @@
             this.isImageLoadedToCanvas = true;
             this._updateUI();
             this.canvas.renderAll();
+            try {
+              this._lastSnapshot = this._serializeCanvasState();
+            } catch (error) {
+              this._reportWarning("loadImage: failed to capture initial canvas snapshot", error);
+            }
             if (typeof this.onImageLoaded === "function") {
               this.onImageLoaded();
             }
             resolve();
-          } catch (err) {
-            reject(err);
+          } catch (error) {
+            reject(error);
           }
         }, { crossOrigin: "anonymous" });
       });
@@ -469,114 +597,530 @@
     /**
      * Creates an HTMLImageElement from a given data URL.
      * 
-     * @param {string} dataURL - A data URL representing the image (e.g., "data:image/png;base64,...").
+     * @param {string} dataUrl - A data URL representing the image (e.g., "data:image/png;base64,...").
+     * @param {number} [timeoutMs=this.options.imageLoadTimeoutMs] - Maximum decode time before rejecting.
      * @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);
+    _createImageElement(dataUrl, timeoutMs = this.options.imageLoadTimeoutMs) {
+      return new Promise((resolve, reject) => {
+        const imageElement = new Image();
+        let isSettled = false;
+        const safeTimeoutMs = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0 ? Number(timeoutMs) : 3e4;
+        let timerId;
+        const settle = (callback) => {
+          if (isSettled)
+            return;
+          isSettled = true;
+          clearTimeout(timerId);
+          imageElement.onload = null;
+          imageElement.onerror = null;
+          callback();
         };
-        img.src = dataURL;
+        timerId = setTimeout(() => {
+          settle(() => reject(new Error("Image load timed out")));
+          try {
+            imageElement.src = "";
+          } catch (error) {
+          }
+        }, safeTimeoutMs);
+        imageElement.onload = () => settle(() => resolve(imageElement));
+        imageElement.onerror = (error) => settle(() => reject(error));
+        imageElement.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 {HTMLImageElement} imageElement - The image element to resample.
+     * @param {number} targetWidth - Target width (in pixels) for the resampled image.
+     * @param {number} targetHeight - 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);
+    _resampleImageToDataURL(imageElement, targetWidth, targetHeight, quality = 0.92) {
+      const offscreenCanvas = document.createElement("canvas");
+      offscreenCanvas.width = targetWidth;
+      offscreenCanvas.height = targetHeight;
+      const context = offscreenCanvas.getContext("2d");
+      if (!context)
+        throw new Error("2D canvas context is unavailable");
+      context.drawImage(imageElement, 0, 0, imageElement.naturalWidth, imageElement.naturalHeight, 0, 0, targetWidth, targetHeight);
+      return offscreenCanvas.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).
+     * @param {number} width - Canvas width in pixels.
+     * @param {number} height - 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);
+    _setCanvasSizeInt(width, height) {
+      const integerWidth = Math.max(1, Math.round(Number(width) || 1));
+      const integerHeight = Math.max(1, Math.round(Number(height) || 1));
+      this.canvas.setWidth(integerWidth);
+      this.canvas.setHeight(integerHeight);
       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";
+      if (this.canvasElement) {
+        this.canvasElement.style.width = integerWidth + "px";
+        this.canvasElement.style.height = integerHeight + "px";
+        this.canvasElement.style.maxWidth = "none";
+      }
+    }
+    _ceilCanvasDimension(value) {
+      const numericValue = Number(value) || 0;
+      const roundedValue = Math.round(numericValue);
+      if (Math.abs(numericValue - roundedValue) < 0.01)
+        return roundedValue;
+      return Math.ceil(numericValue);
+    }
+    _getContainerViewportSize() {
+      if (!this.containerElement) {
+        return {
+          width: Math.max(1, Math.floor(this.options.canvasWidth || 1)),
+          height: Math.max(1, Math.floor(this.options.canvasHeight || 1))
+        };
+      }
+      if (this._hasFixedContainerScrollbars()) {
+        return {
+          width: Math.max(1, Math.floor(this.containerElement.clientWidth || this.options.canvasWidth || 1)),
+          height: Math.max(1, Math.floor(this.containerElement.clientHeight || this.options.canvasHeight || 1))
+        };
+      }
+      const width = Math.max(1, Math.floor(this.containerElement.clientWidth || this.options.canvasWidth || 1));
+      const height = Math.max(1, Math.floor(this.containerElement.clientHeight || this.options.canvasHeight || 1));
+      return { width, height };
+    }
+    _hasFixedContainerScrollbars() {
+      if (!this.containerElement)
+        return false;
+      const inlineOverflow = this.containerElement.style.overflow;
+      const inlineOverflowX = this.containerElement.style.overflowX;
+      const inlineOverflowY = this.containerElement.style.overflowY;
+      let computedOverflow = "";
+      let computedOverflowX = "";
+      let computedOverflowY = "";
+      if (typeof window !== "undefined" && typeof window.getComputedStyle === "function") {
+        const style = window.getComputedStyle(this.containerElement);
+        computedOverflow = style.overflow;
+        computedOverflowX = style.overflowX;
+        computedOverflowY = style.overflowY;
+      }
+      return [inlineOverflow, inlineOverflowX, inlineOverflowY, computedOverflow, computedOverflowX, computedOverflowY].some((value) => value === "scroll");
+    }
+    _getScrollbarSize() {
+      if (this._scrollbarSizeCache) {
+        return { ...this._scrollbarSizeCache };
       }
+      if (typeof document === "undefined" || !document.createElement || !document.body) {
+        return { width: 0, height: 0 };
+      }
+      const probe = document.createElement("div");
+      probe.style.position = "absolute";
+      probe.style.visibility = "hidden";
+      probe.style.overflow = "scroll";
+      probe.style.width = "100px";
+      probe.style.height = "100px";
+      probe.style.top = "-9999px";
+      document.body.appendChild(probe);
+      const width = Math.max(0, probe.offsetWidth - probe.clientWidth);
+      const height = Math.max(0, probe.offsetHeight - probe.clientHeight);
+      document.body.removeChild(probe);
+      this._scrollbarSizeCache = { width, height };
+      return { ...this._scrollbarSizeCache };
+    }
+    _getScrollSafetyMargin() {
+      return 2;
+    }
+    _getScrollableCanvasSize(contentWidth, contentHeight, viewport = this._getContainerViewportSize()) {
+      if (this._hasFixedContainerScrollbars()) {
+        const safetyMargin = this._getScrollSafetyMargin();
+        const safeWidth = Math.max(1, viewport.width - safetyMargin);
+        const safeHeight = Math.max(1, viewport.height - safetyMargin);
+        return {
+          width: contentWidth > viewport.width + 0.5 ? this._ceilCanvasDimension(contentWidth) : safeWidth,
+          height: contentHeight > viewport.height + 0.5 ? this._ceilCanvasDimension(contentHeight) : safeHeight,
+          viewportWidth: viewport.width,
+          viewportHeight: viewport.height,
+          hasHorizontal: true,
+          hasVertical: true
+        };
+      }
+      const scrollbar = this._getScrollbarSize();
+      let hasVertical = false;
+      let hasHorizontal = false;
+      let effectiveWidth = viewport.width;
+      let effectiveHeight = viewport.height;
+      for (let i = 0; i < 4; i += 1) {
+        effectiveWidth = Math.max(1, viewport.width - (hasVertical ? scrollbar.width : 0));
+        effectiveHeight = Math.max(1, viewport.height - (hasHorizontal ? scrollbar.height : 0));
+        const nextHasVertical = contentHeight > effectiveHeight + 0.5;
+        const nextHasHorizontal = contentWidth > effectiveWidth + 0.5;
+        if (nextHasVertical === hasVertical && nextHasHorizontal === hasHorizontal)
+          break;
+        hasVertical = nextHasVertical;
+        hasHorizontal = nextHasHorizontal;
+      }
+      effectiveWidth = Math.max(1, viewport.width - (hasVertical ? scrollbar.width : 0));
+      effectiveHeight = Math.max(1, viewport.height - (hasHorizontal ? scrollbar.height : 0));
+      return {
+        width: hasHorizontal ? this._ceilCanvasDimension(contentWidth) : effectiveWidth,
+        height: hasVertical ? this._ceilCanvasDimension(contentHeight) : effectiveHeight,
+        viewportWidth: effectiveWidth,
+        viewportHeight: effectiveHeight,
+        hasHorizontal,
+        hasVertical
+      };
+    }
+    _calculateCoverCanvasLayout(imageWidth, imageHeight) {
+      const viewport = this._getContainerViewportSize();
+      if (this._hasFixedContainerScrollbars()) {
+        const safetyMargin = this._getScrollSafetyMargin();
+        const targetWidth = Math.max(1, viewport.width - safetyMargin);
+        const targetHeight = Math.max(1, viewport.height - safetyMargin);
+        const scale2 = Math.min(1, Math.max(targetWidth / imageWidth, targetHeight / imageHeight));
+        const contentWidth2 = imageWidth * scale2;
+        const contentHeight2 = imageHeight * scale2;
+        const canvasSize2 = this._getScrollableCanvasSize(contentWidth2, contentHeight2, viewport);
+        return {
+          scale: scale2,
+          canvasWidth: canvasSize2.width,
+          canvasHeight: canvasSize2.height
+        };
+      }
+      const scrollbar = this._getScrollbarSize();
+      let hasVertical = false;
+      let hasHorizontal = false;
+      let scale = 1;
+      let contentWidth = imageWidth;
+      let contentHeight = imageHeight;
+      let effectiveWidth = viewport.width;
+      let effectiveHeight = viewport.height;
+      for (let i = 0; i < 4; i += 1) {
+        effectiveWidth = Math.max(1, viewport.width - (hasVertical ? scrollbar.width : 0));
+        effectiveHeight = Math.max(1, viewport.height - (hasHorizontal ? scrollbar.height : 0));
+        scale = Math.min(1, Math.max(effectiveWidth / imageWidth, effectiveHeight / imageHeight));
+        contentWidth = imageWidth * scale;
+        contentHeight = imageHeight * scale;
+        const nextHasVertical = contentHeight > effectiveHeight + 0.5;
+        const nextHasHorizontal = contentWidth > effectiveWidth + 0.5;
+        if (nextHasVertical === hasVertical && nextHasHorizontal === hasHorizontal)
+          break;
+        hasVertical = nextHasVertical;
+        hasHorizontal = nextHasHorizontal;
+      }
+      const canvasSize = this._getScrollableCanvasSize(contentWidth, contentHeight, viewport);
+      return {
+        scale,
+        canvasWidth: canvasSize.width,
+        canvasHeight: canvasSize.height
+      };
+    }
+    _getStateProperties() {
+      return [
+        "maskId",
+        "maskName",
+        "maskLabel",
+        "isCropRect",
+        "originalAlpha",
+        "originalStroke",
+        "originalStrokeWidth",
+        "selectable",
+        "evented",
+        "hasControls",
+        "lockRotation",
+        "borderColor",
+        "cornerColor",
+        "cornerSize",
+        "transparentCorners",
+        "strokeUniform",
+        "strokeDashArray"
+      ];
+    }
+    _getMaskNormalStyle(mask) {
+      const strokeWidth = Number(mask && mask.originalStrokeWidth);
+      const opacity = Number(mask && mask.originalAlpha);
+      const style = {
+        stroke: mask && mask.originalStroke || "#ccc",
+        strokeWidth: Number.isFinite(strokeWidth) ? strokeWidth : 1
+      };
+      if (Number.isFinite(opacity))
+        style.opacity = opacity;
+      return style;
+    }
+    _withNormalizedMaskStyles(callback) {
+      if (!this.canvas)
+        return callback();
+      const masks = this.canvas.getObjects().filter((object) => object.maskId);
+      const maskStyleBackups = masks.map((mask) => ({
+        object: mask,
+        stroke: mask.stroke,
+        strokeWidth: mask.strokeWidth,
+        opacity: mask.opacity
+      }));
+      try {
+        masks.forEach((mask) => {
+          mask.set(this._getMaskNormalStyle(mask));
+        });
+        return callback();
+      } finally {
+        maskStyleBackups.forEach((backup) => {
+          try {
+            backup.object.set({
+              stroke: backup.stroke,
+              strokeWidth: backup.strokeWidth,
+              opacity: backup.opacity
+            });
+          } catch (error) {
+          }
+        });
+      }
+    }
+    _restoreMaskControls(mask) {
+      if (!mask)
+        return;
+      const cornerSize = Number(mask.cornerSize);
+      mask.set({
+        selectable: mask.selectable !== false,
+        evented: mask.evented !== false,
+        hasControls: mask.hasControls !== false,
+        lockRotation: typeof mask.lockRotation === "boolean" ? mask.lockRotation : !this.options.maskRotatable,
+        borderColor: mask.borderColor || "red",
+        cornerColor: mask.cornerColor || "black",
+        cornerSize: Number.isFinite(cornerSize) ? cornerSize : 8,
+        transparentCorners: mask.transparentCorners === true,
+        strokeUniform: mask.strokeUniform !== false
+      });
+      if (typeof mask.setCoords === "function")
+        mask.setCoords();
+    }
+    /**
+     * Captures editor-owned runtime state that Fabric does not include in canvas JSON.
+     *
+     * @returns {{version:number, baseImageScale:number, currentScale:number, currentRotation:number, maskCounter:number}} Serializable editor metadata.
+     * @private
+     */
+    _serializeEditorMetadata() {
+      const baseImageScale = Number(this.baseImageScale);
+      const currentScale = Number(this.currentScale);
+      const currentRotation = Number(this.currentRotation);
+      const maskCounter = Number(this.maskCounter);
+      return {
+        version: 1,
+        baseImageScale: Number.isFinite(baseImageScale) && baseImageScale > 0 ? baseImageScale : 1,
+        currentScale: Number.isFinite(currentScale) && currentScale > 0 ? currentScale : 1,
+        currentRotation: Number.isFinite(currentRotation) ? currentRotation : 0,
+        maskCounter: Number.isFinite(maskCounter) && maskCounter > 0 ? Math.floor(maskCounter) : 0
+      };
+    }
+    _serializeCanvasState() {
+      if (!this.canvas)
+        return null;
+      return this._withNormalizedMaskStyles(() => {
+        const jsonObject = this.canvas.toJSON(this._getStateProperties());
+        if (Array.isArray(jsonObject.objects)) {
+          jsonObject.objects = jsonObject.objects.filter((object) => !object.isCropRect && !object.maskLabel);
+        }
+        jsonObject.imageEditorMetadata = this._serializeEditorMetadata();
+        return JSON.stringify(jsonObject);
+      });
+    }
+    /**
+     * Normalizes a lossy image quality value to Fabric/canvas's 0..1 range.
+     *
+     * @param {number} quality - Requested image quality.
+     * @returns {number} A finite quality value between 0 and 1.
+     * @private
+     */
+    _normalizeQuality(quality) {
+      const numericQuality = Number(quality);
+      if (!Number.isFinite(numericQuality))
+        return this.options.downsampleQuality ?? 0.92;
+      return Math.max(0, Math.min(1, numericQuality));
+    }
+    /**
+     * Normalizes public image format aliases to canvas export format names.
+     *
+     * @param {string} format - Requested image format or MIME type.
+     * @returns {'jpeg'|'png'|'webp'} Canvas-compatible image format.
+     * @private
+     */
+    _normalizeImageFormat(format) {
+      const typeMapping = {
+        "jpeg": "jpeg",
+        "jpg": "jpeg",
+        "image/jpeg": "jpeg",
+        "png": "png",
+        "image/png": "png",
+        "webp": "webp",
+        "image/webp": "webp"
+      };
+      return typeMapping[String(format || "jpeg").toLowerCase()] || "jpeg";
+    }
+    /**
+     * Converts a bounding rectangle into a canvas-safe integer source region.
+     *
+     * @param {{left:number, top:number, width:number, height:number}} bounds - Bounds in canvas coordinates.
+     * @param {Object} [options={}] - Region rounding options.
+     * @param {boolean} [options.includePartialPixels=true] - If false, excludes partially covered trailing pixels.
+     * @returns {{sourceX:number, sourceY:number, sourceWidth:number, sourceHeight:number}} Clamped source region.
+     * @private
+     */
+    _getClampedCanvasRegion(bounds, options = {}) {
+      const canvasWidth = Math.max(1, Math.round(this.canvas.getWidth()));
+      const canvasHeight = Math.max(1, Math.round(this.canvas.getHeight()));
+      const left = Number(bounds.left) || 0;
+      const top = Number(bounds.top) || 0;
+      const width = Math.max(0, Number(bounds.width) || 0);
+      const height = Math.max(0, Number(bounds.height) || 0);
+      const includePartialPixels = options.includePartialPixels !== false;
+      const roundEnd = includePartialPixels ? Math.ceil : Math.floor;
+      const sourceX = Math.min(canvasWidth - 1, Math.max(0, Math.floor(left)));
+      const sourceY = Math.min(canvasHeight - 1, Math.max(0, Math.floor(top)));
+      const endX = Math.min(canvasWidth, Math.max(sourceX + 1, roundEnd(left + width)));
+      const endY = Math.min(canvasHeight, Math.max(sourceY + 1, roundEnd(top + height)));
+      return {
+        sourceX,
+        sourceY,
+        sourceWidth: Math.max(1, endX - sourceX),
+        sourceHeight: Math.max(1, endY - sourceY)
+      };
+    }
+    /**
+     * Crops an image data URL to a source region using an offscreen canvas.
+     *
+     * @param {string} dataUrl - Source image data URL.
+     * @param {number} sourceX - Source region x coordinate.
+     * @param {number} sourceY - Source region y coordinate.
+     * @param {number} sourceWidth - Source region width.
+     * @param {number} sourceHeight - Source region height.
+     * @param {number} multiplier - Export multiplier already applied to the source data URL.
+     * @param {'jpeg'|'png'|'webp'} [format='jpeg'] - Output image format.
+     * @param {number} [quality=0.92] - Output image quality for lossy formats.
+     * @returns {Promise<string>} Resolves with the cropped image data URL.
+     * @private
+     */
+    async _cropDataUrl(dataUrl, sourceX, sourceY, sourceWidth, sourceHeight, multiplier, format = "jpeg", quality = 0.92) {
+      return new Promise((resolve, reject) => {
+        const imageElement = new Image();
+        let isSettled = false;
+        const timeoutMs = Number(this.options.imageLoadTimeoutMs);
+        const safeTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 3e4;
+        let timerId;
+        const settle = (callback) => {
+          if (isSettled)
+            return;
+          isSettled = true;
+          clearTimeout(timerId);
+          imageElement.onload = null;
+          imageElement.onerror = null;
+          callback();
+        };
+        timerId = setTimeout(() => {
+          settle(() => reject(new Error("Image crop load timed out")));
+          try {
+            imageElement.src = "";
+          } catch (error) {
+          }
+        }, safeTimeoutMs);
+        imageElement.onload = () => {
+          try {
+            const safeMultiplier = Math.max(1, Number(multiplier) || 1);
+            const scaledSourceX = Math.round(sourceX * safeMultiplier);
+            const scaledSourceY = Math.round(sourceY * safeMultiplier);
+            const scaledSourceWidth = Math.max(1, Math.round(sourceWidth * safeMultiplier));
+            const scaledSourceHeight = Math.max(1, Math.round(sourceHeight * safeMultiplier));
+            const offscreenCanvas = document.createElement("canvas");
+            offscreenCanvas.width = scaledSourceWidth;
+            offscreenCanvas.height = scaledSourceHeight;
+            const context = offscreenCanvas.getContext("2d");
+            if (!context)
+              throw new Error("2D canvas context is unavailable");
+            context.drawImage(imageElement, scaledSourceX, scaledSourceY, scaledSourceWidth, scaledSourceHeight, 0, 0, scaledSourceWidth, scaledSourceHeight);
+            settle(() => resolve(offscreenCanvas.toDataURL(`image/${format}`, quality)));
+          } catch (error) {
+            settle(() => reject(error));
+          }
+        };
+        imageElement.onerror = (error) => settle(() => reject(error));
+        imageElement.src = dataUrl;
+      });
+    }
+    /**
+     * Exports the whole Fabric canvas, then crops the requested source region from that export.
+     *
+     * @param {Object} region - Canvas source region and export options.
+     * @param {number} region.sourceX - Source region x coordinate.
+     * @param {number} region.sourceY - Source region y coordinate.
+     * @param {number} region.sourceWidth - Source region width.
+     * @param {number} region.sourceHeight - Source region height.
+     * @param {number} [region.multiplier=1] - Export multiplier.
+     * @param {number} [region.quality=0.92] - Output image quality for lossy formats.
+     * @param {'jpeg'|'png'|'webp'} [region.format='jpeg'] - Output image format.
+     * @returns {Promise<string>} Resolves with an image data URL for the cropped region.
+     * @private
+     */
+    async _exportCanvasRegionToDataURL({ sourceX, sourceY, sourceWidth, sourceHeight, multiplier = 1, quality = 0.92, format = "jpeg" }) {
+      const safeMultiplier = Math.max(1, Number(multiplier) || 1);
+      const fullDataUrl = this.canvas.toDataURL({
+        format,
+        quality,
+        multiplier: safeMultiplier
+      });
+      return this._cropDataUrl(fullDataUrl, sourceX, sourceY, sourceWidth, sourceHeight, safeMultiplier, format, quality);
     }
     /** 
      * 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.
+     * @param {Object} fabricObject - 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)
+    _getObjectTopLeftPoint(fabricObject) {
+      if (!fabricObject)
         return { x: 0, y: 0 };
-      obj.setCoords();
-      const coords = typeof obj.getCoords === "function" ? obj.getCoords() : null;
+      fabricObject.setCoords();
+      const coords = typeof fabricObject.getCoords === "function" ? fabricObject.getCoords() : null;
       if (coords && coords.length)
         return coords[0];
-      const br = obj.getBoundingRect(true, true);
-      return { x: br.left, y: br.top };
+      const boundingRect = fabricObject.getBoundingRect(true, true);
+      return { x: boundingRect.left, y: boundingRect.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 {Object} fabricObject - 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)
+    _setObjectOriginKeepingPosition(fabricObject, originX, originY, refPoint) {
+      if (!fabricObject || !refPoint || !fabricObject.setPositionByOrigin)
         return;
-      obj.set({ originX, originY });
-      obj.setPositionByOrigin(refPoint, originX, originY);
-      obj.setCoords();
+      fabricObject.set({ originX, originY });
+      fabricObject.setPositionByOrigin(refPoint, originX, originY);
+      fabricObject.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.
+     * @param {Object} fabricObject - The object to align.
      * @private
      */
-    _alignObjectBoundingBoxToCanvasTopLeft(obj) {
-      if (!obj)
+    _alignObjectBoundingBoxToCanvasTopLeft(fabricObject) {
+      if (!fabricObject)
         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();
+      fabricObject.setCoords();
+      const boundingRect = fabricObject.getBoundingRect(true, true);
+      const deltaX = boundingRect.left;
+      const deltaY = boundingRect.top;
+      fabricObject.set({ left: (fabricObject.left || 0) - deltaX, top: (fabricObject.top || 0) - deltaY });
+      fabricObject.setCoords();
       this.canvas.renderAll();
     }
     /**
@@ -588,16 +1132,63 @@
       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);
+      const imageBounds = this.originalImage.getBoundingRect(true, true);
+      const size = this._getScrollableCanvasSize(imageBounds.width, imageBounds.height);
+      this._setCanvasSizeInt(size.width, size.height);
+    }
+    /**
+     * Whether post-load edits should resize the canvas to keep transformed content visible.
+     *
+     * @returns {boolean} True when canvas bounds should follow edited image or mask bounds.
+     * @private
+     */
+    _shouldResizeCanvasToContentBounds() {
+      return !!(this.options.expandCanvasToImage || this.options.coverImageToCanvas || this.options.fitImageToCanvas);
+    }
+    /**
+     * Expands the canvas once so all provided objects remain visible after an edit.
+     *
+     * @param {Array<fabric.Object>} fabricObjects - Objects whose bounds should fit inside the canvas.
+     * @param {number} [padding=10] - Extra canvas space after the farthest object edge.
+     * @returns {void}
+     * @private
+     */
+    _expandCanvasToFitObjects(fabricObjects, padding = 10) {
+      if (!this.canvas || !Array.isArray(fabricObjects) || !fabricObjects.length || !this._shouldResizeCanvasToContentBounds())
         return;
+      try {
+        let requiredWidth = this.canvas.getWidth();
+        let requiredHeight = this.canvas.getHeight();
+        fabricObjects.forEach((fabricObject) => {
+          if (!fabricObject)
+            return;
+          if (typeof fabricObject.setCoords === "function")
+            fabricObject.setCoords();
+          const boundingRect = fabricObject.getBoundingRect(true, true);
+          requiredWidth = Math.max(requiredWidth, Math.ceil(boundingRect.left + boundingRect.width + padding));
+          requiredHeight = Math.max(requiredHeight, Math.ceil(boundingRect.top + boundingRect.height + padding));
+        });
+        const minWidth = this.containerElement ? Math.floor(this.containerElement.clientWidth || 0) : 0;
+        const minHeight = this.containerElement ? Math.floor(this.containerElement.clientHeight || 0) : 0;
+        const newWidth = Math.max(this.canvas.getWidth(), minWidth, requiredWidth);
+        const newHeight = Math.max(this.canvas.getHeight(), minHeight, requiredHeight);
+        if (newWidth !== this.canvas.getWidth() || newHeight !== this.canvas.getHeight()) {
+          this._setCanvasSizeInt(newWidth, newHeight);
+        }
+      } catch (error) {
+        this._reportWarning("expandCanvasToFitObjects: failed to expand canvas", error);
       }
-      const newW = Math.max(containerW || 0, Math.floor(br.width));
-      const newH = Math.max(containerH || 0, Math.floor(br.height));
-      this._setCanvasSizeInt(newW, newH);
+    }
+    /**
+     * Expands the canvas so one object remains visible after an edit.
+     *
+     * @param {fabric.Object} fabricObject - Object whose bounds should fit inside the canvas.
+     * @param {number} [padding=10] - Extra canvas space after the object edge.
+     * @returns {void}
+     * @private
+     */
+    _expandCanvasToFitObject(fabricObject, padding = 10) {
+      this._expandCanvasToFitObjects([fabricObject], padding);
     }
     /** 
      * Scales the original image by a given factor, with animation.
@@ -606,8 +1197,8 @@
      * @returns {Promise<void>} Promise that resolves once the scaling animation finishes.
      * @public
      */
-    scaleImage(factor) {
-      return this.animQueue.add(() => this._scaleImageImpl(factor));
+    scaleImage(factor, options = {}) {
+      return this.animationQueue.add(() => this._scaleImageImpl(factor, options));
     }
     /** 
      * Scales the original image by a given factor, with animation.
@@ -616,46 +1207,49 @@
      * @returns {Promise<void>} Promise that resolves once the scaling animation finishes.
      * @private
      */
-    _scaleImageImpl(factor) {
+    _scaleImageImpl(factor, options = {}) {
       if (!this.originalImage)
         return Promise.resolve();
       if (this.isAnimating)
         return Promise.resolve();
+      const saveHistory = options.saveHistory !== false;
       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 targetScale = 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, {
+      const scaleXAnimation = new Promise((resolve) => {
+        this.originalImage.animate("scaleX", targetScale, {
           duration: this.options.animationDuration,
           onChange: this.canvas.renderAll.bind(this.canvas),
-          onComplete: res
+          onComplete: resolve
         });
       });
-      const p2 = new Promise((res) => {
-        this.originalImage.animate("scaleY", targetAbs, {
+      const scaleYAnimation = new Promise((resolve) => {
+        this.originalImage.animate("scaleY", targetScale, {
           duration: this.options.animationDuration,
           onChange: this.canvas.renderAll.bind(this.canvas),
-          onComplete: res
+          onComplete: resolve
         });
       });
-      return Promise.all([p1, p2]).then(() => {
-        this.originalImage.set({ scaleX: targetAbs, scaleY: targetAbs });
+      return Promise.all([scaleXAnimation, scaleYAnimation]).then(() => {
+        this.originalImage.set({ scaleX: targetScale, scaleY: targetScale });
         this.originalImage.setCoords();
-        if (this.options.expandCanvasToImage)
+        if (this._shouldResizeCanvasToContentBounds()) {
           this._updateCanvasSizeToImageBounds();
+        }
         this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
-        this.canvas.getObjects().forEach((o) => {
-          if (o.maskId)
-            this._syncMaskLabel(o);
+        this.canvas.getObjects().forEach((object) => {
+          if (object.maskId)
+            this._syncMaskLabel(object);
         });
         this.isAnimating = false;
         this._updateInputs();
         this._updateUI();
-        this.saveState();
+        if (saveHistory)
+          this.saveState();
       }).catch(() => {
         this.isAnimating = false;
         this._updateUI();
@@ -668,8 +1262,8 @@
      * @returns {Promise<void>} Promise that resolves once the rotation animation finishes.
      * @public
      */
-    rotateImage(deg) {
-      return this.animQueue.add(() => this._rotateImageImpl(deg));
+    rotateImage(degrees, options = {}) {
+      return this.animationQueue.add(() => this._rotateImageImpl(degrees, options));
     }
     /** 
      * Rotates the original image by a given number of degrees, with animation.
@@ -678,171 +1272,322 @@
      * @returns {Promise<void>} Promise that resolves once the rotation animation finishes.
      * @private
      */
-    _rotateImageImpl(degrees) {
+    _rotateImageImpl(degrees, options = {}) {
       if (!this.originalImage)
         return Promise.resolve();
       if (this.isAnimating)
         return Promise.resolve();
       if (isNaN(degrees))
         return Promise.resolve();
+      const saveHistory = options.saveHistory !== false;
       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) => {
+      const rotationAnimation = new Promise((resolve) => {
         this.originalImage.animate("angle", degrees, {
           duration: this.options.animationDuration,
           onChange: this.canvas.renderAll.bind(this.canvas),
-          onComplete: res
+          onComplete: resolve
         });
       });
-      return p.then(() => {
+      return rotationAnimation.then(() => {
         this.originalImage.set("angle", degrees);
         this.originalImage.setCoords();
-        if (this.options.expandCanvasToImage)
+        if (this._shouldResizeCanvasToContentBounds()) {
           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.canvas.getObjects().forEach((object) => {
+          if (object.maskId)
+            this._syncMaskLabel(object);
         });
         this.isAnimating = false;
         this._updateInputs();
         this._updateUI();
-        this.saveState();
+        if (saveHistory)
+          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.
+     * Resets the image transform: scales to 1 and rotates to 0 degrees.
+     *
+     * @returns {Promise<void>} Resolves when the reset history transition has been recorded.
+     * @public
      */
-    reset() {
+    resetImageTransform() {
       if (!this.originalImage)
         return Promise.resolve();
-      return this.scaleImage(1).then(() => this.rotateImage(0)).then(() => {
-        this.saveState();
-      }).catch((err) => {
-        this._reportError("reset() failed", err);
+      return this.animationQueue.add(async () => {
+        const before = this._lastSnapshot || this._serializeCanvasState();
+        await this._scaleImageImpl(1, { saveHistory: false });
+        await this._rotateImageImpl(0, { saveHistory: false });
+        const after = this._serializeCanvasState();
+        this._pushStateTransition(before, after);
+      }).catch((error) => {
+        this._reportError("resetImageTransform() failed", error);
       });
     }
     /**
-     * Restores a canvas state that was previously stored by saveState().
-     * @param {string} jsonString - the JSON string returned by fabric.toJSON().
+     * Backward-compatible alias for {@link ImageEditor#resetImageTransform}.
+     *
+     * @deprecated Use resetImageTransform() instead. This alias will be removed in v2.0.0.
+     * @returns {Promise<void>} Resolves when the image transform reset is complete.
      */
-    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;
+    reset() {
+      return this.resetImageTransform();
+    }
+    /**
+     * Restores a serialized canvas state and rebinds editor-specific mask/image metadata.
+     *
+     * @param {string|Object} serializedState - State returned by `_serializeCanvasState()` as a JSON string or object.
+     * @returns {Promise<void>} Resolves after Fabric has loaded the state and UI state has been refreshed.
+     * @public
+     */
+    loadFromState(serializedState) {
+      if (!serializedState || !this.canvas)
+        return Promise.resolve();
+      return new Promise((resolve) => {
+        try {
+          const state = typeof serializedState === "string" ? JSON.parse(serializedState) : serializedState;
+          const editorMetadata = state && state.imageEditorMetadata ? state.imageEditorMetadata : null;
+          this.canvas.loadFromJSON(state, () => {
+            try {
+              this._hideAllMaskLabels();
+              const canvasObjects = this.canvas.getObjects();
+              this.originalImage = canvasObjects.find((object) => object.type === "image" && !object.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 restoredBaseScale = Number(editorMetadata && editorMetadata.baseImageScale);
+                const restoredCurrentScale = Number(editorMetadata && editorMetadata.currentScale);
+                const restoredCurrentRotation = Number(editorMetadata && editorMetadata.currentRotation);
+                if (Number.isFinite(restoredBaseScale) && restoredBaseScale > 0) {
+                  this.baseImageScale = restoredBaseScale;
+                }
+                if (Number.isFinite(restoredCurrentScale) && restoredCurrentScale > 0) {
+                  this.currentScale = restoredCurrentScale;
+                } else {
+                  const baseScale = Number(this.baseImageScale) || 1;
+                  const imageScale = Number(this.originalImage.scaleX) || baseScale;
+                  this.currentScale = imageScale / baseScale;
+                }
+                this.currentRotation = Number.isFinite(restoredCurrentRotation) ? restoredCurrentRotation : Number(this.originalImage.angle) || 0;
+              } else {
+                this.baseImageScale = 1;
+                this.currentScale = 1;
+                this.currentRotation = 0;
+              }
+              const masks = canvasObjects.filter((object) => object.maskId);
+              masks.forEach((mask) => {
+                this._restoreMaskControls(mask);
+                this._rebindMaskEvents(mask);
+                mask.set(this._getMaskNormalStyle(mask));
+              });
+              const restoredMaskCounter = Number(editorMetadata && editorMetadata.maskCounter);
+              const maxMaskId = masks.reduce((max, mask) => Math.max(max, mask.maskId), 0);
+              this.maskCounter = Number.isFinite(restoredMaskCounter) && restoredMaskCounter >= maxMaskId ? Math.floor(restoredMaskCounter) : maxMaskId;
+              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._updateInputs();
+              this._updateMaskList();
+              this._updatePlaceholderStatus();
+              this._lastSnapshot = this._serializeCanvasState();
+              this._updateUI();
+            } catch (callbackError) {
+              this._reportError("loadFromState() failed", callbackError);
+            } finally {
+              resolve();
             }
-            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);
-      }
+          });
+        } catch (error) {
+          this._reportError("loadFromState() failed", error);
+          resolve();
+        }
+      });
     }
     /**
-     * Saves the current state of the canvas to history, storing any mask/raster label information.
+     * Saves the current editable canvas state as an undoable history transition.
+     *
+     * Labels are hidden before serialization because labels are UI overlays, while mask metadata is kept on
+     * mask objects and restored by `loadFromState()`.
+     *
+     * @returns {void}
+     * @public
      */
     saveState() {
       if (!this.canvas)
         return;
-      const activeObj = this.canvas.getActiveObject();
-      this._hideAllMaskLabels();
+      const activeObject = this.canvas.getActiveObject();
       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 after = this._serializeCanvasState();
         const before = this._lastSnapshot || after;
+        if (after === before)
+          return;
         let executedOnce = false;
-        const cmd = new Command(
+        const command = new Command(
           () => {
             if (executedOnce) {
-              this.loadFromState(after);
+              return this.loadFromState(after);
             }
             executedOnce = true;
+            return void 0;
           },
-          () => {
-            this.loadFromState(before);
-          }
+          () => this.loadFromState(before)
         );
-        this.historyManager.execute(cmd);
+        this.historyManager.execute(command);
         this._lastSnapshot = after;
-        if (activeObj && activeObj.maskId) {
-          this._showLabelForMask(activeObj);
+      } catch (error) {
+        this._reportWarning("saveState: failed to save canvas snapshot", error);
+      } finally {
+        if (activeObject && activeObject.maskId && !activeObject.__label && this.canvas.getObjects().includes(activeObject)) {
+          this._handleSelectionChanged([activeObject]);
         }
         this._updateUI();
-      } catch (err) {
-        this._reportWarning("saveState: failed to save canvas snapshot", err);
       }
     }
+    /**
+     * Pushes a precomputed before/after state transition into history.
+     *
+     * Use this for operations such as crop and merge that build their snapshots around asynchronous image
+     * loading, where the "after" state is already applied before the history command is recorded.
+     *
+     * @param {string} before - Serialized state before the operation.
+     * @param {string} after - Serialized state after the operation.
+     * @returns {void}
+     * @private
+     */
+    _pushStateTransition(before, after) {
+      if (!before || !after)
+        return;
+      if (before === after)
+        return;
+      if (!this.historyManager)
+        this.historyManager = new HistoryManager(this.maxHistorySize || 50);
+      const command = new Command(
+        () => this.loadFromState(after),
+        () => this.loadFromState(before)
+      );
+      this.historyManager.push(command);
+      this._lastSnapshot = after;
+      this._updateUI();
+    }
     /**
      * Undo the last state change, if possible.
+     *
+     * @returns {Promise<void>} Resolves after the history manager finishes the queued undo.
+     * @public
      */
     undo() {
-      this.historyManager.undo();
+      return this.historyManager.undo().then(() => {
+        this._updateUI();
+      }).catch((error) => {
+        this._reportError("undo failed", error);
+      });
     }
     /**
      * Redo the next state change, if possible.
+     *
+     * @returns {Promise<void>} Resolves after the history manager finishes the queued redo.
+     * @public
      */
     redo() {
-      this.historyManager.redo();
+      return this.historyManager.redo().then(() => {
+        this._updateUI();
+      }).catch((error) => {
+        this._reportError("redo failed", error);
+      });
     }
-    /** 
-     * 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.
+    _rebindMaskEvents(mask) {
+      if (!mask)
+        return;
+      if (mask.__imageEditorMaskHandlers) {
+        try {
+          mask.off("mouseover", mask.__imageEditorMaskHandlers.mouseover);
+          mask.off("mouseout", mask.__imageEditorMaskHandlers.mouseout);
+        } catch (error) {
+        }
+      }
+      const metadata = {};
+      if (!Number.isFinite(Number(mask.originalAlpha))) {
+        metadata.originalAlpha = Number.isFinite(Number(mask.opacity)) ? Number(mask.opacity) : 0.5;
+      }
+      if (!mask.originalStroke)
+        metadata.originalStroke = mask.stroke || "#ccc";
+      if (!Number.isFinite(Number(mask.originalStrokeWidth))) {
+        metadata.originalStrokeWidth = Number.isFinite(Number(mask.strokeWidth)) ? Number(mask.strokeWidth) : 1;
+      }
+      if (Object.keys(metadata).length)
+        mask.set(metadata);
+      const normalStyle = {
+        stroke: mask.originalStroke || "#ccc",
+        strokeWidth: mask.originalStrokeWidth,
+        opacity: mask.originalAlpha
+      };
+      const hoverStyle = {
+        stroke: "#ff5500",
+        strokeWidth: 2,
+        opacity: Math.min(mask.originalAlpha + 0.2, 1)
+      };
+      const mouseover = () => {
+        mask.set(hoverStyle);
+        if (mask.canvas)
+          mask.canvas.requestRenderAll();
+      };
+      const mouseout = () => {
+        mask.set(normalStyle);
+        if (mask.canvas)
+          mask.canvas.requestRenderAll();
+      };
+      mask.on("mouseover", mouseover);
+      mask.on("mouseout", mouseout);
+      mask.__imageEditorMaskHandlers = { mouseover, mouseout };
+    }
+    /**
+     * Creates a mask and adds it to the canvas.
+     *
+     * Placement is based on explicit `left`/`top` values when provided; otherwise each new mask is placed
+     * after the previously created mask. Fabric object properties are applied through `set()` and `setCoords()`
+     * so controls and hit testing stay in sync with Fabric 5.x behavior.
+     *
+     * @param {Object} [config={}] - Optional mask configuration overrides.
+     * @param {string} [config.shape='rect'] - Mask shape: `rect`, `circle`, `ellipse`, `polygon`, or a custom shape handled by `fabricGenerator`.
+     * @param {Array<{x:number,y:number}>|Array<Array<number>>} [config.points] - Polygon points.
+     * @param {number|string|MaskValueResolver} [config.width] - Width in pixels, percentage string, or resolver callback.
+     * @param {number|string|MaskValueResolver} [config.height] - Height in pixels, percentage string, or resolver callback.
+     * @param {number|string|MaskValueResolver} [config.radius] - Circle radius in pixels, percentage string, or resolver callback.
+     * @param {number|string|MaskValueResolver} [config.rx] - Ellipse horizontal radius or rectangle corner radius.
+     * @param {number|string|MaskValueResolver} [config.ry] - Ellipse vertical radius or rectangle corner radius.
+     * @param {number|string|MaskValueResolver} [config.left] - Left position in pixels, percentage string, or resolver callback.
+     * @param {number|string|MaskValueResolver} [config.top] - Top position in pixels, percentage string, or resolver callback.
+     * @param {number} [config.angle=0] - Rotation angle in degrees.
+     * @param {string} [config.color='rgba(0,0,0,0.5)'] - Fill color.
+     * @param {number} [config.alpha=0.5] - Opacity from 0 to 1.
+     * @param {boolean} [config.selectable=true] - Whether the mask can be selected.
+     * @param {boolean} [config.hasControls=true] - Whether Fabric transform controls are shown.
+     * @param {Object} [config.styles] - Additional Fabric style properties, such as `stroke` or `strokeDashArray`.
+     * @param {MaskFabricGenerator} [config.fabricGenerator] - Factory callback that returns a custom Fabric object.
+     * @param {MaskCreateCallback} [config.onCreate] - Callback invoked after the mask is added to the canvas.
+     * @returns {fabric.Object|null} The created mask object, or null if the canvas is not initialized.
      * @public
      */
-    addMask(config = {}) {
+    createMask(config = {}) {
       if (!this.canvas)
         return null;
       const shapeType = config.shape || "rect";
-      const cfg = {
+      const maskConfig = {
         shape: shapeType,
         width: this.options.defaultMaskWidth,
         height: this.options.defaultMaskHeight,
@@ -858,80 +1603,73 @@
       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;
+      const resolveValue = (value, fallback) => {
+        if (typeof value === "function")
+          return value(this.canvas, this.options);
+        if (typeof value === "string" && value.endsWith("%")) {
+          const percent = parseFloat(value) / 100;
           return Math.floor((this.canvas ? this.canvas.getWidth() : 0) * percent);
         }
-        return val != null ? val : fallback;
+        return value != null ? value : 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);
+      if (maskConfig.left === void 0 && this._lastMask) {
+        const previousMask = this._lastMask;
+        let previousMaskRight = previousMask.left;
+        if (previousMask.getScaledWidth) {
+          previousMaskRight += previousMask.getScaledWidth();
+        } else if (previousMask.width) {
+          previousMaskRight += previousMask.width * (previousMask.scaleX ?? 1);
         }
-        left = Math.round(prevRight + cfg.gap);
-        top = prev.top ?? firstOffset;
+        left = Math.round(previousMaskRight + maskConfig.gap);
+        top = previousMask.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);
+        left = resolveValue(maskConfig.left, firstOffset);
+        top = resolveValue(maskConfig.top, firstOffset);
       }
+      maskConfig.width = resolveValue(maskConfig.width, this.options.defaultMaskWidth);
+      maskConfig.height = resolveValue(maskConfig.height, this.options.defaultMaskHeight);
+      maskConfig.left = left;
+      maskConfig.top = top;
       let mask;
-      if (typeof cfg.fabricGenerator === "function") {
-        mask = cfg.fabricGenerator(cfg, this.canvas, this.options);
+      if (typeof maskConfig.fabricGenerator === "function") {
+        mask = maskConfig.fabricGenerator(maskConfig, 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
+              radius: resolveValue(maskConfig.radius, Math.min(maskConfig.width, maskConfig.height) / 2),
+              fill: maskConfig.color,
+              opacity: maskConfig.alpha,
+              angle: maskConfig.angle,
+              ...maskConfig.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
+              rx: resolveValue(maskConfig.rx, maskConfig.width / 2),
+              ry: resolveValue(maskConfig.ry, maskConfig.height / 2),
+              fill: maskConfig.color,
+              opacity: maskConfig.alpha,
+              angle: maskConfig.angle,
+              ...maskConfig.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) }));
+            let polygonPoints = maskConfig.points || [];
+            if (Array.isArray(polygonPoints) && polygonPoints.length) {
+              polygonPoints = polygonPoints.map((point) => Array.isArray(point) ? { x: Number(point[0]), y: Number(point[1]) } : { x: Number(point.x), y: Number(point.y) });
             }
-            mask = new fabric.Polygon(polyPoints, {
+            mask = new fabric.Polygon(polygonPoints, {
               left,
               top,
-              fill: cfg.color,
-              opacity: cfg.alpha,
-              angle: cfg.angle,
-              ...cfg.styles
+              fill: maskConfig.color,
+              opacity: maskConfig.alpha,
+              angle: maskConfig.angle,
+              ...maskConfig.styles
             });
             break;
           }
@@ -940,80 +1678,96 @@
             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
+              width: resolveValue(maskConfig.width, this.options.defaultMaskWidth),
+              height: resolveValue(maskConfig.height, this.options.defaultMaskHeight),
+              fill: maskConfig.color,
+              opacity: maskConfig.alpha,
+              angle: maskConfig.angle,
+              rx: maskConfig.rx,
+              ry: maskConfig.ry,
+              ...maskConfig.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();
+      const styles = maskConfig.styles || {};
+      const hasStyle = (property) => Object.prototype.hasOwnProperty.call(styles, property);
+      const maskSettings = {
+        selectable: maskConfig.selectable !== false,
+        hasControls: "hasControls" in maskConfig ? maskConfig.hasControls : true,
+        lockRotation: !this.options.maskRotatable,
+        borderColor: "borderColor" in maskConfig ? maskConfig.borderColor : "red",
+        cornerColor: "cornerColor" in maskConfig ? maskConfig.cornerColor : "black",
+        cornerSize: "cornerSize" in maskConfig ? maskConfig.cornerSize : 8,
+        transparentCorners: "transparentCorners" in maskConfig ? maskConfig.transparentCorners : false,
+        stroke: hasStyle("stroke") ? styles.stroke : "#ccc",
+        strokeWidth: hasStyle("strokeWidth") ? styles.strokeWidth : 1,
+        opacity: hasStyle("opacity") ? styles.opacity : maskConfig.alpha,
+        strokeUniform: "strokeUniform" in maskConfig ? maskConfig.strokeUniform : hasStyle("strokeUniform") ? styles.strokeUniform : true
+      };
+      if (hasStyle("strokeDashArray"))
+        maskSettings.strokeDashArray = styles.strokeDashArray;
+      mask.set(maskSettings);
+      mask.setCoords();
+      mask.set({
+        originalAlpha: Number.isFinite(Number(mask.opacity)) ? Number(mask.opacity) : maskConfig.alpha,
+        originalStroke: mask.stroke || "#ccc",
+        originalStrokeWidth: Number.isFinite(Number(mask.strokeWidth)) ? Number(mask.strokeWidth) : 1
       });
+      this._rebindMaskEvents(mask);
+      this._expandCanvasToFitObject(mask);
       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._lastMaskInitialWidth = resolveValue(maskConfig.width, this.options.defaultMaskWidth);
+      const maskId = ++this.maskCounter;
+      mask.set({
+        maskId,
+        maskName: `${this.options.maskName}${maskId}`
+      });
       this._lastMask = mask;
       this.canvas.add(mask);
       this.canvas.bringToFront(mask);
-      if (cfg.selectable)
+      if (maskConfig.selectable)
         this.canvas.setActiveObject(mask);
-      this._onSelectionChanged([mask]);
+      this._handleSelectionChanged([mask]);
       this._updateMaskList();
       this._updateUI();
       this.canvas.renderAll();
       this.saveState();
-      if (typeof cfg.onCreate === "function")
-        cfg.onCreate(mask, this.canvas);
+      if (typeof maskConfig.onCreate === "function")
+        maskConfig.onCreate(mask, this.canvas);
       return mask;
     }
+    /**
+     * Backward-compatible alias for {@link ImageEditor#createMask}.
+     *
+     * @deprecated Use createMask() instead. This alias will be removed in v2.0.0.
+     * @param {Object} [config={}] - Mask configuration passed to createMask().
+     * @returns {fabric.Object|null} The created mask object, or null if the canvas is not initialized.
+     */
+    addMask(config = {}) {
+      return this.createMask(config);
+    }
     /**
      * 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)
+      const activeObject = this.canvas.getActiveObject();
+      const selectedMasks = this._getModifiedMasks(activeObject);
+      if (!selectedMasks.length)
         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();
+      selectedMasks.forEach((mask) => {
+        this._removeLabelForMask(mask);
+        this.canvas.remove(mask);
+      });
+      const masks = this.canvas.getObjects().filter((object) => object.maskId);
+      this._lastMask = masks.length ? masks[masks.length - 1] : null;
+      if (!this._lastMask) {
+        this._lastMaskInitialLeft = null;
+        this._lastMaskInitialTop = null;
+        this._lastMaskInitialWidth = null;
+      }
       this._updateMaskList();
       this._updateUI();
       this.canvas.renderAll();
@@ -1023,10 +1777,11 @@
      * 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));
+    removeAllMasks(options = {}) {
+      const saveHistory = options.saveHistory !== false;
+      const masks = this.canvas.getObjects().filter((object) => object.maskId);
+      masks.forEach((mask) => this._removeLabelForMask(mask));
+      masks.forEach((mask) => this.canvas.remove(mask));
       this.canvas.discardActiveObject();
       this._lastMask = null;
       this._lastMaskInitialLeft = null;
@@ -1035,7 +1790,8 @@
       this._updateMaskList();
       this._updateUI();
       this.canvas.renderAll();
-      this.saveState();
+      if (saveHistory)
+        this.saveState();
     }
     /**
      * Removes the label associated with the specified mask object, if it exists.
@@ -1048,18 +1804,35 @@
         return;
       if (mask.__label) {
         try {
-          const objs = this.canvas.getObjects();
-          if (objs.includes(mask.__label)) {
+          const canvasObjects = this.canvas.getObjects();
+          if (canvasObjects.includes(mask.__label)) {
             this.canvas.remove(mask.__label);
           }
-        } catch (e) {
+        } catch (error) {
         }
         try {
           delete mask.__label;
-        } catch (e) {
+        } catch (error) {
         }
       }
     }
+    /**
+     * Returns a stable zero-based creation index for label callbacks.
+     *
+     * Mask ids are one-based and are not renumbered after deletion, so this value remains stable for the
+     * lifetime of a mask.
+     *
+     * @param {fabric.Object} mask - Mask object.
+     * @returns {number} Stable zero-based creation index.
+     * @private
+     */
+    _getMaskCreationIndex(mask) {
+      const maskId = Number(mask && mask.maskId);
+      if (Number.isFinite(maskId) && maskId > 0)
+        return Math.floor(maskId) - 1;
+      const masks = this.canvas ? this.canvas.getObjects().filter((object) => object.maskId) : [];
+      return Math.max(0, masks.indexOf(mask));
+    }
     /**
      * 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.
@@ -1071,12 +1844,12 @@
       if (!mask || !this.options.maskLabelOnSelect)
         return;
       this._removeLabelForMask(mask);
-      let textObj = null;
+      let textObject = null;
       if (this.options.label && typeof this.options.label.create === "function") {
-        textObj = this.options.label.create(mask, fabric);
+        textObject = this.options.label.create(mask, fabric);
       }
-      if (!textObj) {
-        let txt = mask.maskName;
+      if (!textObject) {
+        let labelText = mask.maskName;
         let textOptions = {
           left: 0,
           top: 0,
@@ -1091,18 +1864,18 @@
         };
         if (this.options.label) {
           if (typeof this.options.label.getText === "function") {
-            txt = this.options.label.getText(mask, this.maskCounter);
+            labelText = this.options.label.getText(mask, this._getMaskCreationIndex(mask));
           }
           if (this.options.label.textOptions) {
             Object.assign(textOptions, this.options.label.textOptions);
           }
         }
-        textObj = new fabric.Text(txt, textOptions);
+        textObject = new fabric.Text(labelText, textOptions);
       }
-      textObj.maskLabel = true;
-      mask.__label = textObj;
-      this.canvas.add(textObj);
-      this.canvas.bringToFront(textObj);
+      textObject.maskLabel = true;
+      mask.__label = textObject;
+      this.canvas.add(textObject);
+      this.canvas.bringToFront(textObject);
       this._syncMaskLabel(mask);
     }
     /**
@@ -1113,20 +1886,20 @@
     _hideAllMaskLabels() {
       if (!this.canvas)
         return;
-      const objs = this.canvas.getObjects();
-      const labels = objs.filter((o) => o.maskLabel);
-      labels.forEach((l) => {
+      const canvasObjects = this.canvas.getObjects();
+      const labels = canvasObjects.filter((object) => object.maskLabel);
+      labels.forEach((label) => {
         try {
-          if (objs.includes(l))
-            this.canvas.remove(l);
-        } catch (e) {
+          if (canvasObjects.includes(label))
+            this.canvas.remove(label);
+        } catch (error) {
         }
       });
-      objs.forEach((o) => {
-        if (o.maskId && o.__label) {
+      canvasObjects.forEach((object) => {
+        if (object.maskId && object.__label) {
           try {
-            delete o.__label;
-          } catch (e) {
+            delete object.__label;
+          } catch (error) {
           }
         }
       });
@@ -1166,7 +1939,11 @@
         visible: true
       });
       mask.__label.setCoords();
-      this.canvas.renderAll();
+      if (typeof this.canvas.requestRenderAll === "function") {
+        this.canvas.requestRenderAll();
+      } else {
+        this.canvas.renderAll();
+      }
     }
     /**
      * Shows the label for the given mask, creating it if necessary and synchronizing its position.
@@ -1181,7 +1958,7 @@
         return;
       if (!mask.__label)
         this._createLabelForMask(mask);
-      mask.__label.visible = true;
+      mask.__label.set({ visible: true });
       this._syncMaskLabel(mask);
     }
     /**
@@ -1191,21 +1968,25 @@
      * @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) {
+    _handleSelectionChanged(selected) {
+      const selectedMask = (selected || []).find((object) => object.maskId);
+      const masks = this.canvas.getObjects().filter((object) => object.maskId);
+      masks.forEach((mask) => {
+        if (mask !== selectedMask) {
+          if (mask.__label) {
             try {
-              this.canvas.remove(m.__label);
-            } catch (e) {
+              this.canvas.remove(mask.__label);
+            } catch (error) {
             }
-            delete m.__label;
+            delete mask.__label;
           }
-          m.set({ stroke: "#ccc", strokeWidth: 1 });
+          const originalStrokeWidth = Number(mask.originalStrokeWidth);
+          mask.set({
+            stroke: mask.originalStroke || "#ccc",
+            strokeWidth: Number.isFinite(originalStrokeWidth) ? originalStrokeWidth : 1
+          });
         } else {
-          m.set({ stroke: "#ff0000", strokeWidth: 1 });
+          mask.set({ stroke: "#ff0000", strokeWidth: 1 });
         }
       });
       if (selectedMask)
@@ -1220,20 +2001,20 @@
      * @private
      */
     _updateMaskList() {
-      const listEl = document.getElementById(this.elements.maskList);
-      if (!listEl)
+      const maskListElement = document.getElementById(this.elements.maskList);
+      if (!maskListElement)
         return;
-      listEl.innerHTML = "";
-      const masks = this.canvas.getObjects().filter((o) => o.maskId);
+      maskListElement.innerHTML = "";
+      const masks = this.canvas.getObjects().filter((object) => object.maskId);
       masks.forEach((mask) => {
-        const li = document.createElement("li");
-        li.className = "list-group-item mask-item";
-        li.textContent = mask.maskName;
-        li.onclick = () => {
+        const listItemElement = document.createElement("li");
+        listItemElement.className = "list-group-item mask-item";
+        listItemElement.textContent = mask.maskName;
+        listItemElement.onclick = () => {
           this.canvas.setActiveObject(mask);
-          this._onSelectionChanged([mask]);
+          this._handleSelectionChanged([mask]);
         };
-        listEl.appendChild(li);
+        maskListElement.appendChild(listItemElement);
       });
     }
     /**
@@ -1243,157 +2024,167 @@
      * @private
      */
     _updateMaskListSelection(selectedMask) {
-      const listEl = document.getElementById(this.elements.maskList);
-      if (!listEl)
+      const maskListElement = document.getElementById(this.elements.maskList);
+      if (!maskListElement)
         return;
-      const items = listEl.querySelectorAll(".mask-item");
-      items.forEach((item) => {
+      const maskItems = maskListElement.querySelectorAll(".mask-item");
+      maskItems.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.
+     * Flattens the current masks into the base image and reloads the flattened image.
+     *
+     * This removes editable mask objects after export and records the operation as one undoable history transition.
+     * It does nothing when no base image or no masks exist.
+     *
      * @async
-     * @returns {Promise<void>} Resolves when merge and load are complete.
+     * @returns {Promise<void>} Resolves when the flattened image has been loaded.
+     * @public
      */
-    async merge() {
+    async mergeMasks() {
       if (!this.originalImage)
         return;
-      const masks = this.canvas.getObjects().filter((o) => o.maskId);
+      const masks = this.canvas.getObjects().filter((object) => object.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 = "";
+        const beforeJson = this._serializeCanvasState();
+        const merged = await this.exportImageBase64({ exportImageArea: true, multiplier: this.options.exportMultiplier });
+        this.removeAllMasks({ saveHistory: false });
+        await this.loadImage(merged, { preserveScroll: true });
+        const afterJson = this._serializeCanvasState();
+        this._pushStateTransition(beforeJson, afterJson);
+      } catch (error) {
+        this._reportError("merge error", error);
       }
     }
     /**
-     * Triggers a JPEG image download of the current canvas (image plus masks if configured).
+     * Backward-compatible alias for {@link ImageEditor#mergeMasks}.
+     *
+     * @deprecated Use mergeMasks() instead. This alias will be removed in v2.0.0.
+     * @returns {Promise<void>} Resolves when mask flattening is complete.
+     */
+    async merge() {
+      return this.mergeMasks();
+    }
+    /**
+     * Triggers a JPEG image download of the current canvas.
+     *
      * The image area and multiplier are controlled by options.
      * @param {string} [fileName=this.options.defaultDownloadFileName] - Desired download file name.
+     * @returns {void}
+     * @public
      */
     downloadImage(fileName = this.options.defaultDownloadFileName) {
       if (!this.originalImage)
         return;
       const exportImageArea = this.options.exportImageAreaByDefault;
-      this.getImageBase64({ exportImageArea, multiplier: this.options.exportMultiplier }).then((base64) => {
+      this.exportImageBase64({ exportImageArea, multiplier: this.options.exportMultiplier }).then((imageBase64) => {
         const link = document.createElement("a");
         link.download = fileName;
-        link.href = base64;
+        link.href = imageBase64;
         document.body.appendChild(link);
         link.click();
         document.body.removeChild(link);
-      }).catch((err) => this._reportError("download error", err));
+      }).catch((error) => this._reportError("download error", error));
     }
     /**
-     * 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.
+     * Exports the current image as a Base64-encoded data URL.
+     *
+     * When `exportImageArea` is false, the export omits masks and labels. When it is true, masks are
+     * temporarily rendered as opaque export shapes and then restored, so editable mask state is not mutated.
+     *
      * @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.
+     * @param {Object} [options={}] - Export options.
+     * @param {boolean} [options.exportImageArea] - If true, exports only the image bounding area with masks cropped and blended.
+     * @param {number} [options.multiplier=1] - Scaling multiplier for output (resolution).
+     * @param {number} [options.quality=0.92] - Image quality between 0 and 1 for lossy formats.
+     * @param {string} [options.fileType='jpeg'] - Output file type ('jpeg' | 'png' | 'webp').
+     * @returns {Promise<string>} Resolves with an image data URL.
      * @throws {Error} If there is no image loaded.
+     * @public
      */
-    async getImageBase64(opts = {}) {
+    async exportImageBase64(options = {}) {
       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;
+      const exportImageArea = typeof options.exportImageArea === "boolean" ? options.exportImageArea : this.options.exportImageAreaByDefault;
+      const multiplier = options.multiplier || this.options.exportMultiplier || 1;
+      const quality = this._normalizeQuality(options.quality ?? this.options.downsampleQuality);
+      const format = this._normalizeImageFormat(options.fileType || options.format);
       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 masks2 = this.canvas.getObjects().filter((object) => object.maskId || object.maskLabel);
+        const maskVisibilityBackups = masks2.map((mask) => ({ object: mask, visible: mask.visible }));
+        try {
+          masks2.forEach((mask) => {
+            mask.set({ visible: false });
+          });
+          this.canvas.discardActiveObject();
+          this.canvas.renderAll();
+          this.originalImage.setCoords();
+          const imageBounds = this.originalImage.getBoundingRect(true, true);
+          const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+          return await this._exportCanvasRegionToDataURL({
+            ...exportRegion,
+            multiplier,
+            quality,
+            format
+          });
+        } finally {
+          maskVisibilityBackups.forEach((backup) => {
+            try {
+              backup.object.set({ visible: backup.visible });
+            } catch (error) {
+            }
+          });
+          this.canvas.renderAll();
+        }
       }
-      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
+      const masks = this.canvas.getObjects().filter((object) => object.maskId);
+      const maskStyleBackups = masks.map((mask) => ({
+        object: mask,
+        opacity: mask.opacity,
+        fill: mask.fill,
+        strokeWidth: mask.strokeWidth,
+        stroke: mask.stroke,
+        selectable: mask.selectable,
+        lockRotation: mask.lockRotation
       }));
       let finalBase64;
       try {
-        masks.forEach((m) => this._removeLabelForMask(m));
+        masks.forEach((mask) => this._removeLabelForMask(mask));
         this.canvas.discardActiveObject();
         this.canvas.renderAll();
-        masks.forEach((m) => {
-          m.set({ opacity: 1, fill: "#000000", strokeWidth: 0, stroke: null, selectable: false });
-          m.setCoords();
+        masks.forEach((mask) => {
+          mask.set({ opacity: 1, fill: "#000000", strokeWidth: 0, stroke: null, selectable: false });
+          mask.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);
-          }
+        const imageBounds = this.originalImage.getBoundingRect(true, true);
+        const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+        finalBase64 = await this._exportCanvasRegionToDataURL({
+          ...exportRegion,
+          multiplier,
+          quality,
+          format
         });
       } finally {
-        masksBackup.forEach((b) => {
+        maskStyleBackups.forEach((backup) => {
           try {
-            b.obj.set({
-              opacity: b.opacity,
-              fill: b.fill,
-              strokeWidth: b.strokeWidth,
-              stroke: b.stroke,
-              selectable: b.selectable,
-              lockRotation: b.lockRotation
+            backup.object.set({
+              opacity: backup.opacity,
+              fill: backup.fill,
+              strokeWidth: backup.strokeWidth,
+              stroke: backup.stroke,
+              selectable: backup.selectable,
+              lockRotation: backup.lockRotation
             });
-            b.obj.setCoords();
-          } catch (e) {
+            backup.object.setCoords();
+          } catch (error) {
           }
         });
         this.canvas.renderAll();
@@ -1401,22 +2192,34 @@
       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).
+     * Backward-compatible alias for {@link ImageEditor#exportImageBase64}.
+     *
+     * @deprecated Use exportImageBase64() instead. This alias will be removed in v2.0.0.
+     * @param {Object} [options={}] - Export options passed to exportImageBase64().
+     * @returns {Promise<string>} Resolves with an image data URL.
+     */
+    async getImageBase64(options = {}) {
+      return this.exportImageBase64(options);
+    }
+    /**
+     * Exports the current image as a File object.
+     *
+     * The export can include flattened masks (`mergeMask: true`) or only the plain base image (`mergeMask: false`).
+     * Supported output formats are JPEG, PNG, and 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).
+     * @param {Object} [options={}] - Export options.
+     * @param {boolean} [options.mergeMask=true] - If true, export image area with masks merged; if false, export the plain image without masks.
+     * @param {string} [options.fileType='jpeg'] - Output file type ('jpeg' | 'png' | 'webp'). Defaults to 'jpeg' on invalid input.
+     * @param {number} [options.quality=0.92] - Image quality for lossy types (0-1, default based on options.downsampleQuality).
+     * @param {number} [options.multiplier=1] - Output resolution multiplier.
+     * @param {string} [options.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 = {}) {
+    async exportImageFile(options = {}) {
       if (!this.originalImage)
         throw new Error("No image loaded");
       const {
@@ -1425,63 +2228,124 @@
         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;
+      } = options;
+      const safeFileType = this._normalizeImageFormat(fileType);
+      let imageBase64;
       if (mergeMask) {
-        base64 = await this.getImageBase64({
+        imageBase64 = await this.exportImageBase64({
           exportImageArea: true,
-          multiplier
+          multiplier,
+          quality,
+          fileType: safeFileType
         });
       } else {
-        base64 = await this.getImageBase64({
+        imageBase64 = await this.exportImageBase64({
           exportImageArea: false,
-          multiplier
+          multiplier,
+          quality,
+          fileType: safeFileType
         });
       }
-      let imageDataUrl = base64;
+      let imageDataUrl = imageBase64;
       if (!imageDataUrl.startsWith(`data:image/${safeFileType}`)) {
         imageDataUrl = await new Promise((resolve, reject) => {
-          const img = new window.Image();
-          img.crossOrigin = "Anonymous";
-          img.onload = () => {
+          const imageElement = new window.Image();
+          imageElement.crossOrigin = "Anonymous";
+          imageElement.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);
+              const offscreenCanvas = document.createElement("canvas");
+              offscreenCanvas.width = imageElement.width;
+              offscreenCanvas.height = imageElement.height;
+              const context = offscreenCanvas.getContext("2d");
+              context.drawImage(imageElement, 0, 0);
+              const convertedDataUrl = offscreenCanvas.toDataURL(`image/${safeFileType}`, quality);
+              resolve(convertedDataUrl);
+            } catch (error) {
+              reject(error);
             }
           };
-          img.onerror = reject;
-          img.src = base64;
+          imageElement.onerror = reject;
+          imageElement.src = imageBase64;
         });
       }
-      const bstr = atob(imageDataUrl.split(",")[1]);
+      const binaryString = atob(imageDataUrl.split(",")[1]);
       const mime = `image/${safeFileType}`;
-      let n = bstr.length;
-      const u8arr = new Uint8Array(n);
-      while (n--) {
-        u8arr[n] = bstr.charCodeAt(n);
+      let byteIndex = binaryString.length;
+      const bytes = new Uint8Array(byteIndex);
+      while (byteIndex--) {
+        bytes[byteIndex] = binaryString.charCodeAt(byteIndex);
+      }
+      return new File([bytes], fileName, { type: mime });
+    }
+    _clearMaskPlacementMemory() {
+      this._lastMask = null;
+      this._lastMaskInitialLeft = null;
+      this._lastMaskInitialTop = null;
+      this._lastMaskInitialWidth = null;
+    }
+    async _restoreStateAfterCropFailure(beforeJson, message, error) {
+      this._reportError(message, error);
+      if (this._cropRect && this.canvas)
+        this._removeCropRect();
+      this._cropRect = null;
+      this._cropMode = false;
+      if (this.canvas && this._prevSelectionSetting !== void 0) {
+        this.canvas.selection = !!this._prevSelectionSetting;
+      }
+      this._prevSelectionSetting = void 0;
+      if (beforeJson) {
+        try {
+          await this.loadFromState(beforeJson);
+        } catch (restoreError) {
+          this._reportError("applyCrop: rollback failed", restoreError);
+        }
+      }
+      this._updateUI();
+      if (this.canvas)
+        this.canvas.renderAll();
+    }
+    _restoreCropObjectState() {
+      if (Array.isArray(this._cropPrevEvented)) {
+        this._cropPrevEvented.forEach((state) => {
+          try {
+            state.object.set({
+              evented: state.evented,
+              selectable: state.selectable,
+              visible: state.visible
+            });
+          } catch (error) {
+          }
+        });
       }
-      const file = new File([u8arr], fileName, { type: mime });
-      return file;
+      this._cropPrevEvented = null;
+    }
+    _removeCropRect() {
+      if (!this._cropRect)
+        return;
+      try {
+        if (this._cropHandlers && this._cropHandlers.length) {
+          this._cropHandlers.forEach((targetHandlers) => {
+            targetHandlers.handlers.forEach((handlerRecord) => {
+              targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
+            });
+          });
+        }
+      } catch (error) {
+      }
+      try {
+        this.canvas.remove(this._cropRect);
+      } catch (error) {
+      }
+      this._cropRect = null;
+      this._cropHandlers = [];
     }
     /**
-     * Enter crop mode: create a resizable/movable selection rect on top of the image.
+     * Enters crop mode by creating a resizable crop rectangle above the base image.
+     *
+     * Other canvas objects are made non-interactive while crop mode is active. Masks can be hidden during
+     * cropping when `crop.hideMasksDuringCrop` is enabled.
+     *
+     * @returns {void}
      * @public
      */
     enterCropMode() {
@@ -1494,12 +2358,18 @@
       this.canvas.selection = false;
       this.canvas.discardActiveObject();
       this.originalImage.setCoords();
-      const imgBr = this.originalImage.getBoundingRect(true, true);
+      const imageBounds = 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 left = Math.max(0, Math.floor(imageBounds.left + padding));
+      const top = Math.max(0, Math.floor(imageBounds.top + padding));
+      const maxCropWidth = Math.max(1, Math.floor(imageBounds.width - padding * 2));
+      const maxCropHeight = Math.max(1, Math.floor(imageBounds.height - padding * 2));
+      const configuredMinWidth = Math.max(1, Number(this.options.crop.minWidth) || 50);
+      const configuredMinHeight = Math.max(1, Number(this.options.crop.minHeight) || 50);
+      const minCropWidth = Math.min(configuredMinWidth, maxCropWidth);
+      const minCropHeight = Math.min(configuredMinHeight, maxCropHeight);
+      const width = minCropWidth;
+      const height = minCropHeight;
       const cropRect = new fabric.Rect({
         left,
         top,
@@ -1516,7 +2386,8 @@
         cornerSize: 8,
         objectCaching: false,
         originX: "left",
-        originY: "top"
+        originY: "top",
+        lockScalingFlip: true
       });
       this.canvas.add(cropRect);
       cropRect.isCropRect = true;
@@ -1524,63 +2395,59 @@
       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 });
+      const shouldHideMasks = !!(this.options.crop && this.options.crop.hideMasksDuringCrop);
+      this.canvas.getObjects().forEach((object) => {
+        if (object !== cropRect) {
+          this._cropPrevEvented.push({ object, evented: object.evented, selectable: object.selectable, visible: object.visible });
           try {
-            o.evented = false;
-            o.selectable = false;
-          } catch (e) {
+            const updates = {
+              evented: false,
+              selectable: false
+            };
+            if (shouldHideMasks && (object.maskId || object.maskLabel))
+              updates.visible = false;
+            object.set(updates);
+          } catch (error) {
           }
         }
       });
-      const onModified = () => {
+      const handleCropRectModified = () => {
         try {
+          const cropWidth = Math.max(1, Number(cropRect.width) || 1);
+          const cropHeight = Math.max(1, Number(cropRect.height) || 1);
+          const nextScaleX = Math.min(maxCropWidth / cropWidth, Math.max(minCropWidth / cropWidth, Number(cropRect.scaleX) || 1));
+          const nextScaleY = Math.min(maxCropHeight / cropHeight, Math.max(minCropHeight / cropHeight, Number(cropRect.scaleY) || 1));
+          cropRect.set({ scaleX: nextScaleX, scaleY: nextScaleY });
           cropRect.setCoords();
           this.canvas.requestRenderAll();
-        } catch (e) {
+        } catch (error) {
         }
       };
-      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 }] });
+      cropRect.on("modified", handleCropRectModified);
+      cropRect.on("moving", handleCropRectModified);
+      cropRect.on("scaling", handleCropRectModified);
+      this._cropHandlers.push({
+        target: cropRect,
+        handlers: [
+          { eventName: "modified", handler: handleCropRectModified },
+          { eventName: "moving", handler: handleCropRectModified },
+          { eventName: "scaling", handler: handleCropRectModified }
+        ]
+      });
       this._updateUI();
       this.canvas.renderAll();
     }
     /**
-     * Cancel crop mode and remove the temporary selection rect.
+     * Cancels crop mode and removes the temporary crop rectangle.
+     *
+     * @returns {void}
      * @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._removeCropRect();
+      this._restoreCropObjectState();
       this._cropMode = false;
       this.canvas.selection = !!this._prevSelectionSetting;
       this._prevSelectionSetting = void 0;
@@ -1589,8 +2456,14 @@
       this.canvas.renderAll();
     }
     /**
-     * Apply the current crop rectangle.
-     * remove all masks and export canvas snapshot and crop via offscreen canvas
+     * Applies the current crop rectangle to the base image.
+     *
+     * Masks are removed by default. When `crop.preserveMasksAfterCrop` is true, masks that intersect the crop
+     * region are shifted into the cropped coordinate space and remain editable. The operation is recorded as a
+     * single undoable history transition.
+     *
+     * @async
+     * @returns {Promise<void>} Resolves after the cropped image has been loaded and history is updated.
      * @public
      */
     async applyCrop() {
@@ -1598,136 +2471,91 @@
         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)));
+      const cropRegion = this._getClampedCanvasRegion(rectBounds);
+      const shouldPreserveMasks = !!(this.options.crop && this.options.crop.preserveMasksAfterCrop);
+      this._restoreCropObjectState();
       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 = this._serializeCanvasState();
+      } catch (error) {
+        this._reportWarning("applyCrop: could not serialize before state", error);
         beforeJson = null;
       }
+      const preservedMasks = [];
       try {
-        const masks = this.canvas.getObjects().filter((o) => o.maskId);
+        const masks = this.canvas.getObjects().filter((object) => object.maskId);
         if (masks && masks.length) {
-          masks.forEach((m) => {
+          masks.forEach((mask) => {
             try {
-              this._removeLabelForMask(m);
-              this.canvas.remove(m);
-            } catch (err) {
-              this._reportWarning("applyCrop: failed to remove mask", err);
+              mask.setCoords();
+              const maskBounds = mask.getBoundingRect(true, true);
+              const intersectsCrop = maskBounds.left < cropRegion.sourceX + cropRegion.sourceWidth && maskBounds.left + maskBounds.width > cropRegion.sourceX && maskBounds.top < cropRegion.sourceY + cropRegion.sourceHeight && maskBounds.top + maskBounds.height > cropRegion.sourceY;
+              this._removeLabelForMask(mask);
+              this.canvas.remove(mask);
+              if (shouldPreserveMasks && intersectsCrop) {
+                mask.set({
+                  left: (mask.left || 0) - cropRegion.sourceX,
+                  top: (mask.top || 0) - cropRegion.sourceY,
+                  visible: true
+                });
+                mask.setCoords();
+                preservedMasks.push(mask);
+              }
+            } catch (error) {
+              this._reportWarning("applyCrop: failed to remove mask", error);
             }
           });
-          this._lastMask = null;
-          this._lastMaskInitialLeft = null;
-          this._lastMaskInitialTop = null;
-          this._lastMaskInitialWidth = null;
+          this._clearMaskPlacementMemory();
           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) {
+      } catch (error) {
+        this._reportWarning("applyCrop: error while removing masks", error);
       }
+      this._removeCropRect();
       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;
+        croppedBase64 = await this._exportCanvasRegionToDataURL({
+          ...cropRegion,
+          multiplier: 1,
+          quality: this._normalizeQuality(this.options.downsampleQuality),
+          format: "jpeg"
         });
-      } catch (e) {
-        this._reportError("applyCrop: failed to create cropped image", e);
-        this._updateUI();
+      } catch (error) {
+        await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: failed to create cropped image", error);
         return;
       }
       try {
         await this.loadImage(croppedBase64);
-      } catch (e) {
-        this._reportError("applyCrop: loadImage(croppedBase64) failed", e);
-        this._updateUI();
+        if (preservedMasks.length) {
+          preservedMasks.forEach((mask) => {
+            this._rebindMaskEvents(mask);
+            this.canvas.add(mask);
+            this.canvas.bringToFront(mask);
+          });
+          this._lastMask = preservedMasks[preservedMasks.length - 1];
+          this.maskCounter = preservedMasks.reduce((max, mask) => Math.max(max, mask.maskId || 0), this.maskCounter);
+          this._updateMaskList();
+          this.canvas.renderAll();
+        }
+      } catch (error) {
+        await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: loadImage(croppedBase64) failed", error);
         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 = this._serializeCanvasState();
+      } catch (error) {
+        this._reportWarning("applyCrop: failed to serialize after state", error);
         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._pushStateTransition(beforeJson, afterJson);
+      } catch (error) {
+        this._reportWarning("applyCrop: failed to push history command", error);
       }
       this._updateUI();
       this.canvas.renderAll();
@@ -1739,9 +2567,9 @@
      * @private
      */
     _updateInputs() {
-      const scaleEl = document.getElementById(this.elements.scaleRate);
-      if (scaleEl)
-        scaleEl.value = Math.round(this.currentScale * 100);
+      const scaleInputElement = document.getElementById(this.elements.scaleRate);
+      if (scaleInputElement)
+        scaleInputElement.value = Math.round(this.currentScale * 100);
     }
     /**
      * Updates the enabled/disabled state of various UI controls (buttons)
@@ -1749,43 +2577,45 @@
      * @private
      */
     _updateUI() {
-      const hasImg = !!this.originalImage;
-      const masks = hasImg ? this.canvas.getObjects().filter((o) => o.maskId) : [];
+      const hasImage = !!this.originalImage;
+      const masks = hasImage ? this.canvas.getObjects().filter((object) => object.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 activeObject = this.canvas.getActiveObject();
+      const hasSelectedMask = activeObject && activeObject.maskId;
+      const isDefaultTransform = 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)
+      const isInCropMode = !!this._cropMode;
+      if (isInCropMode) {
+        for (const key of Object.keys(this.elements || {})) {
+          const element = document.getElementById(this.elements[key]);
+          if (!element)
             continue;
-          if (k === "applyCropBtn" || k === "cancelCropBtn") {
-            el.disabled = false;
+          if (key === "applyCropBtn" || key === "cancelCropBtn") {
+            this._setDisabled(key, false);
           } else {
-            el.disabled = true;
+            this._setDisabled(key, 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("zoomInBtn", !hasImage || this.isAnimating || this.currentScale >= this.options.maxScale);
+      this._setDisabled("zoomOutBtn", !hasImage || this.isAnimating || this.currentScale <= this.options.minScale);
+      this._setDisabled("rotateLeftBtn", !hasImage || this.isAnimating);
+      this._setDisabled("rotateRightBtn", !hasImage || this.isAnimating);
+      this._setDisabled("addMaskBtn", !hasImage || 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("mergeBtn", !hasImage || !hasMasks || this.isAnimating);
+      this._setDisabled("downloadBtn", !hasImage || this.isAnimating);
+      this._setDisabled("resetBtn", !hasImage || isDefaultTransform || this.isAnimating);
+      this._setDisabled("undoBtn", !hasImage || this.isAnimating || !canUndo);
+      this._setDisabled("redoBtn", !hasImage || this.isAnimating || !canRedo);
+      this._setDisabled("cropBtn", !hasImage || this.isAnimating);
       this._setDisabled("applyCropBtn", true);
       this._setDisabled("cancelCropBtn", true);
+      this._setDisabled("imageInput", this.isAnimating);
+      this._setDisabled("uploadArea", this.isAnimating);
     }
     /**
      * Enables or disables a specific UI element (typically a button) by its key.
@@ -1795,12 +2625,30 @@
      * @private
      */
     _setDisabled(key, disabled) {
-      const el = document.getElementById(this.elements[key]);
-      if (el)
-        el.disabled = !!disabled;
+      const element = document.getElementById(this.elements[key]);
+      if (!element)
+        return;
+      if ("disabled" in element) {
+        element.disabled = !!disabled;
+        return;
+      }
+      if (disabled) {
+        element.setAttribute("aria-disabled", "true");
+        element.style.pointerEvents = "none";
+      } else {
+        element.removeAttribute("aria-disabled");
+        element.style.pointerEvents = "";
+      }
+    }
+    _isElementDisabled(element) {
+      if (!element)
+        return false;
+      if ("disabled" in element)
+        return !!element.disabled;
+      return element.getAttribute("aria-disabled") === "true";
     }
     /**
-     * Automatically display and hide placeholders and containers based on the current image content
+     * Updates placeholder and canvas container visibility based on whether an image is loaded.
      * @private
      */
     _updatePlaceholderStatus() {
@@ -1809,21 +2657,22 @@
       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
+     * Shows or hides the placeholder and canvas container.
+     *
+     * @param {boolean} show - If true, displays the placeholder; otherwise displays the canvas container.
      * @private
      */
     _setPlaceholderVisible(show) {
-      if (!this.placeholderEl)
+      if (!this.placeholderElement || !this.containerElement)
         return;
       if (show) {
-        this.placeholderEl.classList.remove("d-none");
-        this.placeholderEl.classList.add("d-flex");
-        this.containerEl.classList.add("d-none");
+        this.placeholderElement.classList.remove("d-none");
+        this.placeholderElement.classList.add("d-flex");
+        this.containerElement.classList.add("d-none");
       } else {
-        this.placeholderEl.classList.remove("d-flex");
-        this.placeholderEl.classList.add("d-none");
-        this.containerEl.classList.remove("d-none");
+        this.placeholderElement.classList.remove("d-flex");
+        this.placeholderElement.classList.add("d-none");
+        this.containerElement.classList.remove("d-none");
       }
     }
     /**
@@ -1833,89 +2682,93 @@
      */
     dispose() {
       try {
-        for (const key in this._boundHandlers || {}) {
-          const handlers = this._boundHandlers[key] || [];
-          const el = document.getElementById(this.elements[key]);
-          if (!el)
+        for (const key in this._handlersByElementKey || {}) {
+          const handlers = this._handlersByElementKey[key] || [];
+          const element = document.getElementById(this.elements[key]);
+          if (!element)
             continue;
-          handlers.forEach((h) => {
+          handlers.forEach((handlerRecord) => {
             try {
-              el.removeEventListener(h.event, h.handler);
-            } catch (e) {
+              element.removeEventListener(handlerRecord.eventName, handlerRecord.handler);
+            } catch (error) {
             }
           });
         }
-      } catch (e) {
+      } catch (error) {
       }
       if (this._cropRect) {
         try {
           this.canvas.remove(this._cropRect);
-        } catch (e) {
+        } catch (error) {
         }
         this._cropRect = null;
       }
+      if (this.containerElement && this._containerOriginalOverflow !== void 0) {
+        try {
+          this.containerElement.style.overflow = this._containerOriginalOverflow;
+        } catch (error) {
+        }
+      }
       if (this.canvas) {
         try {
           this.canvas.dispose();
-        } catch (e) {
+        } catch (error) {
         }
         this.canvas = null;
-        this.canvasEl = null;
+        this.canvasElement = null;
         this.isImageLoadedToCanvas = false;
       }
-      this._boundHandlers = {};
+      this._handlersByElementKey = {};
     }
   };
   var AnimationQueue = class {
     /**
-     * Creates a new AnimationQueue.
-     *
-     * @constructor
+     * Creates an empty animation queue.
      */
     constructor() {
-      this.queue = [];
-      this.running = false;
+      this.animationTasks = [];
+      this.isRunning = 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.
+     * @param {AnimationTaskCallback} animationFn - Function that returns a value, Promise, or awaitable animation result.
+     * @returns {Promise<unknown>} Resolves or rejects with the queued animation result.
      */
     async add(animationFn) {
       return new Promise((resolve, reject) => {
-        this.queue.push({ fn: animationFn, resolve, reject });
-        if (!this.running) {
-          this.processQueue();
+        this.animationTasks.push({ animationFn, resolve, reject });
+        if (!this.isRunning) {
+          this._drainQueue();
         }
       });
     }
     /**
-     * Internal helper that processes the animation queue sequentially until it is empty.
+     * Runs queued animation tasks sequentially until the queue is empty.
      *
      * @private
      * @returns {Promise<void>}
      */
-    async processQueue() {
-      if (this.queue.length === 0) {
-        this.running = false;
+    async _drainQueue() {
+      if (this.animationTasks.length === 0) {
+        this.isRunning = false;
         return;
       }
-      this.running = true;
-      const { fn, resolve, reject } = this.queue.shift();
+      this.isRunning = true;
+      const { animationFn, resolve, reject } = this.animationTasks.shift();
       try {
-        const result = await fn();
+        const result = await animationFn();
         resolve(result);
       } catch (error) {
         reject(error);
       }
-      this.processQueue();
+      await this._drainQueue();
     }
   };
   var Command = class {
     /**
-     * @param {Function} execute  The function that performs the action.
-     * @param {Function} undo     The function that reverts the action.
+     * @param {HistoryTaskCallback} execute - Function that performs the action.
+     * @param {HistoryTaskCallback} undo - Function that reverts the action.
      */
     constructor(execute, undo) {
       this.execute = execute;
@@ -1924,12 +2777,32 @@
   };
   var HistoryManager = class {
     /**
-     * @param {number} [maxSize=50]  Maximum number of commands to keep in history.
+     * @param {number} [maxSize=50] - Maximum number of commands to keep in history.
      */
     constructor(maxSize = 50) {
       this.history = [];
       this.currentIndex = -1;
       this.maxSize = maxSize;
+      this.pending = Promise.resolve();
+    }
+    /**
+     * Queues a history task after the previously queued undo/redo task completes.
+     *
+     * @param {HistoryTaskCallback} task - Task to run after earlier history work settles.
+     * @returns {Promise<void>} Resolves or rejects with the queued task result.
+     * @private
+     */
+    enqueue(task) {
+      const nextTask = this.pending.then(task, task);
+      let pendingAfterTask;
+      const resetPending = () => {
+        if (this.pending === pendingAfterTask) {
+          this.pending = Promise.resolve();
+        }
+      };
+      pendingAfterTask = nextTask.then(resetPending, resetPending);
+      this.pending = pendingAfterTask;
+      return nextTask;
     }
     /**
      * Executes a new command and pushes it onto the history stack.
@@ -1940,6 +2813,16 @@
      */
     execute(command) {
       command.execute();
+      this.push(command);
+    }
+    /**
+     * Pushes an already-applied command onto the history stack.
+     * Truncates any "future" history when branching.
+     *
+     * @param {Command} command  The command to push.
+     * @returns {void}
+     */
+    push(command) {
       if (this.currentIndex < this.history.length - 1) {
         this.history = this.history.slice(0, this.currentIndex + 1);
       }
@@ -1969,24 +2852,30 @@
     /**
      * Undoes the last executed command if possible.
      *
-     * @returns {void}
+     * @returns {Promise<void>} Resolves after the undo task completes.
      */
     undo() {
-      if (this.currentIndex >= 0) {
-        this.history[this.currentIndex].undo();
-        this.currentIndex--;
-      }
+      return this.enqueue(async () => {
+        if (this.currentIndex >= 0) {
+          const index = this.currentIndex;
+          await this.history[index].undo();
+          this.currentIndex = index - 1;
+        }
+      });
     }
     /**
      * Redoes the next command in history if possible.
      *
-     * @returns {void}
+     * @returns {Promise<void>} Resolves after the redo task completes.
      */
     redo() {
-      if (this.currentIndex < this.history.length - 1) {
-        this.currentIndex++;
-        this.history[this.currentIndex].execute();
-      }
+      return this.enqueue(async () => {
+        if (this.currentIndex < this.history.length - 1) {
+          const index = this.currentIndex + 1;
+          await this.history[index].execute();
+          this.currentIndex = index;
+        }
+      });
     }
   };
   var image_editor_default = ImageEditor;