@bensitu/image-editor 1.4.1 → 1.5.0

package/dist/image-editor.js

@@ -3,13 +3,13 @@
   /**
    * @file image-editor.js
    * @module image-editor
-   * @version 1.4.1
+   * @version 1.5.0
    * @author Ben Situ
    * @license MIT
    * @description Lightweight canvas-based image editor with masking/transform/export support.
    */
   var fabric = null;
-  var INTERNAL_OPERATION_TOKEN = /* @__PURE__ */ Symbol("ImageEditorInternalOperation");
+  var INTERNAL_OPERATION_TOKEN = /* @__PURE__ */ Symbol.for("ImageEditorInternalOperation");
   function getGlobalScope() {
     if (typeof globalThis !== "undefined") return globalThis;
     if (typeof self !== "undefined") return self;
@@ -144,7 +144,7 @@
       this._activeAnimationRejectors = /* @__PURE__ */ new Set();
       this._disposed = false;
       this._initialized = false;
-      this.onImageLoaded = typeof options.onImageLoaded === "function" ? options.onImageLoaded : null;
+      this.onImageLoaded = typeof this.options.onImageLoaded === "function" ? this.options.onImageLoaded : null;
       this.animationQueue = new AnimationQueue();
       this.historyManager = new HistoryManager(this.maxHistorySize);
     }
@@ -190,10 +190,12 @@
      * 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, undoBtn, redoBtn, imageInput,
-     *   uploadArea, cropBtn, applyCropBtn, and cancelCropBtn. Unknown keys are ignored.
+     *   Supported keys include: canvas, canvasContainer, imagePlaceholder, scalePercentageInput,
+     *   rotateLeftDegreesInput, rotateRightDegreesInput, rotateLeftButton, rotateRightButton,
+     *   createMaskButton, removeSelectedMaskButton, removeAllMasksButton, mergeMasksButton,
+     *   downloadImageButton, maskList, zoomInButton, zoomOutButton, resetImageTransformButton,
+     *   undoButton, redoButton, imageInput, uploadArea, enterCropModeButton, applyCropButton,
+     *   and cancelCropButton. Deprecated 1.x names remain supported as aliases.
      *
      * @returns {void}
      *
@@ -202,7 +204,7 @@
      * @example
      * editor.init({
      *   canvas: 'myFabricCanvasId',
-     *   downloadBtn: 'myDownloadButtonId'
+     *   downloadImageButton: 'myDownloadButtonId'
      * });
      */
     init(idMap = {}) {
@@ -221,33 +223,53 @@
       this._containerOriginalOverflow = null;
       this._lastContainerViewportSize = null;
       this._canvasElementOriginalStyle = null;
+      this._deprecatedElementKeyWarnings = /* @__PURE__ */ new Set();
       const defaults = {
         canvas: "fabricCanvas",
         canvasContainer: null,
         // Pass an ID here if you have a scrollable viewport container
-        imgPlaceholder: "imgPlaceholder",
-        scaleRate: "scaleRate",
-        rotationLeftInput: "rotationLeftInput",
-        rotationRightInput: "rotationRightInput",
-        rotateLeftBtn: "rotateLeftBtn",
-        rotateRightBtn: "rotateRightBtn",
-        addMaskBtn: "addMaskBtn",
-        removeMaskBtn: "removeMaskBtn",
-        removeAllMasksBtn: "removeAllMasksBtn",
-        mergeBtn: "mergeBtn",
-        downloadBtn: "downloadBtn",
+        imagePlaceholder: "imagePlaceholder",
+        imgPlaceholder: null,
+        scalePercentageInput: "scalePercentageInput",
+        scaleRate: null,
+        rotateLeftDegreesInput: "rotateLeftDegreesInput",
+        rotationLeftInput: null,
+        rotateRightDegreesInput: "rotateRightDegreesInput",
+        rotationRightInput: null,
+        rotateLeftButton: "rotateLeftButton",
+        rotateLeftBtn: null,
+        rotateRightButton: "rotateRightButton",
+        rotateRightBtn: null,
+        createMaskButton: "createMaskButton",
+        addMaskBtn: null,
+        removeSelectedMaskButton: "removeSelectedMaskButton",
+        removeMaskBtn: null,
+        removeAllMasksButton: "removeAllMasksButton",
+        removeAllMasksBtn: null,
+        mergeMasksButton: "mergeMasksButton",
+        mergeBtn: null,
+        downloadImageButton: "downloadImageButton",
+        downloadBtn: null,
         maskList: "maskList",
-        zoomInBtn: "zoomInBtn",
-        zoomOutBtn: "zoomOutBtn",
-        resetBtn: "resetBtn",
-        undoBtn: "undoBtn",
-        redoBtn: "redoBtn",
+        zoomInButton: "zoomInButton",
+        zoomInBtn: null,
+        zoomOutButton: "zoomOutButton",
+        zoomOutBtn: null,
+        resetImageTransformButton: "resetImageTransformButton",
+        resetBtn: null,
+        undoButton: "undoButton",
+        undoBtn: null,
+        redoButton: "redoButton",
+        redoBtn: null,
         imageInput: "imageInput",
-        cropBtn: "cropBtn",
-        applyCropBtn: "applyCropBtn",
-        cancelCropBtn: "cancelCropBtn"
+        enterCropModeButton: "enterCropModeButton",
+        cropBtn: null,
+        applyCropButton: "applyCropButton",
+        applyCropBtn: null,
+        cancelCropButton: "cancelCropButton",
+        cancelCropBtn: null
       };
-      this.elements = { ...defaults, ...idMap };
+      this.elements = this._resolveElementIdMap(idMap || {}, defaults);
       this._elementCache = {};
       this._initCanvas();
       this._bindEvents();
@@ -260,6 +282,63 @@
         this._updatePlaceholderStatus();
       }
     }
