@bensitu/image-editor 1.4.2 → 1.5.1

package/dist/image-editor.esm.mjs

@@ -5,7 +5,7 @@ import fabricModule from "fabric";
 /**
  * @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.
@@ -77,6 +77,7 @@ var ImageEditor = class {
       downsampleMimeType: null,
       imageLoadTimeoutMs: 3e4,
       exportMultiplier: 1,
+      maxExportPixels: 5e7,
       exportImageAreaByDefault: true,
       defaultMaskWidth: 50,
       defaultMaskHeight: 80,
@@ -146,7 +147,9 @@ var ImageEditor = class {
     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);
   }
@@ -192,10 +195,12 @@ var ImageEditor = class {
    * 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}
    *
@@ -204,11 +209,17 @@ var ImageEditor = class {
    * @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;
@@ -227,29 +238,49 @@ var ImageEditor = class {
       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();
@@ -257,11 +288,68 @@ var ImageEditor = class {
     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;
@@ -278,6 +366,11 @@ var ImageEditor = class {
     } 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.
    *
@@ -300,7 +393,7 @@ var ImageEditor = class {
     } 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) {
@@ -396,13 +489,14 @@ var ImageEditor = class {
     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;
@@ -450,20 +544,20 @@ var ImageEditor = class {
         });
       }
     });
-    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);
@@ -471,8 +565,8 @@ var ImageEditor = class {
       }
       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);
@@ -480,11 +574,11 @@ var ImageEditor = class {
       }
       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));
   }
   /**
@@ -553,6 +647,12 @@ var ImageEditor = class {
       `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.
    *
@@ -566,12 +666,16 @@ var ImageEditor = class {
     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;
@@ -611,7 +715,8 @@ var ImageEditor = class {
       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);
@@ -619,13 +724,13 @@ var ImageEditor = class {
         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);
@@ -654,14 +759,16 @@ var ImageEditor = class {
       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();
     }
   }
@@ -709,7 +816,7 @@ var ImageEditor = class {
         try {
           imageElement.src = "";
         } catch (error) {
-          void error;
+          this._reportWarning("Image timeout cleanup failed", error);
         }
       }, safeTimeoutMs);
       imageElement.onload = () => settle(() => resolve(imageElement));
@@ -774,32 +881,38 @@ var ImageEditor = class {
       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) {
@@ -812,6 +925,46 @@ var ImageEditor = class {
     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;
@@ -882,6 +1035,7 @@ var ImageEditor = class {
    * @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);
@@ -983,9 +1137,9 @@ var ImageEditor = class {
   }
   _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,
@@ -1011,9 +1165,17 @@ var ImageEditor = class {
     }
     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,
@@ -1135,6 +1297,45 @@ var ImageEditor = class {
       });
     }
   }
+  _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);
@@ -1154,7 +1355,7 @@ var ImageEditor = class {
   /**
    * 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() {
@@ -1162,12 +1363,16 @@ var ImageEditor = class {
     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() {
@@ -1176,6 +1381,7 @@ var ImageEditor = class {
       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);
@@ -1250,6 +1456,12 @@ var ImageEditor = class {
     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);
@@ -1258,8 +1470,8 @@ var ImageEditor = class {
     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) {
@@ -1319,7 +1531,8 @@ var ImageEditor = class {
    * @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({
@@ -1335,6 +1548,25 @@ var ImageEditor = class {
     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);
@@ -1379,6 +1611,7 @@ var ImageEditor = class {
   }
   _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));
     }
@@ -1387,6 +1620,13 @@ var ImageEditor = class {
     }
     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).
@@ -1496,24 +1736,49 @@ var ImageEditor = class {
       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);
@@ -1524,16 +1789,60 @@ var ImageEditor = class {
       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.
@@ -1548,7 +1857,14 @@ var ImageEditor = class {
     } 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();
     });
   }
@@ -1582,10 +1898,16 @@ var ImageEditor = class {
   _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) {
@@ -1597,10 +1919,14 @@ var ImageEditor = class {
   }
   _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`);
     }
   }
@@ -1694,7 +2020,7 @@ var ImageEditor = class {
         if (object.maskId) this._syncMaskLabel(object);
       });
       this._updateInputs();
-      if (saveHistory) this.saveState();
+      if (saveHistory) this.saveState(options);
     } finally {
       if (didStartAnimation) {
         this.isAnimating = false;
@@ -1716,7 +2042,14 @@ var ImageEditor = class {
     } 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();
     });
   }
@@ -1759,7 +2092,7 @@ var ImageEditor = class {
         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) {
@@ -1786,11 +2119,23 @@ var ImageEditor = class {
       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) => {
@@ -1814,8 +2159,13 @@ var ImageEditor = class {
    * @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();
@@ -1829,10 +2179,13 @@ var ImageEditor = class {
       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"));
@@ -1868,6 +2221,11 @@ var ImageEditor = class {
               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);
@@ -1895,6 +2253,9 @@ var ImageEditor = class {
             this._reportError("loadFromState() failed", callbackError);
             reject(callbackError);
           }
+        };
+        this.canvas.loadFromJSON(state, () => {
+          void finishLoad();
         });
       } catch (error) {
         this._reportError("loadFromState() failed", error);
@@ -1961,22 +2322,29 @@ var ImageEditor = class {
    * @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;
@@ -2005,8 +2373,8 @@ var ImageEditor = class {
     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;
@@ -2019,8 +2387,16 @@ var ImageEditor = class {
    * @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;
@@ -2033,8 +2409,16 @@ var ImageEditor = class {
    * @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;
@@ -2042,14 +2426,7 @@ var ImageEditor = class {
   }
   _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;
@@ -2076,6 +2453,22 @@ var ImageEditor = class {
     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.
    *
@@ -2141,18 +2534,43 @@ var ImageEditor = class {
       }
       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;
@@ -2161,10 +2579,15 @@ var ImageEditor = class {
     } 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,
@@ -2172,11 +2595,17 @@ var ImageEditor = class {
           });
           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,
@@ -2185,8 +2614,20 @@ var ImageEditor = class {
           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,
@@ -2200,11 +2641,17 @@ var ImageEditor = class {
         }
         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,
@@ -2242,10 +2689,10 @@ var ImageEditor = class {
       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,
@@ -2286,6 +2733,7 @@ var ImageEditor = class {
     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);
@@ -2310,7 +2758,10 @@ var ImageEditor = class {
     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;
@@ -2379,7 +2830,7 @@ var ImageEditor = class {
         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);
       }
     });
   }
@@ -2510,7 +2961,6 @@ var ImageEditor = class {
       try {
         if (canvasObjectSet.has(label)) {
           this.canvas.remove(label);
-          canvasObjectSet.delete(label);
         }
       } catch (error) {
         void error;
@@ -2670,6 +3120,7 @@ var ImageEditor = class {
     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();
@@ -2688,12 +3139,13 @@ var ImageEditor = class {
         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);
       }
@@ -2750,24 +3202,65 @@ var ImageEditor = class {
    */
   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);
