@bensitu/image-editor 1.4.2 → 1.5.1

package/dist/image-editor.js

@@ -3,7 +3,7 @@
   /**
    * @file image-editor.js
    * @module image-editor
-   * @version 1.4.2
+   * @version 1.5.1
    * @author Ben Situ
    * @license MIT
    * @description Lightweight canvas-based image editor with masking/transform/export support.
@@ -75,6 +75,7 @@
         downsampleMimeType: null,
         imageLoadTimeoutMs: 3e4,
         exportMultiplier: 1,
+        maxExportPixels: 5e7,
         exportImageAreaByDefault: true,
         defaultMaskWidth: 50,
         defaultMaskHeight: 80,
@@ -144,7 +145,9 @@
       this._activeAnimationRejectors = /* @__PURE__ */ new Set();
       this._disposed = false;
       this._initialized = false;
-      this.onImageLoaded = typeof options.onImageLoaded === "function" ? options.onImageLoaded : null;
+      this._deprecatedElementKeyWarnings = /* @__PURE__ */ new Set();
+      this._cropRotationWarningEmitted = false;
+      this.onImageLoaded = typeof this.options.onImageLoaded === "function" ? this.options.onImageLoaded : null;
       this.animationQueue = new AnimationQueue();
       this.historyManager = new HistoryManager(this.maxHistorySize);
     }