+    _resolveElementIdMap(idMap, defaults) {
+      const resolved = { ...defaults, ...idMap };
+      this._resolveElementAliases(resolved, idMap, defaults, "imagePlaceholder", ["imgPlaceholder"]);
+      this._resolveElementAliases(resolved, idMap, defaults, "scalePercentageInput", ["scaleRate"]);
+      this._resolveElementAliases(resolved, idMap, defaults, "rotateLeftDegreesInput", ["rotationLeftInput"]);
+      this._resolveElementAliases(resolved, idMap, defaults, "rotateRightDegreesInput", ["rotationRightInput"]);
+      this._resolveElementAlias(resolved, idMap, defaults, "rotateLeftButton", "rotateLeftBtn");
+      this._resolveElementAlias(resolved, idMap, defaults, "rotateRightButton", "rotateRightBtn");
+      this._resolveElementAlias(resolved, idMap, defaults, "createMaskButton", "addMaskBtn");
+      this._resolveElementAliases(resolved, idMap, defaults, "removeSelectedMaskButton", ["removeMaskBtn"]);
+      this._resolveElementAlias(resolved, idMap, defaults, "removeAllMasksButton", "removeAllMasksBtn");
+      this._resolveElementAlias(resolved, idMap, defaults, "mergeMasksButton", "mergeBtn");
+      this._resolveElementAliases(resolved, idMap, defaults, "downloadImageButton", ["downloadBtn"]);
+      this._resolveElementAlias(resolved, idMap, defaults, "zoomInButton", "zoomInBtn");
+      this._resolveElementAlias(resolved, idMap, defaults, "zoomOutButton", "zoomOutBtn");
+      this._resolveElementAlias(resolved, idMap, defaults, "resetImageTransformButton", "resetBtn");
+      this._resolveElementAlias(resolved, idMap, defaults, "undoButton", "undoBtn");
+      this._resolveElementAlias(resolved, idMap, defaults, "redoButton", "redoBtn");
+      this._resolveElementAliases(resolved, idMap, defaults, "enterCropModeButton", ["cropBtn"]);
+      this._resolveElementAlias(resolved, idMap, defaults, "applyCropButton", "applyCropBtn");
+      this._resolveElementAlias(resolved, idMap, defaults, "cancelCropButton", "cancelCropBtn");
+      return resolved;
+    }
+    _resolveElementAlias(resolved, idMap, defaults, canonicalKey, deprecatedKey) {
+      this._resolveElementAliases(resolved, idMap, defaults, canonicalKey, [deprecatedKey]);
+    }
+    _resolveElementAliases(resolved, idMap, defaults, canonicalKey, deprecatedKeys) {
+      const hasCanonicalKey = Object.prototype.hasOwnProperty.call(idMap, canonicalKey);
+      if (hasCanonicalKey) {
+        resolved[canonicalKey] = idMap[canonicalKey];
+        return;
+      }
+      let deprecatedValue;
+      let hasDeprecatedValue = false;
+      for (const deprecatedKey of deprecatedKeys) {
+        if (Object.prototype.hasOwnProperty.call(idMap, deprecatedKey)) {
+          if (!hasDeprecatedValue) {
+            deprecatedValue = idMap[deprecatedKey];
+            hasDeprecatedValue = true;
+          }
+          this._warnDeprecatedElementIdKey(deprecatedKey, canonicalKey);
+        }
+      }
+      if (hasDeprecatedValue) {
+        resolved[canonicalKey] = deprecatedValue;
+        return;
+      }
+      resolved[canonicalKey] = defaults[canonicalKey];
+    }
+    _warnDeprecatedElementIdKey(deprecatedKey, canonicalKey) {
+      if (!this._deprecatedElementKeyWarnings) this._deprecatedElementKeyWarnings = /* @__PURE__ */ new Set();
+      if (this._deprecatedElementKeyWarnings.has(deprecatedKey)) return;
+      this._deprecatedElementKeyWarnings.add(deprecatedKey);
+      this._reportWarning(
+        `ElementIdMap.${deprecatedKey} is deprecated. Use ${canonicalKey} instead. This alias will be removed in v2.0.0.`
+      );
+    }
     _reportError(message, error = null) {
       const handler = this.options && this.options.onError;
       if (typeof handler !== "function") return;
@@ -276,6 +355,11 @@
       } catch {
       }
     }