@@ -2779,50 +3272,14 @@ var ImageEditor = class {
           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}.
@@ -2854,7 +3311,10 @@ var ImageEditor = class {
    */
   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",
@@ -2864,48 +3324,52 @@ var ImageEditor = class {
     } = 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;
@@ -2913,7 +3377,7 @@ var ImageEditor = class {
     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;
@@ -2924,7 +3388,7 @@ var ImageEditor = class {
     this._prevSelectionSetting = void 0;
     if (beforeJson) {
       try {
-        await this.loadFromState(beforeJson);
+        await this.loadFromState(beforeJson, options);
       } catch (restoreError) {
         this._reportError("applyCrop: rollback failed", restoreError);
       }
@@ -2949,28 +3413,38 @@ var ImageEditor = class {
     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.
    *
@@ -2994,14 +3468,19 @@ var ImageEditor = class {
     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,
@@ -3013,8 +3492,8 @@ var ImageEditor = class {
       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",
@@ -3051,7 +3530,7 @@ var ImageEditor = class {
         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);
@@ -3125,89 +3604,100 @@ var ImageEditor = class {
   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 ---------- */
   /**
@@ -3216,7 +3706,7 @@ var ImageEditor = class {
    * @private
    */
   _updateInputs() {
-    const scaleInputElement = this._getElement("scaleRate");
+    const scaleInputElement = this._getElement("scalePercentageInput");
     if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
   }
   /**
@@ -3240,7 +3730,7 @@ var ImageEditor = class {
       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);
@@ -3248,24 +3738,24 @@ var ImageEditor = class {
       }
       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);
@@ -3273,7 +3763,7 @@ var ImageEditor = class {
   /**
    * 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
    */
@@ -3397,14 +3887,7 @@ var ImageEditor = class {
     } 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();
@@ -3427,11 +3910,19 @@ var ImageEditor = class {
         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) {
@@ -3528,7 +4019,7 @@ var AnimationQueue = class {
             task.reject(error);
           }
         } finally {
-          if (generation === this._generation && this.currentTask === task) this.currentTask = null;
+          if (this.currentTask === task) this.currentTask = null;
         }
       }
     } finally {
@@ -3626,11 +4117,11 @@ var HistoryManager = class {
    *
    * @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;
       }
     });
@@ -3640,11 +4131,11 @@ var HistoryManager = class {
    *
    * @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;
       }
     });