@@ -190,10 +193,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,11 +207,17 @@
      * @example
      * editor.init({
      *   canvas: 'myFabricCanvasId',
-     *   downloadBtn: 'myDownloadButtonId'
+     *   downloadImageButton: 'myDownloadButtonId'
      * });
      */
     init(idMap = {}) {
-      if (!this._fabricLoaded) return;
+      if (!this._fabricLoaded) {
+        this._fabricLoaded = !!ensureFabric();
+        if (!this._fabricLoaded) {
+          this._reportError("fabric.js is not loaded. Please include fabric.js first. Initialization will be aborted.");
+          return;
+        }
+      }
       if (this._initialized || this.canvas) this.dispose();
       this._disposed = false;
       this._initialized = true;
@@ -225,29 +236,49 @@
         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"
+        uploadArea: null,
+        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();
@@ -255,11 +286,68 @@
       this._updateMaskList();
       this._updateUI();
       if (this.options.initialImageBase64) {
-        this.loadImage(this.options.initialImageBase64);
+        this.loadImage(this.options.initialImageBase64).catch((error) => this._reportError("initialImageBase64 could not be loaded", error));
       } else {
         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 +364,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 +391,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) {
@@ -394,13 +487,14 @@
       if (!this.containerElement || !this.containerElement.style) return;
       this._captureContainerOverflowState();
       const shouldPreserveScroll = options.preserveScroll === true;
-      if (this.options.coverImageToCanvas) {
+      const layoutMode = this._getImageLayoutMode();
+      if (layoutMode === "cover") {
         this.containerElement.style.overflow = "scroll";
         if (!shouldPreserveScroll) {
           this.containerElement.scrollLeft = 0;
           this.containerElement.scrollTop = 0;
         }
-      } else if (this.options.fitImageToCanvas) {
+      } else if (layoutMode === "fit") {
         this.containerElement.style.overflow = "auto";
         if (!shouldPreserveScroll) {
           this.containerElement.scrollLeft = 0;
@@ -448,20 +542,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 +563,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 +572,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));
     }
     /**
@@ -551,6 +645,12 @@
         `Only one image layout mode should be enabled. Active modes: ${activeModes.join(", ")}.`
       );
     }
+    _getImageLayoutMode() {
+      if (this.options.fitImageToCanvas) return "fit";
+      if (this.options.coverImageToCanvas) return "cover";
+      if (this.options.expandCanvasToImage) return "expand";
+      return "contain";
+    }
     /**
      * Loads a base64 data URL into the Fabric canvas as the base image.
      *
@@ -564,12 +664,16 @@
       if (!this._fabricLoaded) return;
       if (!this.canvas || this._disposed) return;
       if (!imageBase64 || typeof imageBase64 !== "string" || !imageBase64.startsWith("data:image/")) return;
+      options = options || {};
       this._assertIdleForOperation("loadImage", options);
-      this._isLoading = true;
-      this._updateUI();
-      this._warnOnImageLayoutOptionConflict();
-      const transaction = this._captureLoadImageTransaction();
+      const isNestedOperation = this._isOwnInternalOperation(options);
+      const operationToken = isNestedOperation ? this._getInternalOperationToken(options) : this._beginBusyOperation("loadImage");
+      let transaction = null;
       try {
+        this._isLoading = true;
+        this._updateUI();
+        this._warnOnImageLayoutOptionConflict();
+        transaction = this._captureLoadImageTransaction();
         const imageElement = await this._createImageElement(imageBase64);
         if (this._disposed || !this.canvas) throw new Error("Editor was disposed while loading image");
         let loadSource = imageBase64;
@@ -609,7 +713,8 @@
         const viewport = this._getContainerViewportSize();
         const minWidth = viewport.width;
         const minHeight = viewport.height;
-        if (this.options.fitImageToCanvas) {
+        const layoutMode = this._getImageLayoutMode();
+        if (layoutMode === "fit") {
           const canvasWidth = Math.max(1, minWidth - 1);
           const canvasHeight = Math.max(1, minHeight - 1);
           this._setCanvasSizeInt(canvasWidth, canvasHeight);
@@ -617,13 +722,13 @@
           fabricImage.set({ left: 0, top: 0 });
           fabricImage.scale(fitScale);
           this.baseImageScale = fabricImage.scaleX || 1;
-        } else if (this.options.coverImageToCanvas) {
+        } else if (layoutMode === "cover") {
           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) {
+        } else if (layoutMode === "expand") {
           const canvasWidth = Math.max(minWidth, Math.floor(imageWidth));
           const canvasHeight = Math.max(minHeight, Math.floor(imageHeight));
           this._setCanvasSizeInt(canvasWidth, canvasHeight);
@@ -652,14 +757,16 @@
         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);
+        await this._rollbackLoadImageTransaction(
+          transaction,
+          this._withInternalOperationOptions(operationToken)
+        );
         throw error;
       } finally {
         this._isLoading = false;
+        if (!isNestedOperation) this._endBusyOperation(operationToken);
         if (!this._disposed && this.canvas) this._updateUI();
       }
     }
@@ -707,7 +814,7 @@
           try {
             imageElement.src = "";
           } catch (error) {
-            void error;
+            this._reportWarning("Image timeout cleanup failed", error);
           }
         }, safeTimeoutMs);
         imageElement.onload = () => settle(() => resolve(imageElement));
@@ -772,32 +879,38 @@
         canvasVisibility: this._captureElementVisibility(this._getCanvasVisibilityElement())
       };
     }
-    async _rollbackLoadImageTransaction(transaction) {
+    async _rollbackLoadImageTransaction(transaction, options = {}) {
       if (!transaction || !this.canvas || this._disposed) return;
       let didRestoreCanvasState = false;
+      let didFailCanvasRestore = false;
       try {
         if (transaction.canvasState) {
-          await this.loadFromState(transaction.canvasState);
+          await this.loadFromState(transaction.canvasState, options);
           didRestoreCanvasState = true;
         }
       } 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) {
@@ -810,6 +923,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;
@@ -880,6 +1033,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);
@@ -981,9 +1135,9 @@
     }
     _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);
+        const safetyMargin2 = this._getScrollSafetyMargin();
+        const safeWidth = Math.max(1, viewport.width - safetyMargin2);
+        const safeHeight = Math.max(1, viewport.height - safetyMargin2);
         return {
           width: contentWidth > viewport.width + 0.5 ? this._ceilCanvasDimension(contentWidth) : safeWidth,
           height: contentHeight > viewport.height + 0.5 ? this._ceilCanvasDimension(contentHeight) : safeHeight,
@@ -1009,9 +1163,17 @@
       }
       effectiveWidth = Math.max(1, viewport.width - (hasVertical ? scrollbar.width : 0));
       effectiveHeight = Math.max(1, viewport.height - (hasHorizontal ? scrollbar.height : 0));
+      const safetyMargin = this._getScrollSafetyMargin();
+      const layoutMode = this._getImageLayoutMode();
+      const shouldReserveNoScrollbarMargin = layoutMode === "fit" || layoutMode === "cover";
+      const getNonOverflowAxisSize = (contentSize, effectiveSize, hasOppositeScrollbar) => {
+        const margin = hasOppositeScrollbar ? safetyMargin : shouldReserveNoScrollbarMargin ? 1 : 0;
+        const safeEffectiveSize = Math.max(1, effectiveSize - margin);
+        return contentSize <= safeEffectiveSize + 0.5 ? safeEffectiveSize : effectiveSize;
+      };
       return {
-        width: hasHorizontal ? this._ceilCanvasDimension(contentWidth) : effectiveWidth,
-        height: hasVertical ? this._ceilCanvasDimension(contentHeight) : effectiveHeight,
+        width: hasHorizontal ? this._ceilCanvasDimension(contentWidth) : getNonOverflowAxisSize(contentWidth, effectiveWidth, hasVertical),
+        height: hasVertical ? this._ceilCanvasDimension(contentHeight) : getNonOverflowAxisSize(contentHeight, effectiveHeight, hasHorizontal),
         viewportWidth: effectiveWidth,
         viewportHeight: effectiveHeight,
         hasHorizontal,
@@ -1133,6 +1295,45 @@
         });
       }
     }
+    _getSerializableStateObjects() {
+      if (!this.canvas) return [];
+      return this.canvas.getObjects().filter((object) => !object.isCropRect && !object.maskLabel);
+    }
+    _restoreHighPrecisionSerializedGeometry(serializedObjects) {
+      if (!Array.isArray(serializedObjects)) return;
+      const fabricObjects = this._getSerializableStateObjects();
+      const numericProperties = [
+        "left",
+        "top",
+        "width",
+        "height",
+        "scaleX",
+        "scaleY",
+        "angle",
+        "skewX",
+        "skewY",
+        "cropX",
+        "cropY",
+        "radius",
+        "rx",
+        "ry",
+        "strokeWidth"
+      ];
+      serializedObjects.forEach((serializedObject, index) => {
+        const fabricObject = fabricObjects[index];
+        if (!serializedObject || !fabricObject) return;
+        numericProperties.forEach((property) => {
+          const numericValue = Number(fabricObject[property]);
+          if (Number.isFinite(numericValue)) serializedObject[property] = numericValue;
+        });
+        if (Array.isArray(serializedObject.points) && Array.isArray(fabricObject.points)) {
+          serializedObject.points = fabricObject.points.map((point) => ({
+            x: Number.isFinite(Number(point && point.x)) ? Number(point.x) : 0,
+            y: Number.isFinite(Number(point && point.y)) ? Number(point.y) : 0
+          }));
+        }
+      });
+    }
     _restoreMaskControls(mask) {
       if (!mask) return;
       const cornerSize = Number(mask.cornerSize);
@@ -1152,7 +1353,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() {
@@ -1160,12 +1361,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() {
@@ -1174,6 +1379,7 @@
         const jsonObject = this.canvas.toJSON(this._getStateProperties());
         if (Array.isArray(jsonObject.objects)) {
           jsonObject.objects = jsonObject.objects.filter((object) => !object.isCropRect && !object.maskLabel);
+          this._restoreHighPrecisionSerializedGeometry(jsonObject.objects);
         }
         jsonObject.imageEditorMetadata = this._serializeEditorMetadata();
         return JSON.stringify(jsonObject);
@@ -1248,6 +1454,12 @@
       if (!Number.isFinite(numericValue)) return false;
       return Math.abs(numericValue - Math.round(numericValue)) > 0.01;
     }
+    _hasScaledImageEdge(axis) {
+      if (!this.originalImage) return false;
+      const scale = Number(axis === "y" ? this.originalImage.scaleY : this.originalImage.scaleX);
+      if (!Number.isFinite(scale)) return false;
+      return Math.abs(scale - 1) > 0.01;
+    }
     _getPartialExportEdges(bounds) {
       if (!bounds) return null;
       const angle = Math.abs((Number(this.originalImage && this.originalImage.angle) || 0) % 90);
@@ -1256,8 +1468,8 @@
       return {
         left: this._hasFractionalCanvasEdge(bounds.left),
         top: this._hasFractionalCanvasEdge(bounds.top),
-        right: this._hasFractionalCanvasEdge((Number(bounds.left) || 0) + (Number(bounds.width) || 0)),
-        bottom: this._hasFractionalCanvasEdge((Number(bounds.top) || 0) + (Number(bounds.height) || 0))
+        right: this._hasFractionalCanvasEdge((Number(bounds.left) || 0) + (Number(bounds.width) || 0)) || this._hasScaledImageEdge("x"),
+        bottom: this._hasFractionalCanvasEdge((Number(bounds.top) || 0) + (Number(bounds.height) || 0)) || this._hasScaledImageEdge("y")
       };
     }
     async _sealPartialTransparentEdges(dataUrl, edges) {
@@ -1317,7 +1529,8 @@
      * @private
      */
     async _exportCanvasRegionToDataURL({ sourceX, sourceY, sourceWidth, sourceHeight, multiplier = 1, quality = 0.92, format = "jpeg", sealPartialEdges = null }) {
-      const safeMultiplier = Math.max(1, Number(multiplier) || 1);
+      const safeMultiplier = this._getSafeExportMultiplier(multiplier);
+      this._assertExportPixelBudget(sourceWidth, sourceHeight, safeMultiplier);
       const safeFormat = this._normalizeImageFormat(format);
       const exportFormat = safeFormat === "jpeg" ? "png" : safeFormat;
       let regionDataUrl = this.canvas.toDataURL({
@@ -1333,6 +1546,25 @@
       if (safeFormat !== "jpeg") return regionDataUrl;
       return this._convertDataUrlToOpaqueJpeg(regionDataUrl, quality);
     }
+    _getSafeExportMultiplier(multiplier) {
+      const numericMultiplier = Number(multiplier);
+      if (!Number.isFinite(numericMultiplier) || numericMultiplier <= 0) {
+        throw new Error("Export multiplier must be a finite positive number");
+      }
+      return Math.max(1, numericMultiplier);
+    }
+    _assertExportPixelBudget(sourceWidth, sourceHeight, safeMultiplier) {
+      const width = Math.max(1, Math.ceil(Number(sourceWidth) || 1));
+      const height = Math.max(1, Math.ceil(Number(sourceHeight) || 1));
+      const outputWidth = Math.ceil(width * safeMultiplier);
+      const outputHeight = Math.ceil(height * safeMultiplier);
+      const outputPixels = outputWidth * outputHeight;
+      const configuredMaxPixels = Number(this.options.maxExportPixels);
+      const maxPixels = Number.isFinite(configuredMaxPixels) && configuredMaxPixels > 0 ? Math.floor(configuredMaxPixels) : 5e7;
+      if (outputPixels > maxPixels) {
+        throw new Error(`Export would create ${outputPixels} pixels, exceeding the configured maxExportPixels limit of ${maxPixels}`);
+      }
+    }
     async _convertDataUrlToOpaqueJpeg(dataUrl, quality = 0.92) {
       const imageElement = await this._createImageElement(dataUrl);
       const width = Math.max(1, imageElement.naturalWidth || imageElement.width || 1);
@@ -1377,6 +1609,7 @@
     }
     _decodeBase64Payload(base64Payload) {
       const payload = String(base64Payload || "");
+      if (!payload) throw new Error("Data URL base64 payload is empty");
       if (typeof atob === "function") {
         return Uint8Array.from(atob(payload), (char) => char.charCodeAt(0));
       }
@@ -1385,6 +1618,13 @@
       }
       throw new Error("Base64 decoding is unavailable");
     }
+    _decodeDataUrlPayload(dataUrl) {
+      const match = String(dataUrl || "").match(/^data:([^;,]+);base64,([A-Za-z0-9+/=]+)$/i);
+      if (!match || !match[2]) {
+        throw new Error("Export produced an invalid or empty base64 data URL");
+      }
+      return this._decodeBase64Payload(match[2]);
+    }
     /** 
      * Gets the top-left corner coordinates of the given object.
      * Used for geometry calculations (e.g., scale, rotate).
@@ -1494,24 +1734,49 @@
         const currentHeight = this.canvas.getHeight();
         let requiredWidth = currentWidth;
         let requiredHeight = currentHeight;
-        fabricObjects.forEach((fabricObject) => {
+        const layoutMode = this._getImageLayoutMode();
+        const usesScrollableFitBounds = layoutMode === "fit" || layoutMode === "cover";
+        let contentWidth = 0;
+        let contentHeight = 0;
+        const includeObjectBounds = (fabricObject, objectPadding = 0) => {
           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 right = Math.ceil(boundingRect.left + boundingRect.width + objectPadding);
+          const bottom = Math.ceil(boundingRect.top + boundingRect.height + objectPadding);
+          contentWidth = Math.max(contentWidth, right);
+          contentHeight = Math.max(contentHeight, bottom);
+          return { right, bottom };
+        };
+        fabricObjects.forEach((fabricObject) => {
+          const bounds = includeObjectBounds(fabricObject, padding);
+          if (!bounds) return;
+          requiredWidth = Math.max(requiredWidth, bounds.right);
+          requiredHeight = Math.max(requiredHeight, bounds.bottom);
         });
-        const shouldUseScrollSafeViewport = this.options.fitImageToCanvas || this.options.coverImageToCanvas;
+        if (usesScrollableFitBounds) {
+          if (this.originalImage) includeObjectBounds(this.originalImage, 0);
+          this.canvas.getObjects().forEach((object) => {
+            if (object && object.maskId) includeObjectBounds(object, padding);
+          });
+          const contentSize = this._getScrollableCanvasSize(
+            Math.max(1, contentWidth),
+            Math.max(1, contentHeight)
+          );
+          const newWidth2 = contentSize.hasHorizontal ? Math.max(currentWidth, contentSize.width) : contentSize.width;
+          const newHeight2 = contentSize.hasVertical ? Math.max(currentHeight, contentSize.height) : contentSize.height;
+          if (newWidth2 !== currentWidth || newHeight2 !== currentHeight) {
+            this._setCanvasSizeInt(newWidth2, newHeight2);
+          }
+          return;
+        }
         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);
@@ -1522,16 +1787,60 @@
         this._reportWarning("expandCanvasToFitObjects: failed to expand canvas", error);
       }
     }
-    /**
-     * 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);
+    _captureImageDisplayBounds() {
+      if (!this.originalImage || !this.canvas) return null;
+      this.originalImage.setCoords();
+      const bounds = this.originalImage.getBoundingRect(true, true);
+      const width = Number(bounds && bounds.width);
+      const height = Number(bounds && bounds.height);
+      if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) return null;
+      return {
+        left: Number.isFinite(Number(bounds.left)) ? Number(bounds.left) : 0,
+        top: Number.isFinite(Number(bounds.top)) ? Number(bounds.top) : 0,
+        width,
+        height
+      };
+    }
+    _restoreImageDisplayBounds(displayBounds) {
+      if (!displayBounds || !this.originalImage || !this.canvas) return;
+      const imageWidth = Number(this.originalImage.width);
+      const imageHeight = Number(this.originalImage.height);
+      if (!Number.isFinite(imageWidth) || imageWidth <= 0 || !Number.isFinite(imageHeight) || imageHeight <= 0) return;
+      const scaleX = Number(displayBounds.width) / imageWidth;
+      const scaleY = Number(displayBounds.height) / imageHeight;
+      if (!Number.isFinite(scaleX) || scaleX <= 0 || !Number.isFinite(scaleY) || scaleY <= 0) return;
+      const left = Number(displayBounds.left) || 0;
+      const top = Number(displayBounds.top) || 0;
+      const requiredCanvasWidth = Math.max(1, Math.ceil(left + Number(displayBounds.width)));
+      const requiredCanvasHeight = Math.max(1, Math.ceil(top + Number(displayBounds.height)));
+      const currentCanvasWidth = Math.max(1, Math.round(Number(this.canvas.getWidth()) || 1));
+      const currentCanvasHeight = Math.max(1, Math.round(Number(this.canvas.getHeight()) || 1));
+      const layoutMode = this._getImageLayoutMode();
+      if (layoutMode === "fit" || layoutMode === "cover") {
+        const contentSize = this._getScrollableCanvasSize(requiredCanvasWidth, requiredCanvasHeight);
+        if (contentSize.width !== currentCanvasWidth || contentSize.height !== currentCanvasHeight) {
+          this._setCanvasSizeInt(contentSize.width, contentSize.height);
+        }
+      } else if (requiredCanvasWidth > currentCanvasWidth || requiredCanvasHeight > currentCanvasHeight) {
+        this._setCanvasSizeInt(
+          Math.max(currentCanvasWidth, requiredCanvasWidth),
+          Math.max(currentCanvasHeight, requiredCanvasHeight)
+        );
+      }
+      this.originalImage.set({
+        originX: "left",
+        originY: "top",
+        left,
+        top,
+        scaleX,
+        scaleY
+      });
+      this.originalImage.setCoords();
+      this.baseImageScale = scaleX;
+      this.currentScale = 1;
+      this.currentRotation = Number(this.originalImage.angle) || 0;
+      this._updateInputs();
+      this.canvas.renderAll();
     }
     /** 
      * Scales the original image by a given factor, with animation.
@@ -1546,7 +1855,14 @@
       } catch (error) {
         return Promise.reject(error);
       }
-      return this.animationQueue.add(() => this._scaleImageImpl(factor, options)).finally(() => {
+      return this.animationQueue.add(async () => {
+        const operationToken = this._beginBusyOperation("scaleImage");
+        try {
+          await this._scaleImageImpl(factor, this._withInternalOperationOptions(operationToken, options));
+        } finally {
+          this._endBusyOperation(operationToken);
+        }
+      }).finally(() => {
         if (!this._disposed && this.canvas) this._updateUI();
       });
     }
@@ -1580,10 +1896,16 @@
     _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.isAnimating || this.animationQueue && this.animationQueue.isBusy()) {
+      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()) && !isOwnInternalOperation) {
         throw new Error(`${operationName} cannot run while an animation is running`);
       }
       if (this._isLoading && !isOwnInternalOperation) {
@@ -1595,10 +1917,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`);
       }
     }
@@ -1692,7 +2018,7 @@
           if (object.maskId) this._syncMaskLabel(object);
         });
         this._updateInputs();
-        if (saveHistory) this.saveState();
+        if (saveHistory) this.saveState(options);
       } finally {
         if (didStartAnimation) {
           this.isAnimating = false;
@@ -1714,7 +2040,14 @@
       } catch (error) {
         return Promise.reject(error);
       }
-      return this.animationQueue.add(() => this._rotateImageImpl(degrees, options)).finally(() => {
+      return this.animationQueue.add(async () => {
+        const operationToken = this._beginBusyOperation("rotateImage");
+        try {
+          await this._rotateImageImpl(degrees, this._withInternalOperationOptions(operationToken, options));
+        } finally {
+          this._endBusyOperation(operationToken);
+        }
+      }).finally(() => {
         if (!this._disposed && this.canvas) this._updateUI();
       });
     }
@@ -1757,7 +2090,7 @@
           if (object.maskId) this._syncMaskLabel(object);
         });
         this._updateInputs();
-        if (saveHistory) this.saveState();
+        if (saveHistory) this.saveState(options);
         didCompleteRotation = true;
       } finally {
         if (!didCompleteRotation && !this._disposed && image) {
@@ -1784,11 +2117,23 @@
         return Promise.reject(error);
       }
       return this.animationQueue.add(async () => {
+        const operationToken = this._beginBusyOperation("resetImageTransform");
         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, this._withInternalOperationOptions(operationToken, { saveHistory: false }));
+          await this._rotateImageImpl(0, this._withInternalOperationOptions(operationToken, { saveHistory: false }));
+          const after = this._captureCanvasStateOrThrow("resetImageTransform");
+          this._pushStateTransition(before, after);
+        } catch (error) {
+          try {
+            await this.loadFromState(before, this._withInternalOperationOptions(operationToken));
+          } catch (restoreError) {
+            this._reportError("resetImageTransform rollback failed", restoreError);
+          }
+          throw error;
+        } finally {
+          this._endBusyOperation(operationToken);
+        }
       }).finally(() => {
         if (!this._disposed && this.canvas) this._updateUI();
       }).catch((error) => {
@@ -1812,8 +2157,13 @@
      * @returns {Promise<void>} Resolves after Fabric has loaded the state and UI state has been refreshed.
      * @public
      */
-    loadFromState(serializedState) {
+    loadFromState(serializedState, options = {}) {
       if (!serializedState || !this.canvas || this._disposed) return Promise.resolve();
+      try {
+        this._assertIdleForOperation("loadFromState", options);
+      } catch (error) {
+        return Promise.reject(error);
+      }
       if (this._cropMode || this._cropRect) {
         this._removeCropRect();
         this._restoreCropObjectState();
@@ -1827,10 +2177,13 @@
         try {
           const state = typeof serializedState === "string" ? JSON.parse(serializedState) : serializedState;
           const editorMetadata = state && state.imageEditorMetadata ? state.imageEditorMetadata : null;
+          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}`);
           }
-          this.canvas.loadFromJSON(state, async () => {
+          const finishLoad = async () => {
             try {
               if (this._disposed || !this.canvas) {
                 reject(new Error("Editor was disposed while loading state"));
@@ -1866,6 +2219,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);
@@ -1893,6 +2251,9 @@
               this._reportError("loadFromState() failed", callbackError);
               reject(callbackError);
             }
+          };
+          this.canvas.loadFromJSON(state, () => {
+            void finishLoad();
           });
         } catch (error) {
           this._reportError("loadFromState() failed", error);
@@ -1959,22 +2320,29 @@
      * @returns {void}
      * @public
      */
-    saveState() {
+    saveState(options = {}) {
       if (!this.canvas) return;
+      try {
+        this._assertIdleForOperation("saveState", options);
+      } catch (error) {
+        this._reportError("saveState blocked", error);
+        this._updateUI();
+        return;
+      }
       try {
         const after = this._captureCanvasStateOrThrow("saveState");
         const before = this._lastSnapshot || after;
         if (after === before) return;
         let executedOnce = false;
         const command = new Command(
-          () => {
+          (commandOptions = {}) => {
             if (executedOnce) {
-              return this.loadFromState(after);
+              return this.loadFromState(after, commandOptions);
             }
             executedOnce = true;
             return void 0;
           },
-          () => this.loadFromState(before)
+          (commandOptions = {}) => this.loadFromState(before, commandOptions)
         );
         this.historyManager.execute(command);
         this._lastSnapshot = after;
@@ -2003,8 +2371,8 @@
       if (before === after) return;
       if (!this.historyManager) this.historyManager = new HistoryManager(this.maxHistorySize || 50);
       const command = new Command(
-        () => this.loadFromState(after),
-        () => this.loadFromState(before)
+        (commandOptions = {}) => this.loadFromState(after, commandOptions),
+        (commandOptions = {}) => this.loadFromState(before, commandOptions)
       );
       this.historyManager.push(command);
       this._lastSnapshot = after;
@@ -2017,8 +2385,16 @@
      * @public
      */
     undo() {
-      return this.historyManager.undo().then(() => {
+      try {
+        this._assertIdleForOperation("undo");
+      } catch (error) {
+        return Promise.reject(error);
+      }
+      const operationToken = this._beginBusyOperation("undo");
+      return this.historyManager.undo(this._withInternalOperationOptions(operationToken)).then(() => {
         this._updateUI();
+      }).finally(() => {
+        this._endBusyOperation(operationToken);
       }).catch((error) => {
         this._reportError("undo failed", error);
         throw error;
@@ -2031,8 +2407,16 @@
      * @public
      */
     redo() {
-      return this.historyManager.redo().then(() => {
+      try {
+        this._assertIdleForOperation("redo");
+      } catch (error) {
+        return Promise.reject(error);
+      }
+      const operationToken = this._beginBusyOperation("redo");
+      return this.historyManager.redo(this._withInternalOperationOptions(operationToken)).then(() => {
         this._updateUI();
+      }).finally(() => {
+        this._endBusyOperation(operationToken);
       }).catch((error) => {
         this._reportError("redo failed", error);
         throw error;
@@ -2040,14 +2424,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;
@@ -2074,6 +2451,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.
      *
@@ -2139,18 +2532,43 @@
         }
         return value != null ? value : fallback;
       };
-      if (maskConfig.left === void 0 && this._lastMask) {
-        const previousMask = this._lastMask;
-        if (typeof previousMask.setCoords === "function") previousMask.setCoords();
-        const previousBounds = typeof previousMask.getBoundingRect === "function" ? previousMask.getBoundingRect(true, true) : { left: previousMask.left || firstOffset, top: previousMask.top || firstOffset, width: previousMask.width || 0 };
-        left = Math.round(previousBounds.left + previousBounds.width + maskConfig.gap);
-        top = Math.round(previousBounds.top ?? firstOffset);
-      } else {
-        left = resolveValue(maskConfig.left, firstOffset, "width");
-        top = resolveValue(maskConfig.top, firstOffset, "height");
+      const rejectInvalidMask = (message, error = null) => {
+        this._reportWarning(`createMask: ${message}`, error);
+        return null;
+      };
+      const resolveNumber = (value, fallback, axis, fieldName, constraints = {}) => {
+        const resolvedValue = resolveValue(value, fallback, axis);
+        const numericValue = Number(resolvedValue);
+        if (!Number.isFinite(numericValue)) {
+          throw new Error(`${fieldName} must be a finite number`);
+        }
+        if (constraints.positive && numericValue <= 0) {
+          throw new Error(`${fieldName} must be greater than 0`);
+        }
+        if (constraints.nonNegative && numericValue < 0) {
+          throw new Error(`${fieldName} must be 0 or greater`);
+        }
+        return numericValue;
+      };
+      try {
+        maskConfig.gap = resolveNumber(maskConfig.gap, 5, "width", "gap", { nonNegative: true });
+        maskConfig.width = resolveNumber(maskConfig.width, this.options.defaultMaskWidth, "width", "width", { positive: true });
+        maskConfig.height = resolveNumber(maskConfig.height, this.options.defaultMaskHeight, "height", "height", { positive: true });
+        maskConfig.angle = resolveNumber(maskConfig.angle, 0, "width", "angle");
+        maskConfig.alpha = Math.max(0, Math.min(1, resolveNumber(maskConfig.alpha, 0.5, "width", "alpha")));
+        if (maskConfig.left === void 0 && this._lastMask) {
+          const previousMask = this._lastMask;
+          if (typeof previousMask.setCoords === "function") previousMask.setCoords();
+          const previousBounds = typeof previousMask.getBoundingRect === "function" ? previousMask.getBoundingRect(true, true) : { left: previousMask.left || firstOffset, top: previousMask.top || firstOffset, width: previousMask.width || 0 };
+          left = Math.round(previousBounds.left + previousBounds.width + maskConfig.gap);
+          top = Math.round(previousBounds.top ?? firstOffset);
+        } else {
+          left = resolveNumber(maskConfig.left, firstOffset, "width", "left");
+          top = resolveNumber(maskConfig.top, firstOffset, "height", "top");
+        }
+      } catch (error) {
+        return rejectInvalidMask("invalid numeric configuration", error);
       }
-      maskConfig.width = resolveValue(maskConfig.width, this.options.defaultMaskWidth, "width");
-      maskConfig.height = resolveValue(maskConfig.height, this.options.defaultMaskHeight, "height");
       maskConfig.left = left;
       maskConfig.top = top;
       let mask;
@@ -2159,10 +2577,15 @@
       } else {
         switch (shapeType) {
           case "circle":
+            try {
+              maskConfig.radius = resolveNumber(maskConfig.radius, Math.min(maskConfig.width, maskConfig.height) / 2, "min", "radius", { positive: true });
+            } catch (error) {
+              return rejectInvalidMask("invalid circle radius", error);
+            }
             mask = new fabric.Circle({
               left,
               top,
-              radius: resolveValue(maskConfig.radius, Math.min(maskConfig.width, maskConfig.height) / 2, "min"),
+              radius: maskConfig.radius,
               fill: maskConfig.color,
               opacity: maskConfig.alpha,
               angle: maskConfig.angle,
@@ -2170,11 +2593,17 @@
             });
             break;
           case "ellipse":
+            try {
+              maskConfig.rx = resolveNumber(maskConfig.rx, maskConfig.width / 2, "width", "rx", { positive: true });
+              maskConfig.ry = resolveNumber(maskConfig.ry, maskConfig.height / 2, "height", "ry", { positive: true });
+            } catch (error) {
+              return rejectInvalidMask("invalid ellipse radius", error);
+            }
             mask = new fabric.Ellipse({
               left,
               top,
-              rx: resolveValue(maskConfig.rx, maskConfig.width / 2, "width"),
-              ry: resolveValue(maskConfig.ry, maskConfig.height / 2, "height"),
+              rx: maskConfig.rx,
+              ry: maskConfig.ry,
               fill: maskConfig.color,
               opacity: maskConfig.alpha,
               angle: maskConfig.angle,
@@ -2183,8 +2612,20 @@
             break;
           case "polygon": {
             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) });
+            if (!Array.isArray(polygonPoints) || polygonPoints.length < 3) {
+              return rejectInvalidMask("polygon masks require at least three points");
+            }
+            try {
+              polygonPoints = polygonPoints.map((point) => {
+                const x = Number(Array.isArray(point) ? point[0] : point.x);
+                const y = Number(Array.isArray(point) ? point[1] : point.y);
+                if (!Number.isFinite(x) || !Number.isFinite(y)) {
+                  throw new Error("polygon point coordinates must be finite numbers");
+                }
+                return { x, y };
+              });
+            } catch (error) {
+              return rejectInvalidMask("invalid polygon points", error);
             }
             mask = new fabric.Polygon(polygonPoints, {
               left,
@@ -2198,11 +2639,17 @@
           }
           case "rect":
           default:
+            try {
+              if (maskConfig.rx != null) maskConfig.rx = resolveNumber(maskConfig.rx, 0, "width", "rx", { nonNegative: true });
+              if (maskConfig.ry != null) maskConfig.ry = resolveNumber(maskConfig.ry, 0, "height", "ry", { nonNegative: true });
+            } catch (error) {
+              return rejectInvalidMask("invalid rectangle corner radius", error);
+            }
             mask = new fabric.Rect({
               left,
               top,
-              width: resolveValue(maskConfig.width, this.options.defaultMaskWidth, "width"),
-              height: resolveValue(maskConfig.height, this.options.defaultMaskHeight, "height"),
+              width: maskConfig.width,
+              height: maskConfig.height,
               fill: maskConfig.color,
               opacity: maskConfig.alpha,
               angle: maskConfig.angle,
@@ -2240,10 +2687,10 @@
         originalStrokeWidth: Number.isFinite(Number(mask.strokeWidth)) ? Number(mask.strokeWidth) : 1
       });
       this._rebindMaskEvents(mask);
-      this._expandCanvasToFitObject(mask);
+      this._expandCanvasToFitObjects([mask]);
       this._lastMaskInitialLeft = left;
       this._lastMaskInitialTop = top;
-      this._lastMaskInitialWidth = resolveValue(maskConfig.width, this.options.defaultMaskWidth, "width");
+      this._lastMaskInitialWidth = maskConfig.width;
       const maskId = ++this.maskCounter;
       mask.set({
         maskId,
@@ -2284,6 +2731,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);
@@ -2308,7 +2756,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;
@@ -2377,7 +2828,7 @@
           if (backup.labelInCanvas) this.canvas.bringToFront(backup.label);
           this._syncMaskLabel(backup.mask);
         } catch (error) {
-          void error;
+          this._reportWarning("restoreMaskLabelBackups: failed to restore mask label", error);
         }
       });
     }
@@ -2508,7 +2959,6 @@
         try {
           if (canvasObjectSet.has(label)) {
             this.canvas.remove(label);
-            canvasObjectSet.delete(label);
           }
         } catch (error) {
           void error;
@@ -2668,6 +3118,7 @@
       this._assertIdleForOperation("mergeMasks");
       const masks = this.canvas.getObjects().filter((object) => object.maskId);
       if (!masks.length) return;
+      const beforeImageDisplayBounds = this._captureImageDisplayBounds();
       const beforeJson = this._serializeCanvasState();
       const operationToken = this._beginBusyOperation("mergeMasks");
       this.canvas.discardActiveObject();
@@ -2686,12 +3137,13 @@
           preserveScroll: true,
           resetMaskCounter: false
         }));
+        this._restoreImageDisplayBounds(beforeImageDisplayBounds);
         const afterJson = this._serializeCanvasState();
         this._pushStateTransition(beforeJson, afterJson);
       } catch (error) {
         this._reportError("merge error", error);
         try {
-          await this.loadFromState(beforeJson);
+          await this.loadFromState(beforeJson, this._withInternalOperationOptions(operationToken));
         } catch (restoreError) {
           this._reportError("mergeMasks rollback failed", restoreError);
         }
@@ -2748,24 +3200,65 @@
      */
     async exportImageBase64(options = {}) {
       if (!this.originalImage) throw new Error("No image loaded");
+      options = options || {};
       this._assertIdleForOperation("exportImageBase64", options);
+      const isNestedOperation = this._isOwnInternalOperation(options);
+      const operationToken = isNestedOperation ? this._getInternalOperationToken(options) : this._beginBusyOperation("exportImageBase64");
       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 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 {
+        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 });
+            });
+            this.canvas.discardActiveObject();
+            this.canvas.renderAll();
+            this.originalImage.setCoords();
+            const imageBounds = this.originalImage.getBoundingRect(true, true);
+            const exportRegion = this._getClampedCanvasRegion(imageBounds);
+            return await this._exportCanvasRegionToDataURL({
+              ...exportRegion,
+              multiplier,
+              quality,
+              format,
+              sealPartialEdges: this._getPartialExportEdges(imageBounds)
+            });
+          } finally {
+            maskVisibilityBackups.forEach((backup) => {
+              try {
+                backup.object.set({ visible: backup.visible });
+              } catch (error) {
+                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 = this._captureMaskExportBackups(masks);
+        const labelBackups = this._captureMaskLabelBackups(masks);
+        const activeObjectBackup = this._captureActiveObjectBackup();
         try {
-          masks2.forEach((mask) => {
-            mask.set({ visible: false });
-          });
+          masks.forEach((mask) => this._removeLabelForMask(mask));
           this.canvas.discardActiveObject();
           this.canvas.renderAll();
+          masks.forEach((mask) => {
+            mask.set({ opacity: 1, fill: "#000000", strokeWidth: 0, stroke: null, selectable: false });
+            mask.setCoords();
+          });
+          this.canvas.renderAll();
           this.originalImage.setCoords();
           const imageBounds = this.originalImage.getBoundingRect(true, true);
           const exportRegion = this._getClampedCanvasRegion(imageBounds);
@@ -2777,50 +3270,14 @@
             sealPartialEdges: this._getPartialExportEdges(imageBounds)
           });
         } finally {
-          maskVisibilityBackups.forEach((backup) => {
-            try {
-              backup.object.set({ visible: backup.visible });
-            } catch (error) {
-              void error;
-            }
-          });
-          this._restoreMaskExportBackups(maskStyleBackups2);
-          this._restoreMaskLabelBackups(labelBackups2);
-          this._restoreActiveObjectBackup(activeObjectBackup2);
+          this._restoreMaskExportBackups(maskStyleBackups);
+          this._restoreMaskLabelBackups(labelBackups);
+          this._restoreActiveObjectBackup(activeObjectBackup);
           this.canvas.renderAll();
         }
-      }
-      const masks = this.canvas.getObjects().filter((object) => object.maskId);
-      const maskStyleBackups = this._captureMaskExportBackups(masks);
-      const labelBackups = this._captureMaskLabelBackups(masks);
-      const activeObjectBackup = this._captureActiveObjectBackup();
-      let finalBase64;
-      try {
-        masks.forEach((mask) => this._removeLabelForMask(mask));
-        this.canvas.discardActiveObject();
-        this.canvas.renderAll();
-        masks.forEach((mask) => {
-          mask.set({ opacity: 1, fill: "#000000", strokeWidth: 0, stroke: null, selectable: false });
-          mask.setCoords();
-        });
-        this.canvas.renderAll();
-        this.originalImage.setCoords();
-        const imageBounds = this.originalImage.getBoundingRect(true, true);
-        const exportRegion = this._getClampedCanvasRegion(imageBounds);
-        finalBase64 = await this._exportCanvasRegionToDataURL({
-          ...exportRegion,
-          multiplier,
-          quality,
-          format,
-          sealPartialEdges: this._getPartialExportEdges(imageBounds)
-        });
       } finally {
-        this._restoreMaskExportBackups(maskStyleBackups);
-        this._restoreMaskLabelBackups(labelBackups);
-        this._restoreActiveObjectBackup(activeObjectBackup);
-        this.canvas.renderAll();
+        if (!isNestedOperation) this._endBusyOperation(operationToken);
       }
-      return finalBase64;
     }
     /**
      * Backward-compatible alias for {@link ImageEditor#exportImageBase64}.
@@ -2852,7 +3309,10 @@
      */
     async exportImageFile(options = {}) {
       if (!this.originalImage) throw new Error("No image loaded");
-      this._assertIdleForOperation("exportImageFile");
+      options = options || {};
+      this._assertIdleForOperation("exportImageFile", options);
+      const isNestedOperation = this._isOwnInternalOperation(options);
+      const operationToken = isNestedOperation ? this._getInternalOperationToken(options) : this._beginBusyOperation("exportImageFile");
       const {
         mergeMask = true,
         fileType = "jpeg",
@@ -2862,48 +3322,52 @@
       } = options;
       const safeFileType = this._normalizeImageFormat(fileType);
       const normalizedQuality = this._normalizeQuality(quality);
-      let imageBase64;
-      if (mergeMask) {
-        imageBase64 = await this.exportImageBase64({
-          exportImageArea: true,
-          multiplier,
-          quality: normalizedQuality,
-          fileType: safeFileType
-        });
-      } else {
-        imageBase64 = await this.exportImageBase64({
-          exportImageArea: false,
-          multiplier,
-          quality: normalizedQuality,
-          fileType: safeFileType
-        });
-      }
-      let imageDataUrl = imageBase64;
-      if (!imageDataUrl.startsWith(`data:image/${safeFileType}`)) {
-        imageDataUrl = await new Promise((resolve, reject) => {
-          const imageElement = new window.Image();
-          imageElement.crossOrigin = "Anonymous";
-          imageElement.onload = () => {
-            try {
-              const offscreenCanvas = document.createElement("canvas");
-              offscreenCanvas.width = imageElement.width;
-              offscreenCanvas.height = imageElement.height;
-              const context = offscreenCanvas.getContext("2d");
-              if (!context) throw new Error("Unable to create 2D canvas context for export conversion");
-              context.drawImage(imageElement, 0, 0);
-              const convertedDataUrl = offscreenCanvas.toDataURL(`image/${safeFileType}`, normalizedQuality);
-              resolve(convertedDataUrl);
-            } catch (error) {
-              reject(error);
-            }
-          };
-          imageElement.onerror = reject;
-          imageElement.src = imageBase64;
-        });
+      try {
+        let imageBase64;
+        if (mergeMask) {
+          imageBase64 = await this.exportImageBase64(this._withInternalOperationOptions(operationToken, {
+            exportImageArea: true,
+            multiplier,
+            quality: normalizedQuality,
+            fileType: safeFileType
+          }));
+        } else {
+          imageBase64 = await this.exportImageBase64(this._withInternalOperationOptions(operationToken, {
+            exportImageArea: false,
+            multiplier,
+            quality: normalizedQuality,
+            fileType: safeFileType
+          }));
+        }
+        let imageDataUrl = imageBase64;
+        if (!imageDataUrl.startsWith(`data:image/${safeFileType}`)) {
+          imageDataUrl = await new Promise((resolve, reject) => {
+            const imageElement = new window.Image();
+            imageElement.crossOrigin = "Anonymous";
+            imageElement.onload = () => {
+              try {
+                const offscreenCanvas = document.createElement("canvas");
+                offscreenCanvas.width = imageElement.width;
+                offscreenCanvas.height = imageElement.height;
+                const context = offscreenCanvas.getContext("2d");
+                if (!context) throw new Error("Unable to create 2D canvas context for export conversion");
+                context.drawImage(imageElement, 0, 0);
+                const convertedDataUrl = offscreenCanvas.toDataURL(`image/${safeFileType}`, normalizedQuality);
+                resolve(convertedDataUrl);
+              } catch (error) {
+                reject(error);
+              }
+            };
+            imageElement.onerror = reject;
+            imageElement.src = imageBase64;
+          });
+        }
+        const bytes = this._decodeDataUrlPayload(imageDataUrl);
+        const mime = `image/${safeFileType}`;
+        return new File([bytes], fileName, { type: mime });
+      } finally {
+        if (!isNestedOperation) this._endBusyOperation(operationToken);
       }
-      const bytes = this._decodeBase64Payload(imageDataUrl.split(",")[1]);
-      const mime = `image/${safeFileType}`;
-      return new File([bytes], fileName, { type: mime });
     }
     _clearMaskPlacementMemory() {
       this._lastMask = null;
@@ -2911,7 +3375,7 @@
       this._lastMaskInitialTop = null;
       this._lastMaskInitialWidth = null;
     }
-    async _restoreStateAfterCropFailure(beforeJson, message, error) {
+    async _restoreStateAfterCropFailure(beforeJson, message, error, options = {}) {
       this._reportError(message, error);
       if (this._cropRect && this.canvas) this._removeCropRect();
       this._cropRect = null;
@@ -2922,7 +3386,7 @@
       this._prevSelectionSetting = void 0;
       if (beforeJson) {
         try {
-          await this.loadFromState(beforeJson);
+          await this.loadFromState(beforeJson, options);
         } catch (restoreError) {
           this._reportError("applyCrop: rollback failed", restoreError);
         }
@@ -2947,28 +3411,38 @@
       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;
       }
       this._cropRect = null;
       this._cropHandlers = [];
     }
+    _getCropRectContentBounds(cropRect) {
+      if (!cropRect) return { left: 0, top: 0, width: 1, height: 1 };
+      const width = Math.max(1, (Number(cropRect.width) || 1) * Math.abs(Number(cropRect.scaleX) || 1));
+      const height = Math.max(1, (Number(cropRect.height) || 1) * Math.abs(Number(cropRect.scaleY) || 1));
+      return {
+        left: Number(cropRect.left) || 0,
+        top: Number(cropRect.top) || 0,
+        width,
+        height
+      };
+    }
     /**
      * Enters crop mode by creating a resizable crop rectangle above the base image.
      *
@@ -2992,14 +3466,19 @@
       const padding = this.options.crop && this.options.crop.padding ? this.options.crop.padding : 10;
       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 maxCropWidth = Math.max(1, Math.floor(imageBounds.width));
+      const maxCropHeight = Math.max(1, Math.floor(imageBounds.height));
       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 requestedCropRotation = !!(this.options.crop && this.options.crop.allowRotationOfCropRect);
+      if (requestedCropRotation && !this._cropRotationWarningEmitted) {
+        this._cropRotationWarningEmitted = true;
+        this._reportWarning("crop.allowRotationOfCropRect is disabled in v1.x because rotated crop export is not supported");
+      }
       const cropRect = new fabric.Rect({
         left,
         top,
@@ -3011,8 +3490,8 @@
         strokeWidth: 1,
         strokeUniform: true,
         selectable: true,
-        hasRotatingPoint: !!(this.options.crop && this.options.crop.allowRotationOfCropRect),
-        lockRotation: !(this.options.crop && this.options.crop.allowRotationOfCropRect),
+        hasRotatingPoint: false,
+        lockRotation: true,
         cornerSize: 8,
         objectCaching: false,
         originX: "left",
@@ -3049,7 +3528,7 @@
           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 cropBounds = this._getCropRectContentBounds(cropRect);
           const imageLeft = Number(imageBounds.left) || 0;
           const imageTop = Number(imageBounds.top) || 0;
           const imageRight = imageLeft + (Number(imageBounds.width) || 0);
@@ -3123,89 +3602,100 @@
     async applyCrop() {
       if (!this.canvas || !this._cropMode || !this._cropRect) return;
       this._assertIdleForOperation("applyCrop");
-      this._cropRect.setCoords();
-      const rectBounds = this._cropRect.getBoundingRect(true, true);
-      const cropRegion = this._getClampedCanvasRegion(rectBounds, { includePartialPixels: false });
-      const shouldPreserveMasks = !!(this.options.crop && this.options.crop.preserveMasksAfterCrop);
-      this._restoreCropObjectState();
-      let beforeJson;
-      try {
-        beforeJson = this._serializeCanvasState();
-      } catch (error) {
-        this._reportWarning("applyCrop: could not serialize before state", error);
-        beforeJson = null;
-      }
-      const preservedMasks = [];
+      const operationToken = this._beginBusyOperation("applyCrop");
+      const internalOptions = this._withInternalOperationOptions(operationToken);
       try {
-        const masks = this.canvas.getObjects().filter((object) => object.maskId);
-        if (masks && masks.length) {
-          masks.forEach((mask) => {
-            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);
-            }
-          });
-          this._clearMaskPlacementMemory();
-          this.canvas.discardActiveObject();
-          this.canvas.renderAll();
+        this._cropRect.setCoords();
+        const rectBounds = this._getCropRectContentBounds(this._cropRect);
+        const cropRegion = this._getClampedCanvasRegion(rectBounds, { includePartialPixels: false });
+        const shouldPreserveMasks = !!(this.options.crop && this.options.crop.preserveMasksAfterCrop);
+        this._restoreCropObjectState();
+        let beforeJson;
+        try {
+          beforeJson = this._serializeCanvasState();
+        } catch (error) {
+          this._reportError("applyCrop: failed to capture rollback state", error);
+          beforeJson = null;
         }
-      } catch (error) {
-        await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: failed to prepare masks", error);
-        return;
-      }
-      this._removeCropRect();
-      this._cropMode = false;
-      this.canvas.selection = !!this._prevSelectionSetting;
-      this._prevSelectionSetting = void 0;
-      let croppedBase64;
-      try {
-        croppedBase64 = await this._exportCanvasRegionToDataURL({
-          ...cropRegion,
-          multiplier: 1,
-          quality: this._normalizeQuality(this.options.downsampleQuality),
-          format: "jpeg"
-        });
-      } catch (error) {
-        await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: failed to create cropped image", error);
-        return;
-      }
-      try {
-        await this.loadImage(croppedBase64, { resetMaskCounter: false });
-        if (preservedMasks.length) {
-          preservedMasks.forEach((mask) => {
-            this._rebindMaskEvents(mask);
-            this.canvas.add(mask);
-            this.canvas.bringToFront(mask);
+        if (!beforeJson) {
+          this.cancelCrop();
+          return;
+        }
+        const preservedMasks = [];
+        try {
+          const masks = this.canvas.getObjects().filter((object) => object.maskId);
+          if (masks && masks.length) {
+            masks.forEach((mask) => {
+              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();
+            this.canvas.discardActiveObject();
+            this.canvas.renderAll();
+          }
+        } catch (error) {
+          await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: failed to prepare masks", error, internalOptions);
+          return;
+        }
+        this._removeCropRect();
+        this._cropMode = false;
+        this.canvas.selection = !!this._prevSelectionSetting;
+        this._prevSelectionSetting = void 0;
+        let croppedBase64;
+        try {
+          croppedBase64 = await this._exportCanvasRegionToDataURL({
+            ...cropRegion,
+            multiplier: 1,
+            quality: this._normalizeQuality(this.options.downsampleQuality),
+            format: "jpeg"
           });
-          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: failed to create cropped image", error, internalOptions);
+          return;
         }
-      } catch (error) {
-        await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: loadImage(croppedBase64) failed", error);
-        return;
-      }
-      let afterJson;
-      try {
-        afterJson = preservedMasks.length ? this._serializeCanvasState() : this._lastSnapshot;
-      } catch (error) {
-        this._reportWarning("applyCrop: failed to serialize after state", error);
-        afterJson = null;
-      }
-      try {
-        this._pushStateTransition(beforeJson, afterJson);
-      } catch (error) {
-        this._reportWarning("applyCrop: failed to push history command", error);
+        try {
+          await this.loadImage(croppedBase64, this._withInternalOperationOptions(operationToken, { resetMaskCounter: false }));
+          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, internalOptions);
+          return;
+        }
+        let afterJson;
+        try {
+          afterJson = preservedMasks.length ? this._serializeCanvasState() : this._lastSnapshot;
+        } catch (error) {
+          this._reportWarning("applyCrop: failed to serialize after state", error);
+          afterJson = null;
+        }
+        try {
+          this._pushStateTransition(beforeJson, afterJson);
+        } catch (error) {
+          this._reportWarning("applyCrop: failed to push history command", error);
+        }
+        this._updateUI();
+        this.canvas.renderAll();
+      } finally {
+        this._endBusyOperation(operationToken);
       }
-      this._updateUI();
-      this.canvas.renderAll();
     }
     /* ---------- Misc / UI ---------- */
     /**
@@ -3214,7 +3704,7 @@
      * @private
      */
     _updateInputs() {
-      const scaleInputElement = this._getElement("scaleRate");
+      const scaleInputElement = this._getElement("scalePercentageInput");
       if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
     }
     /**
@@ -3238,7 +3728,7 @@
         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);
@@ -3246,24 +3736,24 @@
         }
         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("scaleRate", !hasImage || isBusy);
-      this._setDisabled("rotationLeftInput", !hasImage || isBusy);
-      this._setDisabled("rotationRightInput", !hasImage || isBusy);
+      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);
@@ -3271,7 +3761,7 @@
     /**
      * 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
      */
@@ -3395,14 +3885,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();
@@ -3425,11 +3908,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) {
@@ -3526,7 +4017,7 @@
               task.reject(error);
             }
           } finally {
-            if (generation === this._generation && this.currentTask === task) this.currentTask = null;
+            if (this.currentTask === task) this.currentTask = null;
           }
         }
       } finally {
@@ -3624,11 +4115,11 @@
      *
      * @returns {Promise<void>} Resolves after the undo task completes.
      */
-    undo() {
+    undo(options = {}) {
       return this.enqueue(async () => {
         if (this.currentIndex >= 0) {
           const index = this.currentIndex;
-          await this.history[index].undo();
+          await this.history[index].undo(options);
           this.currentIndex = index - 1;
         }
       });
@@ -3638,11 +4129,11 @@
      *
      * @returns {Promise<void>} Resolves after the redo task completes.
      */
-    redo() {
+    redo(options = {}) {
       return this.enqueue(async () => {
         if (this.currentIndex < this.history.length - 1) {
           const index = this.currentIndex + 1;
-          await this.history[index].execute();
+          await this.history[index].execute(options);
           this.currentIndex = index;
         }
       });