+    _notifyImageLoaded() {
+      const optionsCallback = this.options && this.options.onImageLoaded;
+      const callback = typeof optionsCallback === "function" ? optionsCallback : this.onImageLoaded;
+      if (typeof callback === "function") callback();
+    }
     /**
      * Initializes the Fabric canvas, viewport elements, and selection event handlers.
      *
@@ -298,7 +382,7 @@
       } else {
         this.containerElement = canvasElement.parentElement;
       }
-      this.placeholderElement = this._getElement("imgPlaceholder") || null;
+      this.placeholderElement = this._getElement("imagePlaceholder") || null;
       let initialWidth = this.options.canvasWidth;
       let initialHeight = this.options.canvasHeight;
       if (this.containerElement) {
@@ -448,20 +532,20 @@
           });
         }
       });
-      this._bindIfExists("zoomInBtn", "click", () => this.scaleImage(this.currentScale + this.options.scaleStep).catch((error) => this._reportError("scaleImage failed", error)));
-      this._bindIfExists("zoomOutBtn", "click", () => this.scaleImage(this.currentScale - this.options.scaleStep).catch((error) => this._reportError("scaleImage failed", error)));
-      this._bindIfExists("resetBtn", "click", () => {
+      this._bindIfExists("zoomInButton", "click", () => this.scaleImage(this.currentScale + this.options.scaleStep).catch((error) => this._reportError("scaleImage failed", error)));
+      this._bindIfExists("zoomOutButton", "click", () => this.scaleImage(this.currentScale - this.options.scaleStep).catch((error) => this._reportError("scaleImage failed", error)));
+      this._bindIfExists("resetImageTransformButton", "click", () => {
         this.resetImageTransform().catch((error) => this._reportError("resetImageTransform failed", error));
       });
-      this._bindIfExists("addMaskBtn", "click", () => this.createMask());
-      this._bindIfExists("removeMaskBtn", "click", () => this.removeSelectedMask());
-      this._bindIfExists("removeAllMasksBtn", "click", () => this.removeAllMasks());
-      this._bindIfExists("mergeBtn", "click", () => this.mergeMasks().catch((error) => this._reportError("merge error", error)));
-      this._bindIfExists("downloadBtn", "click", () => this.downloadImage());
-      this._bindIfExists("undoBtn", "click", () => this.undo().catch((error) => this._reportError("undo failed", error)));
-      this._bindIfExists("redoBtn", "click", () => this.redo().catch((error) => this._reportError("redo failed", error)));
-      this._bindIfExists("rotateLeftBtn", "click", () => {
-        const rotationInputElement = this._getElement("rotationLeftInput");
+      this._bindIfExists("createMaskButton", "click", () => this.createMask());
+      this._bindIfExists("removeSelectedMaskButton", "click", () => this.removeSelectedMask());
+      this._bindIfExists("removeAllMasksButton", "click", () => this.removeAllMasks());
+      this._bindIfExists("mergeMasksButton", "click", () => this.mergeMasks().catch((error) => this._reportError("merge error", error)));
+      this._bindIfExists("downloadImageButton", "click", () => this.downloadImage());
+      this._bindIfExists("undoButton", "click", () => this.undo().catch((error) => this._reportError("undo failed", error)));
+      this._bindIfExists("redoButton", "click", () => this.redo().catch((error) => this._reportError("redo failed", error)));
+      this._bindIfExists("rotateLeftButton", "click", () => {
+        const rotationInputElement = this._getElement("rotateLeftDegreesInput");
         let step = this.options.rotationStep;
         if (rotationInputElement) {
           const parsedStep = parseFloat(rotationInputElement.value);
@@ -469,8 +553,8 @@
         }
         this.rotateImage(this.currentRotation - step).catch((error) => this._reportError("rotateImage failed", error));
       });
-      this._bindIfExists("rotateRightBtn", "click", () => {
-        const rotationInputElement = this._getElement("rotationRightInput");
+      this._bindIfExists("rotateRightButton", "click", () => {
+        const rotationInputElement = this._getElement("rotateRightDegreesInput");
         let step = this.options.rotationStep;
         if (rotationInputElement) {
           const parsedStep = parseFloat(rotationInputElement.value);
@@ -478,11 +562,11 @@
         }
         this.rotateImage(this.currentRotation + step).catch((error) => this._reportError("rotateImage failed", error));
       });
-      this._bindIfExists("cropBtn", "click", () => this.enterCropMode());
-      this._bindIfExists("applyCropBtn", "click", () => {
+      this._bindIfExists("enterCropModeButton", "click", () => this.enterCropMode());
+      this._bindIfExists("applyCropButton", "click", () => {
         this.applyCrop().catch((error) => this._reportError("applyCrop failed", error));
       });
-      this._bindIfExists("cancelCropBtn", "click", () => this.cancelCrop());
+      this._bindIfExists("cancelCropButton", "click", () => this.cancelCrop());
       this._bindIfExists("maskList", "click", (event) => this._handleMaskListClick(event));
     }
     /**
@@ -573,12 +657,14 @@
         const imageElement = await this._createImageElement(imageBase64);
         if (this._disposed || !this.canvas) throw new Error("Editor was disposed while loading image");
         let loadSource = imageBase64;
-        if (this.options.downsampleOnLoad) {
-          const shouldResize = imageElement.naturalWidth > this.options.downsampleMaxWidth || imageElement.naturalHeight > this.options.downsampleMaxHeight;
+        const downsampleMaxWidth = Number(this.options.downsampleMaxWidth);
+        const downsampleMaxHeight = Number(this.options.downsampleMaxHeight);
+        if (this.options.downsampleOnLoad && downsampleMaxWidth > 0 && downsampleMaxHeight > 0) {
+          const shouldResize = imageElement.naturalWidth > downsampleMaxWidth || imageElement.naturalHeight > downsampleMaxHeight;
           if (shouldResize) {
             const ratio = Math.min(
-              this.options.downsampleMaxWidth / imageElement.naturalWidth,
-              this.options.downsampleMaxHeight / imageElement.naturalHeight
+              downsampleMaxWidth / imageElement.naturalWidth,
+              downsampleMaxHeight / imageElement.naturalHeight
             );
             const targetWidth = Math.round(imageElement.naturalWidth * ratio);
             const targetHeight = Math.round(imageElement.naturalHeight * ratio);
@@ -590,6 +676,8 @@
               imageBase64
             );
           }
+        } else if (this.options.downsampleOnLoad) {
+          this._reportWarning("loadImage: downsample limits must be positive numbers; using the original image");
         }
         const fabricImage = await this._createFabricImageFromURL(loadSource);
         if (this._disposed || !this.canvas) throw new Error("Editor was disposed while loading image");
@@ -648,9 +736,7 @@
         this._updateUI();
         this.canvas.renderAll();
         this._lastSnapshot = this._captureCanvasStateOrThrow("loadImage");
-        if (typeof this.onImageLoaded === "function") {
-          this.onImageLoaded();
-        }
+        this._notifyImageLoaded();
       } catch (error) {
         await this._rollbackLoadImageTransaction(transaction);
         throw error;
@@ -667,6 +753,15 @@
       const fabricInstance = ensureFabric();
       return !!(this.originalImage && fabricInstance && this.originalImage instanceof fabricInstance.Image && this.originalImage.width > 0 && this.originalImage.height > 0);
     }
+    /**
+     * Checks whether the editor is in a temporary non-mutating state.
+     *
+     * @returns {boolean} True while loading, animating, cropping, or running a compound operation.
+     * @public
+     */
+    isBusy() {
+      return !!(this.isAnimating || this._cropMode || this._isLoading || this._activeOperationToken || this.animationQueue && this.animationQueue.isBusy());
+    }
     /**
      * Creates an HTMLImageElement from a given data URL.
      * 
@@ -694,7 +789,7 @@
           try {
             imageElement.src = "";
           } catch (error) {
-            void error;
+            this._reportWarning("Image timeout cleanup failed", error);
           }
         }, safeTimeoutMs);
         imageElement.onload = () => settle(() => resolve(imageElement));
@@ -738,7 +833,6 @@
     _captureLoadImageTransaction() {
       return {
         canvasState: this._serializeCanvasState(),
-        originalImage: this.originalImage,
         baseImageScale: this.baseImageScale,
         currentScale: this.currentScale,
         currentRotation: this.currentRotation,
@@ -763,6 +857,7 @@
     async _rollbackLoadImageTransaction(transaction) {
       if (!transaction || !this.canvas || this._disposed) return;
       let didRestoreCanvasState = false;
+      let didFailCanvasRestore = false;
       try {
         if (transaction.canvasState) {
           await this.loadFromState(transaction.canvasState);
@@ -770,22 +865,27 @@
         }
       } catch (error) {
         this._lastMask = null;
+        didFailCanvasRestore = true;
         this._reportError("loadImage rollback failed", error);
       }
-      this.baseImageScale = transaction.baseImageScale;
-      this.currentScale = transaction.currentScale;
-      this.currentRotation = transaction.currentRotation;
-      this.maskCounter = transaction.maskCounter;
-      this.isImageLoadedToCanvas = transaction.isImageLoadedToCanvas;
-      this._lastSnapshot = transaction.lastSnapshot;
-      if (didRestoreCanvasState) {
-        this._restoreLastMaskReference(transaction.lastMask);
+      if (didFailCanvasRestore) {
+        this._reconcileEditorStateFromCanvas();
       } else {
-        this._lastMask = null;
+        this.baseImageScale = transaction.baseImageScale;
+        this.currentScale = transaction.currentScale;
+        this.currentRotation = transaction.currentRotation;
+        this.maskCounter = transaction.maskCounter;
+        this.isImageLoadedToCanvas = transaction.isImageLoadedToCanvas;
+        this._lastSnapshot = transaction.lastSnapshot;
+        if (didRestoreCanvasState) {
+          this._restoreLastMaskReference(transaction.lastMask);
+        } else {
+          this._lastMask = null;
+        }
+        this._lastMaskInitialLeft = transaction.lastMaskInitialLeft;
+        this._lastMaskInitialTop = transaction.lastMaskInitialTop;
+        this._lastMaskInitialWidth = transaction.lastMaskInitialWidth;
       }
-      this._lastMaskInitialLeft = transaction.lastMaskInitialLeft;
-      this._lastMaskInitialTop = transaction.lastMaskInitialTop;
-      this._lastMaskInitialWidth = transaction.lastMaskInitialWidth;
       this._restoreElementVisibility(this.placeholderElement, transaction.placeholderVisibility);
       this._restoreElementVisibility(this._getCanvasVisibilityElement(), transaction.canvasVisibility);
       if (this.containerElement) {
@@ -798,6 +898,46 @@
       this._updateUI();
       if (this.canvas) this.canvas.renderAll();
     }
+    _reconcileEditorStateFromCanvas() {
+      if (!this.canvas) {
+        this.originalImage = null;
+        this.baseImageScale = 1;
+        this.currentScale = 1;
+        this.currentRotation = 0;
+        this.maskCounter = 0;
+        this.isImageLoadedToCanvas = false;
+        this._lastSnapshot = null;
+        this._clearMaskPlacementMemory();
+        return;
+      }
+      const canvasObjects = this.canvas.getObjects();
+      this.originalImage = canvasObjects.find((object) => object.type === "image" && !object.maskId) || null;
+      if (this.originalImage) {
+        const imageScale = Number(this.originalImage.scaleX) || 1;
+        this.baseImageScale = imageScale;
+        this.currentScale = 1;
+        this.currentRotation = Number(this.originalImage.angle) || 0;
+      } else {
+        this.baseImageScale = 1;
+        this.currentScale = 1;
+        this.currentRotation = 0;
+      }
+      const masks = canvasObjects.filter((object) => object.maskId);
+      this.maskCounter = masks.reduce((max, mask) => Math.max(max, Number(mask.maskId) || 0), 0);
+      this._lastMask = masks[masks.length - 1] || null;
+      if (!this._lastMask) {
+        this._lastMaskInitialLeft = null;
+        this._lastMaskInitialTop = null;
+        this._lastMaskInitialWidth = null;
+      }
+      this.isImageLoadedToCanvas = !!this.originalImage;
+      try {
+        this._lastSnapshot = this._serializeCanvasState();
+      } catch (error) {
+        this._lastSnapshot = null;
+        this._reportWarning("loadImage rollback: failed to reconcile canvas snapshot", error);
+      }
+    }
     _restoreLastMaskReference(previousLastMask) {
       if (!this.canvas) {
         this._lastMask = null;
@@ -824,12 +964,19 @@
      * @private
      */
     _resampleImageToDataURL(imageElement, targetWidth, targetHeight, quality = 0.92, sourceDataUrl = null) {
+      const sourceWidth = Math.max(1, Number(imageElement && (imageElement.naturalWidth || imageElement.width)) || 0);
+      const sourceHeight = Math.max(1, Number(imageElement && (imageElement.naturalHeight || imageElement.height)) || 0);
+      const safeTargetWidth = Math.round(Number(targetWidth));
+      const safeTargetHeight = Math.round(Number(targetHeight));
+      if (!Number.isFinite(safeTargetWidth) || !Number.isFinite(safeTargetHeight) || safeTargetWidth <= 0 || safeTargetHeight <= 0) {
+        throw new Error("Invalid image resample target dimensions");
+      }
       const offscreenCanvas = document.createElement("canvas");
-      offscreenCanvas.width = targetWidth;
-      offscreenCanvas.height = targetHeight;
+      offscreenCanvas.width = safeTargetWidth;
+      offscreenCanvas.height = safeTargetHeight;
       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);
+      context.drawImage(imageElement, 0, 0, sourceWidth, sourceHeight, 0, 0, safeTargetWidth, safeTargetHeight);
       return offscreenCanvas.toDataURL(this._getDownsampleMimeType(sourceDataUrl), quality);
     }
     _getDataUrlMimeType(dataUrl) {
@@ -861,6 +1008,7 @@
      * @private
      */
     _setCanvasSizeInt(width, height) {
+      if (!this.canvas) return;
       const integerWidth = Math.max(1, Math.round(Number(width) || 1));
       const integerHeight = Math.max(1, Math.round(Number(height) || 1));
       this.canvas.setWidth(integerWidth);
@@ -1133,7 +1281,7 @@
     /**
      * 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.
+     * @returns {{version:number, baseImageScale:number, currentScale:number, currentRotation:number, maskCounter:number, canvasWidth:number, canvasHeight:number}} Serializable editor metadata.
      * @private
      */
     _serializeEditorMetadata() {
@@ -1141,12 +1289,16 @@
       const currentScale = Number(this.currentScale);
       const currentRotation = Number(this.currentRotation);
       const maskCounter = Number(this.maskCounter);
+      const canvasWidth = this.canvas ? Number(this.canvas.getWidth()) : NaN;
+      const canvasHeight = this.canvas ? Number(this.canvas.getHeight()) : NaN;
       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
+        maskCounter: Number.isFinite(maskCounter) && maskCounter > 0 ? Math.floor(maskCounter) : 0,
+        canvasWidth: Number.isFinite(canvasWidth) && canvasWidth > 0 ? Math.round(canvasWidth) : 1,
+        canvasHeight: Number.isFinite(canvasHeight) && canvasHeight > 0 ? Math.round(canvasHeight) : 1
       };
     }
     _serializeCanvasState() {
@@ -1330,10 +1482,42 @@
     }
     _getJpegBackgroundColor() {
       const backgroundColor = String(this.options.backgroundColor || "").trim();
-      if (!backgroundColor || backgroundColor === "transparent") return "#ffffff";
-      if (/^rgba\([^)]*,\s*0(?:\.0+)?\s*\)$/i.test(backgroundColor)) return "#ffffff";
+      if (!backgroundColor || this._isTransparentCssColor(backgroundColor)) return "#ffffff";
       return backgroundColor;
     }
+    _isTransparentCssColor(color) {
+      const normalizedColor = String(color || "").trim().toLowerCase();
+      if (!normalizedColor || normalizedColor === "transparent") return true;
+      const hexAlphaMatch = normalizedColor.match(/^#(?:[0-9a-f]{3}([0-9a-f])|[0-9a-f]{6}([0-9a-f]{2}))$/i);
+      if (hexAlphaMatch) {
+        const alpha = hexAlphaMatch[1] || hexAlphaMatch[2];
+        return alpha === "0" || alpha === "00";
+      }
+      const slashAlphaMatch = normalizedColor.match(/^(?:rgba?|hsla?)\([^)]*\/\s*([^)]+)\)$/i);
+      if (slashAlphaMatch) return this._isZeroCssAlpha(slashAlphaMatch[1]);
+      const commaAlphaMatch = normalizedColor.match(/^(?:rgba|hsla)\((.*)\)$/i);
+      if (commaAlphaMatch) {
+        const parts = commaAlphaMatch[1].split(",");
+        if (parts.length >= 4) return this._isZeroCssAlpha(parts[parts.length - 1]);
+      }
+      return false;
+    }
+    _isZeroCssAlpha(alphaValue) {
+      const normalizedAlpha = String(alphaValue || "").trim();
+      if (!normalizedAlpha) return false;
+      if (normalizedAlpha.endsWith("%")) return Number.parseFloat(normalizedAlpha) === 0;
+      return Number(normalizedAlpha) === 0;
+    }
+    _decodeBase64Payload(base64Payload) {
+      const payload = String(base64Payload || "");
+      if (typeof atob === "function") {
+        return Uint8Array.from(atob(payload), (char) => char.charCodeAt(0));
+      }
+      if (typeof Buffer !== "undefined" && typeof Buffer.from === "function") {
+        return new Uint8Array(Buffer.from(payload, "base64"));
+      }
+      throw new Error("Base64 decoding is unavailable");
+    }
     /** 
      * Gets the top-left corner coordinates of the given object.
      * Used for geometry calculations (e.g., scale, rotate).
@@ -1450,17 +1634,13 @@
           requiredWidth = Math.max(requiredWidth, Math.ceil(boundingRect.left + boundingRect.width + padding));
           requiredHeight = Math.max(requiredHeight, Math.ceil(boundingRect.top + boundingRect.height + padding));
         });
-        const shouldUseScrollSafeViewport = this.options.fitImageToCanvas || this.options.coverImageToCanvas;
         let minWidth = 0;
         let minHeight = 0;
-        if (shouldUseScrollSafeViewport) {
+        if (this.containerElement) {
           const viewport = this._getContainerViewportSize();
           const safetyMargin = this._getScrollSafetyMargin();
           minWidth = Math.max(1, viewport.width - safetyMargin);
           minHeight = Math.max(1, viewport.height - safetyMargin);
-        } else if (this.containerElement) {
-          minWidth = Math.floor(this.containerElement.clientWidth || 0);
-          minHeight = Math.floor(this.containerElement.clientHeight || 0);
         }
         const newWidth = Math.max(currentWidth, minWidth, requiredWidth);
         const newHeight = Math.max(currentHeight, minHeight, requiredHeight);
@@ -1529,9 +1709,15 @@
     _assertEditorAvailable(operationName) {
       if (this._disposed || !this.canvas) throw new Error(`${operationName} cannot run after the editor has been disposed`);
     }
+    _isCropModeAllowedOperation(operationName) {
+      return operationName === "applyCrop" || operationName === "cancelCrop";
+    }
     _assertIdleForOperation(operationName, options = {}) {
       this._assertEditorAvailable(operationName);
       const isOwnInternalOperation = this._isOwnInternalOperation(options);
+      if (this._cropMode && !this._isCropModeAllowedOperation(operationName) && !isOwnInternalOperation) {
+        throw new Error(`${operationName} cannot run while crop mode is active`);
+      }
       if (this.isAnimating || this.animationQueue && this.animationQueue.isBusy()) {
         throw new Error(`${operationName} cannot run while an animation is running`);
       }
@@ -1544,10 +1730,14 @@
     }
     _assertCanQueueAnimation(operationName, options = {}) {
       this._assertEditorAvailable(operationName);
-      if (this._isLoading && !this._isOwnInternalOperation(options)) {
+      const isOwnInternalOperation = this._isOwnInternalOperation(options);
+      if (this._cropMode && !this._isCropModeAllowedOperation(operationName) && !isOwnInternalOperation) {
+        throw new Error(`${operationName} cannot run while crop mode is active`);
+      }
+      if (this._isLoading && !isOwnInternalOperation) {
         throw new Error(`${operationName} cannot run while an image is loading`);
       }
-      if (this._activeOperationToken && !this._isOwnInternalOperation(options)) {
+      if (this._activeOperationToken && !isOwnInternalOperation) {
         throw new Error(`${operationName} cannot run while ${this._activeOperationName || "another operation"} is running`);
       }
     }
@@ -1734,10 +1924,19 @@
       }
       return this.animationQueue.add(async () => {
         const before = this._lastSnapshot || this._captureCanvasStateOrThrow("resetImageTransform");
-        await this._scaleImageImpl(1, { saveHistory: false });
-        await this._rotateImageImpl(0, { saveHistory: false });
-        const after = this._captureCanvasStateOrThrow("resetImageTransform");
-        this._pushStateTransition(before, after);
+        try {
+          await this._scaleImageImpl(1, { saveHistory: false });
+          await this._rotateImageImpl(0, { saveHistory: false });
+          const after = this._captureCanvasStateOrThrow("resetImageTransform");
+          this._pushStateTransition(before, after);
+        } catch (error) {
+          try {
+            await this.loadFromState(before);
+          } catch (restoreError) {
+            this._reportError("resetImageTransform rollback failed", restoreError);
+          }
+          throw error;
+        }
       }).finally(() => {
         if (!this._disposed && this.canvas) this._updateUI();
       }).catch((error) => {
@@ -1776,7 +1975,13 @@
         try {
           const state = typeof serializedState === "string" ? JSON.parse(serializedState) : serializedState;
           const editorMetadata = state && state.imageEditorMetadata ? state.imageEditorMetadata : null;
-          this.canvas.loadFromJSON(state, async () => {
+          const restoredCanvasWidth = Number(editorMetadata && editorMetadata.canvasWidth);
+          const restoredCanvasHeight = Number(editorMetadata && editorMetadata.canvasHeight);
+          const hasRestoredCanvasSize = Number.isFinite(restoredCanvasWidth) && restoredCanvasWidth > 0 && Number.isFinite(restoredCanvasHeight) && restoredCanvasHeight > 0;
+          if (editorMetadata && Object.prototype.hasOwnProperty.call(editorMetadata, "version") && Number(editorMetadata.version) !== 1) {
+            this._reportWarning(`loadFromState: unsupported editor metadata version ${editorMetadata.version}`);
+          }
+          const finishLoad = async () => {
             try {
               if (this._disposed || !this.canvas) {
                 reject(new Error("Editor was disposed while loading state"));
@@ -1812,6 +2017,11 @@
                 this.currentScale = 1;
                 this.currentRotation = 0;
               }
+              if (hasRestoredCanvasSize) {
+                this._setCanvasSizeInt(restoredCanvasWidth, restoredCanvasHeight);
+              } else if (this.originalImage && this._shouldResizeCanvasToContentBounds()) {
+                this._updateCanvasSizeToImageBounds();
+              }
               const masks = canvasObjects.filter((object) => object.maskId);
               masks.forEach((mask) => {
                 this._restoreMaskControls(mask);
@@ -1839,6 +2049,9 @@
               this._reportError("loadFromState() failed", callbackError);
               reject(callbackError);
             }
+          };
+          this.canvas.loadFromJSON(state, () => {
+            void finishLoad();
           });
         } catch (error) {
           this._reportError("loadFromState() failed", error);
@@ -1854,12 +2067,12 @@
     }
     _waitForImageElementReady(imageElement) {
       if (!imageElement) return Promise.resolve();
-      if (imageElement.complete || imageElement.naturalWidth > 0 || imageElement.width > 0) return Promise.resolve();
+      const hasLoadedDimensions = (Number(imageElement.naturalWidth) > 0 || Number(imageElement.width) > 0) && (Number(imageElement.naturalHeight) > 0 || Number(imageElement.height) > 0);
+      if (hasLoadedDimensions) return Promise.resolve();
+      if (imageElement.complete) return Promise.reject(new Error("Image could not be loaded while restoring state"));
       return new Promise((resolve, reject) => {
         let isSettled = false;
-        const timerId = setTimeout(() => {
-          settle(() => reject(new Error("Image load timed out while restoring state")));
-        }, this._getSafeTimeoutMs(this.options.imageLoadTimeoutMs));
+        let timerId;
         const settle = (callback) => {
           if (isSettled) return;
           isSettled = true;
@@ -1873,8 +2086,20 @@
           }
           callback();
         };
-        const handleLoad = () => settle(resolve);
-        const handleError = (error) => settle(() => reject(error));
+        const handleLoad = () => {
+          const didLoad = (Number(imageElement.naturalWidth) > 0 || Number(imageElement.width) > 0) && (Number(imageElement.naturalHeight) > 0 || Number(imageElement.height) > 0);
+          settle(() => {
+            if (didLoad) {
+              resolve();
+            } else {
+              reject(new Error("Image could not be loaded while restoring state"));
+            }
+          });
+        };
+        const handleError = (error) => settle(() => reject(error instanceof Error ? error : new Error("Image could not be loaded while restoring state")));
+        timerId = setTimeout(() => {
+          settle(() => reject(new Error("Image load timed out while restoring state")));
+        }, this._getSafeTimeoutMs(this.options.imageLoadTimeoutMs));
         if (typeof imageElement.addEventListener === "function") {
           imageElement.addEventListener("load", handleLoad, { once: true });
           imageElement.addEventListener("error", handleError, { once: true });
@@ -1974,14 +2199,7 @@
     }
     _rebindMaskEvents(mask) {
       if (!mask) return;
-      if (mask.__imageEditorMaskHandlers) {
-        try {
-          mask.off("mouseover", mask.__imageEditorMaskHandlers.mouseover);
-          mask.off("mouseout", mask.__imageEditorMaskHandlers.mouseout);
-        } catch (error) {
-          void error;
-        }
-      }
+      this._cleanupMaskEvents(mask);
       const metadata = {};
       if (!Number.isFinite(Number(mask.originalAlpha))) {
         metadata.originalAlpha = Number.isFinite(Number(mask.opacity)) ? Number(mask.opacity) : 0.5;
@@ -2008,6 +2226,22 @@
       mask.on("mouseout", mouseout);
       mask.__imageEditorMaskHandlers = { mouseover, mouseout };
     }
+    _cleanupMaskEvents(mask) {
+      if (!mask || !mask.__imageEditorMaskHandlers) return;
+      try {
+        if (typeof mask.off === "function") {
+          mask.off("mouseover", mask.__imageEditorMaskHandlers.mouseover);
+          mask.off("mouseout", mask.__imageEditorMaskHandlers.mouseout);
+        }
+      } catch (error) {
+        this._reportWarning("Mask event cleanup failed", error);
+      }
+      try {
+        delete mask.__imageEditorMaskHandlers;
+      } catch (error) {
+        this._reportWarning("Mask event metadata cleanup failed", error);
+      }
+    }
     /**
      * Creates a mask and adds it to the canvas.
      *
@@ -2146,6 +2380,10 @@
             });
         }
       }
+      if (!mask || typeof mask.set !== "function" || typeof mask.setCoords !== "function") {
+        this._reportWarning("fabricGenerator returned an invalid Fabric object");
+        return null;
+      }
       const styles = maskConfig.styles || {};
       const hasStyle = (property) => Object.prototype.hasOwnProperty.call(styles, property);
       const maskSettings = {
@@ -2214,6 +2452,7 @@
       this.canvas.discardActiveObject();
       selectedMasks.forEach((mask) => {
         this._removeLabelForMask(mask);
+        this._cleanupMaskEvents(mask);
         this.canvas.remove(mask);
       });
       const masks = this.canvas.getObjects().filter((object) => object.maskId);
@@ -2238,7 +2477,10 @@
       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));
+      masks.forEach((mask) => {
+        this._cleanupMaskEvents(mask);
+        this.canvas.remove(mask);
+      });
       this.canvas.discardActiveObject();
       this._lastMask = null;
       this._lastMaskInitialLeft = null;
@@ -2273,6 +2515,93 @@
         }
       }
     }
+    _captureMaskLabelBackups(masks) {
+      if (!this.canvas) return [];
+      const canvasObjects = new Set(this.canvas.getObjects());
+      return (masks || []).map((mask) => {
+        const label = mask && mask.__label ? mask.__label : null;
+        return {
+          mask,
+          label,
+          hadLabel: !!label,
+          labelInCanvas: !!label && canvasObjects.has(label),
+          visible: label ? label.visible : void 0
+        };
+      });
+    }
+    _restoreMaskLabelBackups(labelBackups) {
+      if (!this.canvas || !Array.isArray(labelBackups)) return;
+      const canvasObjects = new Set(this.canvas.getObjects());
+      labelBackups.forEach((backup) => {
+        if (!backup || !backup.mask) return;
+        try {
+          if (!backup.hadLabel) {
+            if (backup.mask.__label) this._removeLabelForMask(backup.mask);
+            return;
+          }
+          backup.mask.__label = backup.label;
+          if (!backup.label) return;
+          if (backup.labelInCanvas && !canvasObjects.has(backup.label)) {
+            this.canvas.add(backup.label);
+            canvasObjects.add(backup.label);
+          }
+          if (backup.visible !== void 0) backup.label.set({ visible: backup.visible });
+          if (backup.labelInCanvas) this.canvas.bringToFront(backup.label);
+          this._syncMaskLabel(backup.mask);
+        } catch (error) {
+          this._reportWarning("restoreMaskLabelBackups: failed to restore mask label", error);
+        }
+      });
+    }
+    _captureActiveObjectBackup() {
+      if (!this.canvas) return null;
+      const activeObject = this.canvas.getActiveObject();
+      if (!activeObject) return null;
+      const selectedObjects = typeof activeObject.getObjects === "function" ? activeObject.getObjects() : [activeObject];
+      return { activeObject, selectedObjects };
+    }
+    _restoreActiveObjectBackup(activeObjectBackup) {
+      if (!this.canvas || !activeObjectBackup || !activeObjectBackup.activeObject) return;
+      const canvasObjects = this.canvas.getObjects();
+      const selectedObjects = Array.isArray(activeObjectBackup.selectedObjects) ? activeObjectBackup.selectedObjects : [];
+      const canRestore = selectedObjects.length ? selectedObjects.every((object) => canvasObjects.includes(object)) : canvasObjects.includes(activeObjectBackup.activeObject);
+      if (!canRestore) return;
+      try {
+        this.canvas.setActiveObject(activeObjectBackup.activeObject);
+      } catch (error) {
+        void error;
+      }
+    }
+    _captureMaskExportBackups(masks) {
+      return (masks || []).map((mask) => ({
+        object: mask,
+        visible: mask.visible,
+        opacity: mask.opacity,
+        fill: mask.fill,
+        strokeWidth: mask.strokeWidth,
+        stroke: mask.stroke,
+        selectable: mask.selectable,
+        lockRotation: mask.lockRotation
+      }));
+    }
+    _restoreMaskExportBackups(maskBackups) {
+      (maskBackups || []).forEach((backup) => {
+        try {
+          backup.object.set({
+            visible: backup.visible,
+            opacity: backup.opacity,
+            fill: backup.fill,
+            strokeWidth: backup.strokeWidth,
+            stroke: backup.stroke,
+            selectable: backup.selectable,
+            lockRotation: backup.lockRotation
+          });
+          backup.object.setCoords();
+        } catch (error) {
+          void error;
+        }
+      });
+    }
     /**
      * Returns a stable zero-based creation index for label callbacks.
      *
@@ -2345,10 +2674,13 @@
     _hideAllMaskLabels() {
       if (!this.canvas) return;
       const canvasObjects = this.canvas.getObjects();
+      const canvasObjectSet = new Set(canvasObjects);
       const labels = canvasObjects.filter((object) => object.maskLabel);
       labels.forEach((label) => {
         try {
-          if (canvasObjects.includes(label)) this.canvas.remove(label);
+          if (canvasObjectSet.has(label)) {
+            this.canvas.remove(label);
+          }
         } catch (error) {
           void error;
         }
@@ -2518,6 +2850,9 @@
           fileType: "png"
         }));
         this.removeAllMasks(this._withInternalOperationOptions(operationToken, { saveHistory: false }));
+        if (this.canvas.getObjects().some((object) => object.maskId)) {
+          throw new Error("Masks could not be removed during merge");
+        }
         await this.loadImage(merged, this._withInternalOperationOptions(operationToken, {
           preserveScroll: true,
           resetMaskCounter: false
@@ -2591,7 +2926,11 @@
       const format = this._normalizeImageFormat(options.fileType || options.format);
       if (!exportImageArea) {
         const masks2 = this.canvas.getObjects().filter((object) => object.maskId || object.maskLabel);
+        const editableMasks = this.canvas.getObjects().filter((object) => object.maskId);
         const maskVisibilityBackups = masks2.map((mask) => ({ object: mask, visible: mask.visible }));
+        const maskStyleBackups2 = this._captureMaskExportBackups(editableMasks);
+        const labelBackups2 = this._captureMaskLabelBackups(editableMasks);
+        const activeObjectBackup2 = this._captureActiveObjectBackup();
         try {
           masks2.forEach((mask) => {
             mask.set({ visible: false });
@@ -2616,20 +2955,16 @@
               void error;
             }
           });
+          this._restoreMaskExportBackups(maskStyleBackups2);
+          this._restoreMaskLabelBackups(labelBackups2);
+          this._restoreActiveObjectBackup(activeObjectBackup2);
           this.canvas.renderAll();
         }
       }
       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;
+      const maskStyleBackups = this._captureMaskExportBackups(masks);
+      const labelBackups = this._captureMaskLabelBackups(masks);
+      const activeObjectBackup = this._captureActiveObjectBackup();
       try {
         masks.forEach((mask) => this._removeLabelForMask(mask));
         this.canvas.discardActiveObject();
@@ -2642,7 +2977,7 @@
         this.originalImage.setCoords();
         const imageBounds = this.originalImage.getBoundingRect(true, true);
         const exportRegion = this._getClampedCanvasRegion(imageBounds);
-        finalBase64 = await this._exportCanvasRegionToDataURL({
+        return await this._exportCanvasRegionToDataURL({
           ...exportRegion,
           multiplier,
           quality,
@@ -2650,24 +2985,11 @@
           sealPartialEdges: this._getPartialExportEdges(imageBounds)
         });
       } finally {
-        maskStyleBackups.forEach((backup) => {
-          try {
-            backup.object.set({
-              opacity: backup.opacity,
-              fill: backup.fill,
-              strokeWidth: backup.strokeWidth,
-              stroke: backup.stroke,
-              selectable: backup.selectable,
-              lockRotation: backup.lockRotation
-            });
-            backup.object.setCoords();
-          } catch (error) {
-            void error;
-          }
-        });
+        this._restoreMaskExportBackups(maskStyleBackups);
+        this._restoreMaskLabelBackups(labelBackups);
+        this._restoreActiveObjectBackup(activeObjectBackup);
         this.canvas.renderAll();
       }
-      return finalBase64;
     }
     /**
      * Backward-compatible alias for {@link ImageEditor#exportImageBase64}.
@@ -2748,13 +3070,8 @@
           imageElement.src = imageBase64;
         });
       }
-      const binaryString = atob(imageDataUrl.split(",")[1]);
+      const bytes = this._decodeBase64Payload(imageDataUrl.split(",")[1]);
       const mime = `image/${safeFileType}`;
-      let byteIndex = binaryString.length;
-      const bytes = new Uint8Array(byteIndex);
-      while (byteIndex--) {
-        bytes[byteIndex] = binaryString.charCodeAt(byteIndex);
-      }
       return new File([bytes], fileName, { type: mime });
     }
     _clearMaskPlacementMemory() {
@@ -2799,22 +3116,21 @@
       this._cropPrevEvented = null;
     }
     _removeCropRect() {
-      if (!this._cropRect) return;
-      try {
-        if (this._cropHandlers && this._cropHandlers.length) {
-          this._cropHandlers.forEach((targetHandlers) => {
-            targetHandlers.handlers.forEach((handlerRecord) => {
+      if (this._cropHandlers && this._cropHandlers.length) {
+        this._cropHandlers.forEach((targetHandlers) => {
+          (targetHandlers.handlers || []).forEach((handlerRecord) => {
+            try {
               if (targetHandlers.target && typeof targetHandlers.target.off === "function") {
                 targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
               }
-            });
+            } catch (error) {
+              this._reportWarning("Crop handler cleanup failed", error);
+            }
           });
-        }
-      } catch (error) {
-        void error;
+        });
       }
       try {
-        if (this.canvas) this.canvas.remove(this._cropRect);
+        if (this.canvas && this._cropRect) this.canvas.remove(this._cropRect);
       } catch (error) {
         void error;
       }
@@ -2901,6 +3217,30 @@
           const nextScaleY = Math.min(maxCropHeight / cropHeight, Math.max(minCropHeight / cropHeight, Number(cropRect.scaleY) || 1));
           cropRect.set({ scaleX: nextScaleX, scaleY: nextScaleY });
           cropRect.setCoords();
+          const cropBounds = cropRect.getBoundingRect(true, true);
+          const imageLeft = Number(imageBounds.left) || 0;
+          const imageTop = Number(imageBounds.top) || 0;
+          const imageRight = imageLeft + (Number(imageBounds.width) || 0);
+          const imageBottom = imageTop + (Number(imageBounds.height) || 0);
+          let deltaX = 0;
+          let deltaY = 0;
+          if (cropBounds.left < imageLeft) {
+            deltaX = imageLeft - cropBounds.left;
+          } else if (cropBounds.left + cropBounds.width > imageRight) {
+            deltaX = imageRight - (cropBounds.left + cropBounds.width);
+          }
+          if (cropBounds.top < imageTop) {
+            deltaY = imageTop - cropBounds.top;
+          } else if (cropBounds.top + cropBounds.height > imageBottom) {
+            deltaY = imageBottom - (cropBounds.top + cropBounds.height);
+          }
+          if (deltaX || deltaY) {
+            cropRect.set({
+              left: (Number(cropRect.left) || 0) + deltaX,
+              top: (Number(cropRect.top) || 0) + deltaY
+            });
+            cropRect.setCoords();
+          }
           this.canvas.requestRenderAll();
         } catch (error) {
           void error;
@@ -2960,27 +3300,28 @@
       try {
         beforeJson = this._serializeCanvasState();
       } catch (error) {
-        this._reportWarning("applyCrop: could not serialize before state", error);
+        this._reportError("applyCrop: failed to capture rollback state", error);
         beforeJson = null;
       }
+      if (!beforeJson) {
+        this.cancelCrop();
+        return;
+      }
       const preservedMasks = [];
       try {
         const masks = this.canvas.getObjects().filter((object) => object.maskId);
         if (masks && masks.length) {
           masks.forEach((mask) => {
-            try {
-              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) {
-                this._translateObjectByCanvasOffset(mask, -cropRegion.sourceX, -cropRegion.sourceY);
-                mask.set({ visible: true });
-                preservedMasks.push(mask);
-              }
-            } catch (error) {
-              this._reportWarning("applyCrop: failed to remove mask", error);
+            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._cleanupMaskEvents(mask);
+            this.canvas.remove(mask);
+            if (shouldPreserveMasks && intersectsCrop) {
+              this._translateObjectByCanvasOffset(mask, -cropRegion.sourceX, -cropRegion.sourceY);
+              mask.set({ visible: true });
+              preservedMasks.push(mask);
             }
           });
           this._clearMaskPlacementMemory();
@@ -2988,7 +3329,8 @@
           this.canvas.renderAll();
         }
       } catch (error) {
-        this._reportWarning("applyCrop: error while removing masks", error);
+        await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: failed to prepare masks", error);
+        return;
       }
       this._removeCropRect();
       this._cropMode = false;
@@ -3045,7 +3387,7 @@
      * @private
      */
     _updateInputs() {
-      const scaleInputElement = this._getElement("scaleRate");
+      const scaleInputElement = this._getElement("scalePercentageInput");
       if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
     }
     /**
@@ -3064,12 +3406,12 @@
       const canUndo = this.historyManager?.canUndo();
       const canRedo = this.historyManager?.canRedo();
       const isInCropMode = !!this._cropMode;
-      const isBusy = this.isAnimating || this._isLoading || !!this._activeOperationToken || !!(this.animationQueue && this.animationQueue.isBusy());
+      const isBusy = this.isBusy();
       if (isInCropMode) {
         for (const key of Object.keys(this.elements || {})) {
           const element = this._getElement(key);
           if (!element) continue;
-          if (key === "applyCropBtn" || key === "cancelCropBtn") {
+          if (key === "applyCropButton" || key === "cancelCropButton" || key === "applyCropBtn" || key === "cancelCropBtn") {
             this._setDisabled(key, false);
           } else {
             this._setDisabled(key, true);
@@ -3077,28 +3419,32 @@
         }
         return;
       }
-      this._setDisabled("zoomInBtn", !hasImage || isBusy || this.currentScale >= this.options.maxScale);
-      this._setDisabled("zoomOutBtn", !hasImage || isBusy || this.currentScale <= this.options.minScale);
-      this._setDisabled("rotateLeftBtn", !hasImage || isBusy);
-      this._setDisabled("rotateRightBtn", !hasImage || isBusy);
-      this._setDisabled("addMaskBtn", !hasImage || isBusy);
-      this._setDisabled("removeMaskBtn", !hasSelectedMask || isBusy);
-      this._setDisabled("removeAllMasksBtn", !hasMasks || isBusy);
-      this._setDisabled("mergeBtn", !hasImage || !hasMasks || isBusy);
-      this._setDisabled("downloadBtn", !hasImage || isBusy);
-      this._setDisabled("resetBtn", !hasImage || isDefaultTransform || isBusy);
-      this._setDisabled("undoBtn", !hasImage || isBusy || !canUndo);
-      this._setDisabled("redoBtn", !hasImage || isBusy || !canRedo);
-      this._setDisabled("cropBtn", !hasImage || isBusy);
-      this._setDisabled("applyCropBtn", true);
-      this._setDisabled("cancelCropBtn", true);
+      this._setDisabled("zoomInButton", !hasImage || isBusy || this.currentScale >= this.options.maxScale);
+      this._setDisabled("zoomOutButton", !hasImage || isBusy || this.currentScale <= this.options.minScale);
+      this._setDisabled("rotateLeftButton", !hasImage || isBusy);
+      this._setDisabled("rotateRightButton", !hasImage || isBusy);
+      this._setDisabled("createMaskButton", !hasImage || isBusy);
+      this._setDisabled("removeSelectedMaskButton", !hasSelectedMask || isBusy);
+      this._setDisabled("removeAllMasksButton", !hasMasks || isBusy);
+      this._setDisabled("mergeMasksButton", !hasImage || !hasMasks || isBusy);
+      this._setDisabled("downloadImageButton", !hasImage || isBusy);
+      this._setDisabled("resetImageTransformButton", !hasImage || isDefaultTransform || isBusy);
+      this._setDisabled("undoButton", !hasImage || isBusy || !canUndo);
+      this._setDisabled("redoButton", !hasImage || isBusy || !canRedo);
+      this._setDisabled("enterCropModeButton", !hasImage || isBusy);
+      this._setDisabled("applyCropButton", true);
+      this._setDisabled("cancelCropButton", true);
+      this._setDisabled("scalePercentageInput", !hasImage || isBusy);
+      this._setDisabled("rotateLeftDegreesInput", !hasImage || isBusy);
+      this._setDisabled("rotateRightDegreesInput", !hasImage || isBusy);
+      this._setDisabled("maskList", !hasImage || isBusy);
       this._setDisabled("imageInput", isBusy);
       this._setDisabled("uploadArea", isBusy);
     }
     /**
      * Enables or disables a specific UI element (typically a button) by its key.
      * 
-     * @param {string} key - Key of the element in this.elements (e.g. 'zoomInBtn').
+     * @param {string} key - Key of the element in this.elements (e.g. 'zoomInButton').
      * @param {boolean} disabled - If true, disables the element; otherwise enables.
      * @private
      */
@@ -3222,14 +3568,7 @@
       } catch (error) {
         void error;
       }
-      if (this._cropRect) {
-        try {
-          this.canvas.remove(this._cropRect);
-        } catch (error) {
-          void error;
-        }
-        this._cropRect = null;
-      }
+      if (this._cropRect) this._removeCropRect();
       if (this.containerElement && this._containerOriginalOverflow) {
         try {
           this._restoreContainerOverflowState();
@@ -3252,11 +3591,19 @@
           this.canvasElement.style.display = this._canvasElementOriginalStyle.display;
           this.canvasElement.style.width = this._canvasElementOriginalStyle.width;
           this.canvasElement.style.height = this._canvasElementOriginalStyle.height;
+          this.canvasElement.style.maxWidth = this._canvasElementOriginalStyle.maxWidth;
         } catch (error) {
           void error;
         }
       }
       if (this.canvas) {
+        try {
+          this.canvas.getObjects().forEach((object) => {
+            if (object && object.maskId) this._cleanupMaskEvents(object);
+          });
+        } catch (error) {
+          void error;
+        }
         try {
           this.canvas.dispose();
         } catch (error) {
@@ -3353,7 +3700,7 @@
               task.reject(error);
             }
           } finally {
-            if (generation === this._generation && this.currentTask === task) this.currentTask = null;
+            if (this.currentTask === task) this.currentTask = null;
           }
         }
       } finally {
@@ -3406,9 +3753,9 @@
     execute(command) {
       const result = command.execute();
       if (result && typeof result.then === "function") {
-        return Promise.resolve(result).then(() => {
+        return this.enqueue(() => Promise.resolve(result).then(() => {
           this.push(command);
-        });
+        }));
       }
       this.push(command);
       return result;