@bensitu/image-editor 1.3.1 → 1.4.1

package/dist/image-editor.esm.mjs

@@ -5,12 +5,13 @@ import fabricModule from "fabric";
 /**
  * @file image-editor.js
  * @module image-editor
- * @version 1.3.1
+ * @version 1.4.1
  * @author Ben Situ
  * @license MIT
  * @description Lightweight canvas-based image editor with masking/transform/export support.
  */
 var fabric = null;
+var INTERNAL_OPERATION_TOKEN = /* @__PURE__ */ Symbol("ImageEditorInternalOperation");
 function getGlobalScope() {
   if (typeof globalThis !== "undefined") return globalThis;
   if (typeof self !== "undefined") return self;
@@ -72,6 +73,8 @@ var ImageEditor = class {
       downsampleMaxWidth: 4e3,
       downsampleMaxHeight: 3e3,
       downsampleQuality: 0.92,
+      preserveSourceFormat: true,
+      downsampleMimeType: null,
       imageLoadTimeoutMs: 3e4,
       exportMultiplier: 1,
       exportImageAreaByDefault: true,
@@ -116,10 +119,15 @@ var ImageEditor = class {
     this.currentRotation = 0;
     this.maskCounter = 0;
     this.isAnimating = false;
+    this._isLoading = false;
+    this._activeOperationName = null;
+    this._activeOperationToken = null;
     this.elements = {};
     this.isImageLoadedToCanvas = false;
     this.maxHistorySize = 50;
     this._handlersByElementKey = {};
+    this._elementCache = {};
+    this._elementOriginalPointerEvents = /* @__PURE__ */ new Map();
     this._lastMask = null;
     this._lastMaskInitialLeft = null;
     this._lastMaskInitialTop = null;
@@ -130,8 +138,14 @@ var ImageEditor = class {
     this._cropHandlers = [];
     this._cropPrevEvented = null;
     this._prevSelectionSetting = void 0;
-    this._containerOriginalOverflow = void 0;
+    this._containerOriginalOverflow = null;
+    this._lastContainerViewportSize = null;
+    this._canvasElementOriginalStyle = null;
+    this._visibilityStateByElement = /* @__PURE__ */ new WeakMap();
     this._scrollbarSizeCache = null;
+    this._activeAnimationRejectors = /* @__PURE__ */ new Set();
+    this._disposed = false;
+    this._initialized = false;
     this.onImageLoaded = typeof options.onImageLoaded === "function" ? options.onImageLoaded : null;
     this.animationQueue = new AnimationQueue();
     this.historyManager = new HistoryManager(this.maxHistorySize);
@@ -195,6 +209,20 @@ var ImageEditor = class {
    */
   init(idMap = {}) {
     if (!this._fabricLoaded) return;
+    if (this._initialized || this.canvas) this.dispose();
+    this._disposed = false;
+    this._initialized = true;
+    this.animationQueue = new AnimationQueue();
+    this.historyManager = new HistoryManager(this.maxHistorySize);
+    this._visibilityStateByElement = /* @__PURE__ */ new WeakMap();
+    this._activeAnimationRejectors = /* @__PURE__ */ new Set();
+    this._isLoading = false;
+    this._activeOperationName = null;
+    this._activeOperationToken = null;
+    this._elementOriginalPointerEvents = /* @__PURE__ */ new Map();
+    this._containerOriginalOverflow = null;
+    this._lastContainerViewportSize = null;
+    this._canvasElementOriginalStyle = null;
     const defaults = {
       canvas: "fabricCanvas",
       canvasContainer: null,
@@ -222,6 +250,7 @@ var ImageEditor = class {
       cancelCropBtn: "cancelCropBtn"
     };
     this.elements = { ...defaults, ...idMap };
+    this._elementCache = {};
     this._initCanvas();
     this._bindEvents();
     this._updateInputs();
@@ -256,16 +285,22 @@ var ImageEditor = class {
    * @private
    */
   _initCanvas() {
-    const canvasElement = document.getElementById(this.elements.canvas);
+    const canvasElement = this._getElement("canvas");
     if (!canvasElement) throw new Error("Canvas is not found: " + this.elements.canvas);
     this.canvasElement = canvasElement;
+    this._canvasElementOriginalStyle = {
+      display: canvasElement.style.display || "",
+      width: canvasElement.style.width || "",
+      height: canvasElement.style.height || "",
+      maxWidth: canvasElement.style.maxWidth || ""
+    };
     if (this.elements.canvasContainer) {
-      const containerElement = document.getElementById(this.elements.canvasContainer);
+      const containerElement = this._getElement("canvasContainer");
       this.containerElement = containerElement || canvasElement.parentElement;
     } else {
       this.containerElement = canvasElement.parentElement;
     }
-    this.placeholderElement = document.getElementById(this.elements.imgPlaceholder) || null;
+    this.placeholderElement = this._getElement("imgPlaceholder") || null;
     let initialWidth = this.options.canvasWidth;
     let initialHeight = this.options.canvasHeight;
     if (this.containerElement) {
@@ -274,6 +309,10 @@ var ImageEditor = class {
       if (containerWidth > 0 && containerHeight > 0) {
         initialWidth = containerWidth;
         initialHeight = containerHeight;
+        this._lastContainerViewportSize = {
+          width: containerWidth,
+          height: containerHeight
+        };
       }
     }
     this.canvas = new fabric.Canvas(canvasElement, {
@@ -298,6 +337,23 @@ var ImageEditor = class {
     this.canvas.on("object:modified", (event) => this._handleObjectModified(event.target));
     this.canvasElement.style.display = "block";
   }
+  /**
+   * Returns a configured DOM element and caches lookups for hot UI paths.
+   *
+   * @param {string} key - Key in the configured element map.
+   * @returns {HTMLElement|null} The configured element, or null when missing.
+   * @private
+   */
+  _getElement(key) {
+    const id = this.elements && this.elements[key];
+    if (!id) return null;
+    if (this._elementCache && Object.prototype.hasOwnProperty.call(this._elementCache, key)) {
+      return this._elementCache[key];
+    }
+    const element = document.getElementById(id);
+    if (this._elementCache) this._elementCache[key] = element || null;
+    return element || null;
+  }
   /**
    * Records a history entry after Fabric finishes modifying one or more masks.
    *
@@ -338,9 +394,7 @@ var ImageEditor = class {
    */
   _syncContainerOverflow(options = {}) {
     if (!this.containerElement || !this.containerElement.style) return;
-    if (this._containerOriginalOverflow === void 0) {
-      this._containerOriginalOverflow = this.containerElement.style.overflow || "";
-    }
+    this._captureContainerOverflowState();
     const shouldPreserveScroll = options.preserveScroll === true;
     if (this.options.coverImageToCanvas) {
       this.containerElement.style.overflow = "scroll";
@@ -355,58 +409,83 @@ var ImageEditor = class {
         this.containerElement.scrollTop = 0;
       }
     } else {
-      this.containerElement.style.overflow = this._containerOriginalOverflow;
+      this._restoreContainerOverflowState();
     }
   }
+  _captureContainerOverflowState() {
+    if (!this.containerElement || !this.containerElement.style || this._containerOriginalOverflow) return;
+    this._containerOriginalOverflow = {
+      overflow: this.containerElement.style.overflow || "",
+      overflowX: this.containerElement.style.overflowX || "",
+      overflowY: this.containerElement.style.overflowY || ""
+    };
+  }
+  _restoreContainerOverflowState() {
+    if (!this.containerElement || !this.containerElement.style || !this._containerOriginalOverflow) return;
+    this.containerElement.style.overflow = this._containerOriginalOverflow.overflow;
+    this.containerElement.style.overflowX = this._containerOriginalOverflow.overflowX;
+    this.containerElement.style.overflowY = this._containerOriginalOverflow.overflowY;
+  }
+  _restoreContainerOverflowSnapshot(snapshot) {
+    if (!this.containerElement || !this.containerElement.style || !snapshot) return;
+    this.containerElement.style.overflow = snapshot.overflow || "";
+    this.containerElement.style.overflowX = snapshot.overflowX || "";
+    this.containerElement.style.overflowY = snapshot.overflowY || "";
+  }
   /** 
    * DOM / UI bindings
    * @private
    */
   _bindEvents() {
     this._bindIfExists("uploadArea", "click", () => {
-      const uploadAreaElement = document.getElementById(this.elements.uploadArea);
+      const uploadAreaElement = this._getElement("uploadArea");
       if (this._isElementDisabled(uploadAreaElement)) return;
-      document.getElementById(this.elements.imageInput)?.click();
+      this._getElement("imageInput")?.click();
     });
     this._bindIfExists("imageInput", "change", (event) => {
       const file = event.target.files && event.target.files[0];
-      if (file) this._loadImageFile(file);
+      if (file) {
+        this._loadImageFile(file).catch((error) => this._reportError("Image file could not be loaded", error)).finally(() => {
+          event.target.value = "";
+        });
+      }
     });
-    this._bindIfExists("zoomInBtn", "click", () => this.scaleImage(this.currentScale + this.options.scaleStep));
-    this._bindIfExists("zoomOutBtn", "click", () => this.scaleImage(this.currentScale - this.options.scaleStep));
+    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.resetImageTransform();
+      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());
+    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());
-    this._bindIfExists("redoBtn", "click", () => this.redo());
+    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 = document.getElementById(this.elements.rotationLeftInput);
+      const rotationInputElement = this._getElement("rotationLeftInput");
       let step = this.options.rotationStep;
       if (rotationInputElement) {
         const parsedStep = parseFloat(rotationInputElement.value);
         if (!isNaN(parsedStep)) step = parsedStep;
       }
-      this.rotateImage(this.currentRotation - step);
+      this.rotateImage(this.currentRotation - step).catch((error) => this._reportError("rotateImage failed", error));
     });
     this._bindIfExists("rotateRightBtn", "click", () => {
-      const rotationInputElement = document.getElementById(this.elements.rotationRightInput);
+      const rotationInputElement = this._getElement("rotationRightInput");
       let step = this.options.rotationStep;
       if (rotationInputElement) {
         const parsedStep = parseFloat(rotationInputElement.value);
         if (!isNaN(parsedStep)) step = parsedStep;
       }
-      this.rotateImage(this.currentRotation + step);
+      this.rotateImage(this.currentRotation + step).catch((error) => this._reportError("rotateImage failed", error));
     });
     this._bindIfExists("cropBtn", "click", () => this.enterCropMode());
     this._bindIfExists("applyCropBtn", "click", () => {
       this.applyCrop().catch((error) => this._reportError("applyCrop failed", error));
     });
     this._bindIfExists("cancelCropBtn", "click", () => this.cancelCrop());
+    this._bindIfExists("maskList", "click", (event) => this._handleMaskListClick(event));
   }
   /**
    * Binds a DOM event listener when the configured element exists and records it for disposal.
@@ -417,7 +496,7 @@ var ImageEditor = class {
    * @private
    */
   _bindIfExists(key, eventName, handler) {
-    const element = document.getElementById(this.elements[key]);
+    const element = this._getElement(key);
     if (element) {
       element.addEventListener(eventName, handler);
       this._handlersByElementKey = this._handlersByElementKey || {};
@@ -429,16 +508,33 @@ var ImageEditor = class {
    * Reads an image File as a data URL and loads it into the Fabric canvas.
    *
    * @param {File} file - Image file selected by the user.
+   * @returns {Promise<void>} Resolves after the selected file is loaded.
    * @private
    */
   _loadImageFile(file) {
-    if (!file || !file.type.startsWith("image/")) return;
-    const reader = new FileReader();
-    reader.onload = (event) => this.loadImage(event.target.result);
-    reader.onerror = (event) => {
-      this._reportError("Image file could not be read", event);
-    };
-    reader.readAsDataURL(file);
+    if (!this._isSupportedImageFile(file)) {
+      const error = new Error("Selected file is not a supported image");
+      this._reportError("Selected file is not a supported image", error);
+      return Promise.reject(error);
+    }
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = (event) => {
+        this.loadImage(event.target.result).then(resolve).catch(reject);
+      };
+      reader.onerror = (event) => {
+        const error = new Error("Image file could not be read");
+        this._reportError("Image file could not be read", event);
+        reject(error);
+      };
+      reader.readAsDataURL(file);
+    });
+  }
+  _isSupportedImageFile(file) {
+    if (!file) return false;
+    if (typeof file.type === "string" && file.type.startsWith("image/")) return true;
+    const fileName = String(file.name || "");
+    return /\.(avif|bmp|gif|jpe?g|png|webp)$/i.test(fileName);
   }
   /**
    * Warns when more than one mutually exclusive image layout mode is enabled.
@@ -468,98 +564,102 @@ var ImageEditor = class {
    */
   async loadImage(imageBase64, options = {}) {
     if (!this._fabricLoaded) return;
-    if (!this.canvas) return;
+    if (!this.canvas || this._disposed) return;
     if (!imageBase64 || typeof imageBase64 !== "string" || !imageBase64.startsWith("data:image/")) return;
+    this._assertIdleForOperation("loadImage", options);
+    this._isLoading = true;
+    this._updateUI();
     this._warnOnImageLayoutOptionConflict();
-    this._setPlaceholderVisible(false);
-    this._syncContainerOverflow({ preserveScroll: options.preserveScroll === true });
-    const imageElement = await this._createImageElement(imageBase64);
-    let loadSource = imageBase64;
-    if (this.options.downsampleOnLoad) {
-      const shouldResize = imageElement.naturalWidth > this.options.downsampleMaxWidth || imageElement.naturalHeight > this.options.downsampleMaxHeight;
-      if (shouldResize) {
-        const ratio = Math.min(
-          this.options.downsampleMaxWidth / imageElement.naturalWidth,
-          this.options.downsampleMaxHeight / imageElement.naturalHeight
-        );
-        const targetWidth = Math.round(imageElement.naturalWidth * ratio);
-        const targetHeight = Math.round(imageElement.naturalHeight * ratio);
-        loadSource = this._resampleImageToDataURL(imageElement, targetWidth, targetHeight, this.options.downsampleQuality);
+    const transaction = this._captureLoadImageTransaction();
+    try {
+      const imageElement = await this._createImageElement(imageBase64);
+      if (this._disposed || !this.canvas) throw new Error("Editor was disposed while loading image");
+      let loadSource = imageBase64;
+      if (this.options.downsampleOnLoad) {
+        const shouldResize = imageElement.naturalWidth > this.options.downsampleMaxWidth || imageElement.naturalHeight > this.options.downsampleMaxHeight;
+        if (shouldResize) {
+          const ratio = Math.min(
+            this.options.downsampleMaxWidth / imageElement.naturalWidth,
+            this.options.downsampleMaxHeight / imageElement.naturalHeight
+          );
+          const targetWidth = Math.round(imageElement.naturalWidth * ratio);
+          const targetHeight = Math.round(imageElement.naturalHeight * ratio);
+          loadSource = this._resampleImageToDataURL(
+            imageElement,
+            targetWidth,
+            targetHeight,
+            this._normalizeQuality(this.options.downsampleQuality),
+            imageBase64
+          );
+        }
+      }
+      const fabricImage = await this._createFabricImageFromURL(loadSource);
+      if (this._disposed || !this.canvas) throw new Error("Editor was disposed while loading image");
+      this.canvas.discardActiveObject();
+      this._hideAllMaskLabels();
+      this.canvas.clear();
+      this.canvas.setBackgroundColor(this.options.backgroundColor, this.canvas.renderAll.bind(this.canvas));
+      fabricImage.set({ originX: "left", originY: "top", selectable: false, evented: false });
+      this._setPlaceholderVisible(false);
+      this._syncContainerOverflow({ preserveScroll: options.preserveScroll === true });
+      const imageWidth = fabricImage.width;
+      const imageHeight = fabricImage.height;
+      const viewport = this._getContainerViewportSize();
+      const minWidth = viewport.width;
+      const minHeight = viewport.height;
+      if (this.options.fitImageToCanvas) {
+        const canvasWidth = Math.max(1, minWidth - 1);
+        const canvasHeight = Math.max(1, minHeight - 1);
+        this._setCanvasSizeInt(canvasWidth, canvasHeight);
+        const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
+        fabricImage.set({ left: 0, top: 0 });
+        fabricImage.scale(fitScale);
+        this.baseImageScale = fabricImage.scaleX || 1;
+      } else if (this.options.coverImageToCanvas) {
+        const layout = this._calculateCoverCanvasLayout(imageWidth, imageHeight);
+        this._setCanvasSizeInt(layout.canvasWidth, layout.canvasHeight);
+        fabricImage.set({ left: 0, top: 0 });
+        fabricImage.scale(layout.scale);
+        this.baseImageScale = fabricImage.scaleX || 1;
+      } else if (this.options.expandCanvasToImage) {
+        const canvasWidth = Math.max(minWidth, Math.floor(imageWidth));
+        const canvasHeight = Math.max(minHeight, Math.floor(imageHeight));
+        this._setCanvasSizeInt(canvasWidth, canvasHeight);
+        fabricImage.set({ left: 0, top: 0 });
+        fabricImage.scale(1);
+        this.baseImageScale = 1;
+      } else {
+        const canvasWidth = Math.max(this.options.canvasWidth, minWidth);
+        const canvasHeight = Math.max(this.options.canvasHeight, minHeight);
+        this._setCanvasSizeInt(canvasWidth, canvasHeight);
+        const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
+        fabricImage.set({ left: 0, top: 0 });
+        fabricImage.scale(fitScale);
+        this.baseImageScale = fabricImage.scaleX || 1;
+      }
+      this.originalImage = fabricImage;
+      this.canvas.add(fabricImage);
+      this.canvas.sendToBack(fabricImage);
+      this._clearMaskPlacementMemory();
+      if (options.resetMaskCounter !== false) this.maskCounter = 0;
+      this.currentScale = 1;
+      this.currentRotation = 0;
+      this._updateInputs();
+      this._updateMaskList();
+      this.isImageLoadedToCanvas = true;
+      this._updateUI();
+      this.canvas.renderAll();
+      this._lastSnapshot = this._captureCanvasStateOrThrow("loadImage");
+      if (typeof this.onImageLoaded === "function") {
+        this.onImageLoaded();
       }
+    } catch (error) {
+      await this._rollbackLoadImageTransaction(transaction);
+      throw error;
+    } finally {
+      this._isLoading = false;
+      if (!this._disposed && this.canvas) this._updateUI();
     }
-    return new Promise((resolve, reject) => {
-      fabric.Image.fromURL(loadSource, (fabricImage) => {
-        try {
-          if (!fabricImage) throw new Error("Image could not be loaded");
-          this.canvas.discardActiveObject();
-          this._hideAllMaskLabels();
-          this.canvas.clear();
-          this.canvas.setBackgroundColor(this.options.backgroundColor, this.canvas.renderAll.bind(this.canvas));
-          fabricImage.set({ originX: "left", originY: "top", selectable: false, evented: false });
-          const imageWidth = fabricImage.width;
-          const imageHeight = fabricImage.height;
-          const viewport = this._getContainerViewportSize();
-          const minWidth = viewport.width;
-          const minHeight = viewport.height;
-          if (this.options.fitImageToCanvas) {
-            const canvasWidth = Math.max(1, minWidth - 1);
-            const canvasHeight = Math.max(1, minHeight - 1);
-            this._setCanvasSizeInt(canvasWidth, canvasHeight);
-            const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
-            fabricImage.set({ left: 0, top: 0 });
-            fabricImage.scale(fitScale);
-            this.baseImageScale = fabricImage.scaleX || 1;
-          } else if (this.options.coverImageToCanvas) {
-            const layout = this._calculateCoverCanvasLayout(imageWidth, imageHeight);
-            this._setCanvasSizeInt(layout.canvasWidth, layout.canvasHeight);
-            fabricImage.set({ left: 0, top: 0 });
-            fabricImage.scale(layout.scale);
-            this.baseImageScale = fabricImage.scaleX || 1;
-          } else if (this.options.expandCanvasToImage) {
-            const canvasWidth = Math.max(minWidth, Math.floor(imageWidth));
-            const canvasHeight = Math.max(minHeight, Math.floor(imageHeight));
-            this._setCanvasSizeInt(canvasWidth, canvasHeight);
-            fabricImage.set({ left: 0, top: 0 });
-            fabricImage.scale(1);
-            this.baseImageScale = 1;
-          } else {
-            const canvasWidth = Math.max(this.options.canvasWidth, minWidth);
-            const canvasHeight = Math.max(this.options.canvasHeight, minHeight);
-            this._setCanvasSizeInt(canvasWidth, canvasHeight);
-            const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
-            fabricImage.set({ left: 0, top: 0 });
-            fabricImage.scale(fitScale);
-            this.baseImageScale = fabricImage.scaleX || 1;
-          }
-          this.originalImage = fabricImage;
-          this.canvas.add(fabricImage);
-          this.canvas.sendToBack(fabricImage);
-          this._lastMask = null;
-          this._lastMaskInitialLeft = null;
-          this._lastMaskInitialTop = null;
-          this._lastMaskInitialWidth = null;
-          this.maskCounter = 0;
-          this.currentScale = 1;
-          this.currentRotation = 0;
-          this._updateInputs();
-          this._updateMaskList();
-          this.isImageLoadedToCanvas = true;
-          this._updateUI();
-          this.canvas.renderAll();
-          try {
-            this._lastSnapshot = this._serializeCanvasState();
-          } catch (error) {
-            this._reportWarning("loadImage: failed to capture initial canvas snapshot", error);
-          }
-          if (typeof this.onImageLoaded === "function") {
-            this.onImageLoaded();
-          }
-          resolve();
-        } catch (error) {
-          reject(error);
-        }
-      }, { crossOrigin: "anonymous" });
-    });
   }
   /**
    * Checks whether there is a loaded image on the current canvas.
@@ -604,24 +704,155 @@ var ImageEditor = class {
       imageElement.src = dataUrl;
     });
   }
+  _createFabricImageFromURL(dataUrl, timeoutMs = this.options.imageLoadTimeoutMs) {
+    return new Promise((resolve, reject) => {
+      const safeTimeoutMs = this._getSafeTimeoutMs(timeoutMs);
+      let isSettled = false;
+      let timerId;
+      const settle = (callback) => {
+        if (isSettled) return;
+        isSettled = true;
+        clearTimeout(timerId);
+        callback();
+      };
+      timerId = setTimeout(() => {
+        settle(() => reject(new Error("Fabric image load timed out")));
+      }, safeTimeoutMs);
+      try {
+        fabric.Image.fromURL(dataUrl, (fabricImage) => {
+          settle(() => {
+            if (!fabricImage) {
+              reject(new Error("Image could not be loaded"));
+              return;
+            }
+            resolve(fabricImage);
+          });
+        }, { crossOrigin: "anonymous" });
+      } catch (error) {
+        settle(() => reject(error));
+      }
+    });
+  }
+  _getSafeTimeoutMs(timeoutMs) {
+    const safeTimeoutMs = Number(timeoutMs);
+    return Number.isFinite(safeTimeoutMs) && safeTimeoutMs > 0 ? safeTimeoutMs : 3e4;
+  }
+  _captureLoadImageTransaction() {
+    return {
+      canvasState: this._serializeCanvasState(),
+      originalImage: this.originalImage,
+      baseImageScale: this.baseImageScale,
+      currentScale: this.currentScale,
+      currentRotation: this.currentRotation,
+      maskCounter: this.maskCounter,
+      isImageLoadedToCanvas: this.isImageLoadedToCanvas,
+      lastSnapshot: this._lastSnapshot,
+      lastMask: this._lastMask,
+      lastMaskInitialLeft: this._lastMaskInitialLeft,
+      lastMaskInitialTop: this._lastMaskInitialTop,
+      lastMaskInitialWidth: this._lastMaskInitialWidth,
+      containerOverflow: this.containerElement && this.containerElement.style ? {
+        overflow: this.containerElement.style.overflow || "",
+        overflowX: this.containerElement.style.overflowX || "",
+        overflowY: this.containerElement.style.overflowY || ""
+      } : null,
+      scrollLeft: this.containerElement ? this.containerElement.scrollLeft : 0,
+      scrollTop: this.containerElement ? this.containerElement.scrollTop : 0,
+      placeholderVisibility: this._captureElementVisibility(this.placeholderElement),
+      canvasVisibility: this._captureElementVisibility(this._getCanvasVisibilityElement())
+    };
+  }
+  async _rollbackLoadImageTransaction(transaction) {
+    if (!transaction || !this.canvas || this._disposed) return;
+    let didRestoreCanvasState = false;
+    try {
+      if (transaction.canvasState) {
+        await this.loadFromState(transaction.canvasState);
+        didRestoreCanvasState = true;
+      }
+    } catch (error) {
+      this._lastMask = null;
+      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);
+    } else {
+      this._lastMask = null;
+    }
+    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) {
+      this.containerElement.scrollLeft = transaction.scrollLeft;
+      this.containerElement.scrollTop = transaction.scrollTop;
+      this._restoreContainerOverflowSnapshot(transaction.containerOverflow);
+    }
+    this._updateInputs();
+    this._updateMaskList();
+    this._updateUI();
+    if (this.canvas) this.canvas.renderAll();
+  }
+  _restoreLastMaskReference(previousLastMask) {
+    if (!this.canvas) {
+      this._lastMask = null;
+      return;
+    }
+    const masks = this.canvas.getObjects().filter((object) => object.maskId);
+    const previousMaskId = previousLastMask && previousLastMask.maskId;
+    this._lastMask = masks.find((mask) => mask.maskId === previousMaskId) || masks[masks.length - 1] || null;
+    if (!this._lastMask) {
+      this._lastMaskInitialLeft = null;
+      this._lastMaskInitialTop = null;
+      this._lastMaskInitialWidth = null;
+    }
+  }
   /**
-   * Resamples the given image element to a new width and height and returns the result as a JPEG data URL.
+   * Resamples the given image element to a new width and height and returns the result as a data URL.
    * 
    * @param {HTMLImageElement} imageElement - The image element to resample.
    * @param {number} targetWidth - Target width (in pixels) for the resampled image.
    * @param {number} targetHeight - Target height (in pixels) for the resampled image.
-   * @param {number} [quality=0.92] - JPEG image quality between 0 and 1 (optional, default 0.92).
-   * @returns {string} A data URL representing the resampled image as JPEG.
+   * @param {number} [quality=0.92] - Image quality between 0 and 1 for lossy formats.
+   * @param {string|null} [sourceDataUrl=null] - Source data URL used to preserve alpha-capable formats.
+   * @returns {string} A data URL representing the resampled image.
    * @private
    */
-  _resampleImageToDataURL(imageElement, targetWidth, targetHeight, quality = 0.92) {
+  _resampleImageToDataURL(imageElement, targetWidth, targetHeight, quality = 0.92, sourceDataUrl = null) {
     const offscreenCanvas = document.createElement("canvas");
     offscreenCanvas.width = targetWidth;
     offscreenCanvas.height = targetHeight;
     const context = offscreenCanvas.getContext("2d");
     if (!context) throw new Error("2D canvas context is unavailable");
     context.drawImage(imageElement, 0, 0, imageElement.naturalWidth, imageElement.naturalHeight, 0, 0, targetWidth, targetHeight);
-    return offscreenCanvas.toDataURL("image/jpeg", quality);
+    return offscreenCanvas.toDataURL(this._getDownsampleMimeType(sourceDataUrl), quality);
+  }
+  _getDataUrlMimeType(dataUrl) {
+    const match = String(dataUrl || "").match(/^data:([^;,]+)[;,]/i);
+    return match ? match[1].toLowerCase() : "";
+  }
+  _getDownsampleMimeType(sourceDataUrl) {
+    if (this.options.downsampleMimeType) {
+      const requestedFormat = this._normalizeImageFormat(this.options.downsampleMimeType);
+      return `image/${requestedFormat}`;
+    }
+    const sourceMimeType = this._getDataUrlMimeType(sourceDataUrl);
+    if (this.options.preserveSourceFormat !== false && (sourceMimeType === "image/png" || sourceMimeType === "image/webp")) {
+      return sourceMimeType;
+    }
+    return "image/jpeg";
+  }
+  _captureCanvasStateOrThrow(context) {
+    const snapshot = this._serializeCanvasState();
+    if (!snapshot) throw new Error(`${context}: canvas state is unavailable`);
+    return snapshot;
   }
   /** 
    * Sets canvas size to integer width and height values to prevent scrollbars due to sub-pixel rendering.
@@ -640,7 +871,6 @@ var ImageEditor = class {
     if (this.canvasElement) {
       this.canvasElement.style.width = integerWidth + "px";
       this.canvasElement.style.height = integerHeight + "px";
-      this.canvasElement.style.maxWidth = "none";
     }
   }
   _ceilCanvasDimension(value) {
@@ -656,8 +886,13 @@ var ImageEditor = class {
         height: Math.max(1, Math.floor(this.options.canvasHeight || 1))
       };
     }
-    let width = Math.max(1, Math.floor(this.containerElement.clientWidth || this.options.canvasWidth || 1));
-    let height = Math.max(1, Math.floor(this.containerElement.clientHeight || this.options.canvasHeight || 1));
+    const measuredWidth = Math.floor(this.containerElement.clientWidth || 0);
+    const measuredHeight = Math.floor(this.containerElement.clientHeight || 0);
+    let width = Math.max(1, measuredWidth || this._lastContainerViewportSize?.width || this.options.canvasWidth || 1);
+    let height = Math.max(1, measuredHeight || this._lastContainerViewportSize?.height || this.options.canvasHeight || 1);
+    if (measuredWidth > 0 && measuredHeight > 0) {
+      this._lastContainerViewportSize = { width: measuredWidth, height: measuredHeight };
+    }
     if (this._hasFixedContainerScrollbars()) {
       return { width, height };
     }
@@ -862,7 +1097,11 @@ var ImageEditor = class {
         maskStyleBackups.push(backup);
         mask.set(stylePatch);
       });
-      return callback();
+      const result = callback();
+      if (result && typeof result.then === "function") {
+        throw new Error("_withNormalizedMaskStyles callback must be synchronous");
+      }
+      return result;
     } finally {
       maskStyleBackups.forEach((backup) => {
         try {
@@ -930,9 +1169,13 @@ var ImageEditor = class {
    * @returns {number} A finite quality value between 0 and 1.
    * @private
    */
-  _normalizeQuality(quality) {
+  _normalizeQuality(quality, fallback = void 0) {
+    const fallbackQuality = fallback == null ? this.options.downsampleQuality : fallback;
+    const numericFallback = fallbackQuality == null ? NaN : Number(fallbackQuality);
+    const safeFallback = Number.isFinite(numericFallback) ? Math.max(0, Math.min(1, numericFallback)) : 0.92;
+    if (quality == null) return safeFallback;
     const numericQuality = Number(quality);
-    if (!Number.isFinite(numericQuality)) return this.options.downsampleQuality ?? 0.92;
+    if (!Number.isFinite(numericQuality)) return safeFallback;
     return Math.max(0, Math.min(1, numericQuality));
   }
   /**
@@ -983,67 +1226,66 @@ var ImageEditor = class {
       sourceHeight: Math.max(1, endY - sourceY)
     };
   }
-  /**
-   * Crops an image data URL to a source region using an offscreen canvas.
-   *
-   * @param {string} dataUrl - Source image data URL.
-   * @param {number} sourceX - Source region x coordinate.
-   * @param {number} sourceY - Source region y coordinate.
-   * @param {number} sourceWidth - Source region width.
-   * @param {number} sourceHeight - Source region height.
-   * @param {number} multiplier - Export multiplier already applied to the source data URL.
-   * @param {'jpeg'|'png'|'webp'} [format='jpeg'] - Output image format.
-   * @param {number} [quality=0.92] - Output image quality for lossy formats.
-   * @returns {Promise<string>} Resolves with the cropped image data URL.
-   * @private
-   */
-  async _cropDataUrl(dataUrl, sourceX, sourceY, sourceWidth, sourceHeight, multiplier, format = "jpeg", quality = 0.92) {
-    return new Promise((resolve, reject) => {
-      const imageElement = new Image();
-      let isSettled = false;
-      const timeoutMs = Number(this.options.imageLoadTimeoutMs);
-      const safeTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 3e4;
-      let timerId;
-      const settle = (callback) => {
-        if (isSettled) return;
-        isSettled = true;
-        clearTimeout(timerId);
-        imageElement.onload = null;
-        imageElement.onerror = null;
-        callback();
-      };
-      timerId = setTimeout(() => {
-        settle(() => reject(new Error("Image crop load timed out")));
-        try {
-          imageElement.src = "";
-        } catch (error) {
-          void error;
-        }
-      }, safeTimeoutMs);
-      imageElement.onload = () => {
-        try {
-          const safeMultiplier = Math.max(1, Number(multiplier) || 1);
-          const scaledSourceX = Math.round(sourceX * safeMultiplier);
-          const scaledSourceY = Math.round(sourceY * safeMultiplier);
-          const scaledSourceWidth = Math.max(1, Math.round(sourceWidth * safeMultiplier));
-          const scaledSourceHeight = Math.max(1, Math.round(sourceHeight * safeMultiplier));
-          const offscreenCanvas = document.createElement("canvas");
-          offscreenCanvas.width = scaledSourceWidth;
-          offscreenCanvas.height = scaledSourceHeight;
-          const context = offscreenCanvas.getContext("2d");
-          if (!context) throw new Error("2D canvas context is unavailable");
-          context.drawImage(imageElement, scaledSourceX, scaledSourceY, scaledSourceWidth, scaledSourceHeight, 0, 0, scaledSourceWidth, scaledSourceHeight);
-          settle(() => resolve(offscreenCanvas.toDataURL(`image/${format}`, quality)));
-        } catch (error) {
-          settle(() => reject(error));
-        }
-      };
-      imageElement.onerror = (error) => settle(() => reject(error));
-      imageElement.src = dataUrl;
-    });
+  _hasFractionalCanvasEdge(value) {
+    const numericValue = Number(value);
+    if (!Number.isFinite(numericValue)) return false;
+    return Math.abs(numericValue - Math.round(numericValue)) > 0.01;
+  }
+  _getPartialExportEdges(bounds) {
+    if (!bounds) return null;
+    const angle = Math.abs((Number(this.originalImage && this.originalImage.angle) || 0) % 90);
+    const isAxisAligned = angle < 0.01 || Math.abs(angle - 90) < 0.01;
+    if (!isAxisAligned) return null;
+    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))
+    };
+  }
+  async _sealPartialTransparentEdges(dataUrl, edges) {
+    if (!edges || !Object.values(edges).some(Boolean)) return dataUrl;
+    const imageElement = await this._createImageElement(dataUrl);
+    const width = Math.max(1, imageElement.naturalWidth || imageElement.width || 1);
+    const height = Math.max(1, imageElement.naturalHeight || imageElement.height || 1);
+    const offscreenCanvas = document.createElement("canvas");
+    offscreenCanvas.width = width;
+    offscreenCanvas.height = height;
+    const context = offscreenCanvas.getContext("2d");
+    if (!context) throw new Error("2D canvas context is unavailable");
+    context.drawImage(imageElement, 0, 0, width, height);
+    const imageData = context.getImageData(0, 0, width, height);
+    const pixels = imageData.data;
+    const sealPixel = (x, y, fallbackX, fallbackY) => {
+      const index = (y * width + x) * 4;
+      const fallbackIndex = (fallbackY * width + fallbackX) * 4;
+      if (pixels[index + 3] === 0 && pixels[fallbackIndex + 3] > 0) {
+        pixels[index] = pixels[fallbackIndex];
+        pixels[index + 1] = pixels[fallbackIndex + 1];
+        pixels[index + 2] = pixels[fallbackIndex + 2];
+        pixels[index + 3] = pixels[fallbackIndex + 3];
+      }
+      if (pixels[index + 3] > 0 && pixels[index + 3] < 255) {
+        pixels[index + 3] = 255;
+      }
+    };
+    if (edges.left && width > 1) {
+      for (let y = 0; y < height; y += 1) sealPixel(0, y, 1, y);
+    }
+    if (edges.right && width > 1) {
+      for (let y = 0; y < height; y += 1) sealPixel(width - 1, y, width - 2, y);
+    }
+    if (edges.top && height > 1) {
+      for (let x = 0; x < width; x += 1) sealPixel(x, 0, x, 1);
+    }
+    if (edges.bottom && height > 1) {
+      for (let x = 0; x < width; x += 1) sealPixel(x, height - 1, x, height - 2);
+    }
+    context.putImageData(imageData, 0, 0);
+    return offscreenCanvas.toDataURL("image/png");
   }
   /**
-   * Exports the whole Fabric canvas, then crops the requested source region from that export.
+   * Exports a source region directly through Fabric's region export options.
    *
    * @param {Object} region - Canvas source region and export options.
    * @param {number} region.sourceX - Source region x coordinate.
@@ -1053,17 +1295,46 @@ var ImageEditor = class {
    * @param {number} [region.multiplier=1] - Export multiplier.
    * @param {number} [region.quality=0.92] - Output image quality for lossy formats.
    * @param {'jpeg'|'png'|'webp'} [region.format='jpeg'] - Output image format.
+   * @param {Object|null} [region.sealPartialEdges=null] - Fractional canvas edges whose alpha should be sealed.
    * @returns {Promise<string>} Resolves with an image data URL for the cropped region.
    * @private
    */
-  async _exportCanvasRegionToDataURL({ sourceX, sourceY, sourceWidth, sourceHeight, multiplier = 1, quality = 0.92, format = "jpeg" }) {
+  async _exportCanvasRegionToDataURL({ sourceX, sourceY, sourceWidth, sourceHeight, multiplier = 1, quality = 0.92, format = "jpeg", sealPartialEdges = null }) {
     const safeMultiplier = Math.max(1, Number(multiplier) || 1);
-    const fullDataUrl = this.canvas.toDataURL({
-      format,
+    const safeFormat = this._normalizeImageFormat(format);
+    const exportFormat = safeFormat === "jpeg" ? "png" : safeFormat;
+    let regionDataUrl = this.canvas.toDataURL({
+      format: exportFormat,
       quality,
-      multiplier: safeMultiplier
+      multiplier: safeMultiplier,
+      left: sourceX,
+      top: sourceY,
+      width: sourceWidth,
+      height: sourceHeight
     });
-    return this._cropDataUrl(fullDataUrl, sourceX, sourceY, sourceWidth, sourceHeight, safeMultiplier, format, quality);
+    regionDataUrl = await this._sealPartialTransparentEdges(regionDataUrl, sealPartialEdges);
+    if (safeFormat !== "jpeg") return regionDataUrl;
+    return this._convertDataUrlToOpaqueJpeg(regionDataUrl, quality);
+  }
+  async _convertDataUrlToOpaqueJpeg(dataUrl, quality = 0.92) {
+    const imageElement = await this._createImageElement(dataUrl);
+    const width = Math.max(1, imageElement.naturalWidth || imageElement.width || 1);
+    const height = Math.max(1, imageElement.naturalHeight || imageElement.height || 1);
+    const offscreenCanvas = document.createElement("canvas");
+    offscreenCanvas.width = width;
+    offscreenCanvas.height = height;
+    const context = offscreenCanvas.getContext("2d");
+    if (!context) throw new Error("2D canvas context is unavailable");
+    context.fillStyle = this._getJpegBackgroundColor();
+    context.fillRect(0, 0, width, height);
+    context.drawImage(imageElement, 0, 0, width, height);
+    return offscreenCanvas.toDataURL("image/jpeg", this._normalizeQuality(quality));
+  }
+  _getJpegBackgroundColor() {
+    const backgroundColor = String(this.options.backgroundColor || "").trim();
+    if (!backgroundColor || backgroundColor === "transparent") return "#ffffff";
+    if (/^rgba\([^)]*,\s*0(?:\.0+)?\s*\)$/i.test(backgroundColor)) return "#ffffff";
+    return backgroundColor;
   }
   /** 
    * Gets the top-left corner coordinates of the given object.
@@ -1076,11 +1347,37 @@ var ImageEditor = class {
   _getObjectTopLeftPoint(fabricObject) {
     if (!fabricObject) return { x: 0, y: 0 };
     fabricObject.setCoords();
-    const coords = typeof fabricObject.getCoords === "function" ? fabricObject.getCoords() : null;
-    if (coords && coords.length) return coords[0];
     const boundingRect = fabricObject.getBoundingRect(true, true);
     return { x: boundingRect.left, y: boundingRect.top };
   }
+  _getObjectCoordinateTopLeftPoint(fabricObject) {
+    if (!fabricObject) return { x: 0, y: 0 };
+    fabricObject.setCoords();
+    const coords = typeof fabricObject.getCoords === "function" ? fabricObject.getCoords() : null;
+    if (coords && coords.length) return coords[0];
+    return this._getObjectTopLeftPoint(fabricObject);
+  }
+  _getObjectOriginPoint(fabricObject, originX, originY) {
+    if (!fabricObject) return { x: 0, y: 0 };
+    if (typeof fabricObject.getPointByOrigin === "function") {
+      return fabricObject.getPointByOrigin(originX, originY);
+    }
+    return this._getObjectTopLeftPoint(fabricObject);
+  }
+  _translateObjectByCanvasOffset(fabricObject, deltaX, deltaY) {
+    if (!fabricObject) return;
+    if (typeof fabricObject.getCenterPoint === "function" && typeof fabricObject.setPositionByOrigin === "function") {
+      const center = fabricObject.getCenterPoint();
+      const nextCenter = new fabric.Point(center.x + deltaX, center.y + deltaY);
+      fabricObject.setPositionByOrigin(nextCenter, "center", "center");
+    } else {
+      fabricObject.set({
+        left: (fabricObject.left || 0) + deltaX,
+        top: (fabricObject.top || 0) + deltaY
+      });
+    }
+    fabricObject.setCoords();
+  }
   /**
    * Sets the object's origin at the specified origin point, keeping a reference point fixed in position.
    * 
@@ -1144,8 +1441,10 @@ var ImageEditor = class {
   _expandCanvasToFitObjects(fabricObjects, padding = 10) {
     if (!this.canvas || !Array.isArray(fabricObjects) || !fabricObjects.length || !this._shouldResizeCanvasToContentBounds()) return;
     try {
-      let requiredWidth = this.canvas.getWidth();
-      let requiredHeight = this.canvas.getHeight();
+      const currentWidth = this.canvas.getWidth();
+      const currentHeight = this.canvas.getHeight();
+      let requiredWidth = currentWidth;
+      let requiredHeight = currentHeight;
       fabricObjects.forEach((fabricObject) => {
         if (!fabricObject) return;
         if (typeof fabricObject.setCoords === "function") fabricObject.setCoords();
@@ -1153,11 +1452,21 @@ var ImageEditor = class {
         requiredWidth = Math.max(requiredWidth, Math.ceil(boundingRect.left + boundingRect.width + padding));
         requiredHeight = Math.max(requiredHeight, Math.ceil(boundingRect.top + boundingRect.height + padding));
       });
-      const minWidth = this.containerElement ? Math.floor(this.containerElement.clientWidth || 0) : 0;
-      const minHeight = this.containerElement ? Math.floor(this.containerElement.clientHeight || 0) : 0;
-      const newWidth = Math.max(this.canvas.getWidth(), minWidth, requiredWidth);
-      const newHeight = Math.max(this.canvas.getHeight(), minHeight, requiredHeight);
-      if (newWidth !== this.canvas.getWidth() || newHeight !== this.canvas.getHeight()) {
+      const shouldUseScrollSafeViewport = this.options.fitImageToCanvas || this.options.coverImageToCanvas;
+      let minWidth = 0;
+      let minHeight = 0;
+      if (shouldUseScrollSafeViewport) {
+        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);
+      if (newWidth !== currentWidth || newHeight !== currentHeight) {
         this._setCanvasSizeInt(newWidth, newHeight);
       }
     } catch (error) {
@@ -1183,7 +1492,120 @@ var ImageEditor = class {
    * @public
    */
   scaleImage(factor, options = {}) {
-    return this.animationQueue.add(() => this._scaleImageImpl(factor, options));
+    try {
+      this._assertCanQueueAnimation("scaleImage", options);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return this.animationQueue.add(() => this._scaleImageImpl(factor, options)).finally(() => {
+      if (!this._disposed && this.canvas) this._updateUI();
+    });
+  }
+  _getInternalOperationToken(options) {
+    return options && options[INTERNAL_OPERATION_TOKEN];
+  }
+  _isOwnInternalOperation(options) {
+    const token = this._getInternalOperationToken(options);
+    return !!token && token === this._activeOperationToken;
+  }
+  _beginBusyOperation(operationName) {
+    const token = Symbol(operationName);
+    this._activeOperationName = operationName;
+    this._activeOperationToken = token;
+    this._updateUI();
+    return token;
+  }
+  _endBusyOperation(token) {
+    if (token && token === this._activeOperationToken) {
+      this._activeOperationName = null;
+      this._activeOperationToken = null;
+      this._updateUI();
+    }
+  }
+  _withInternalOperationOptions(token, options = {}) {
+    return {
+      ...options,
+      [INTERNAL_OPERATION_TOKEN]: token
+    };
+  }
+  _assertEditorAvailable(operationName) {
+    if (this._disposed || !this.canvas) throw new Error(`${operationName} cannot run after the editor has been disposed`);
+  }
+  _assertIdleForOperation(operationName, options = {}) {
+    this._assertEditorAvailable(operationName);
+    const isOwnInternalOperation = this._isOwnInternalOperation(options);
+    if (this.isAnimating || this.animationQueue && this.animationQueue.isBusy()) {
+      throw new Error(`${operationName} cannot run while an animation is running`);
+    }
+    if (this._isLoading && !isOwnInternalOperation) {
+      throw new Error(`${operationName} cannot run while an image is loading`);
+    }
+    if (this._activeOperationToken && !isOwnInternalOperation) {
+      throw new Error(`${operationName} cannot run while ${this._activeOperationName || "another operation"} is running`);
+    }
+  }
+  _assertCanQueueAnimation(operationName, options = {}) {
+    this._assertEditorAvailable(operationName);
+    if (this._isLoading && !this._isOwnInternalOperation(options)) {
+      throw new Error(`${operationName} cannot run while an image is loading`);
+    }
+    if (this._activeOperationToken && !this._isOwnInternalOperation(options)) {
+      throw new Error(`${operationName} cannot run while ${this._activeOperationName || "another operation"} is running`);
+    }
+  }
+  _canMutateNow(operationName, options = {}) {
+    try {
+      this._assertIdleForOperation(operationName, options);
+      return true;
+    } catch (error) {
+      this._reportError(`${operationName} blocked`, error);
+      return false;
+    }
+  }
+  _rejectActiveAnimations(reason) {
+    const error = reason instanceof Error ? reason : new Error(String(reason || "Animation cancelled"));
+    this._activeAnimationRejectors.forEach((reject) => {
+      try {
+        reject(error);
+      } catch (rejectError) {
+        void rejectError;
+      }
+    });
+    this._activeAnimationRejectors.clear();
+  }
+  _animateFabricProperty(fabricObject, property, value) {
+    return new Promise((resolve, reject) => {
+      if (this._disposed || !this.canvas || !fabricObject) {
+        reject(new Error("Animation cannot start after editor disposal"));
+        return;
+      }
+      let isSettled = false;
+      const duration = Math.max(0, Number(this.options.animationDuration) || 0);
+      const timeoutMs = Math.max(1e3, duration + 1e3);
+      let timerId;
+      const settle = (callback) => {
+        if (isSettled) return;
+        isSettled = true;
+        clearTimeout(timerId);
+        this._activeAnimationRejectors.delete(reject);
+        callback();
+      };
+      this._activeAnimationRejectors.add(reject);
+      timerId = setTimeout(() => {
+        settle(() => reject(new Error(`Animation timed out while changing ${property}`)));
+      }, timeoutMs);
+      try {
+        fabricObject.animate(property, value, {
+          duration,
+          onChange: () => {
+            if (!this._disposed && this.canvas) this.canvas.renderAll();
+          },
+          onComplete: () => settle(resolve)
+        });
+      } catch (error) {
+        settle(() => reject(error));
+      }
+    });
   }
   /** 
    * Scales the original image by a given factor, with animation.
@@ -1192,32 +1614,25 @@ var ImageEditor = class {
    * @returns {Promise<void>} Promise that resolves once the scaling animation finishes.
    * @private
    */
-  _scaleImageImpl(factor, options = {}) {
-    if (!this.originalImage) return Promise.resolve();
-    if (this.isAnimating) return Promise.resolve();
+  async _scaleImageImpl(factor, options = {}) {
+    if (!this.originalImage || this._disposed) return;
+    if (this.isAnimating) return;
     const saveHistory = options.saveHistory !== false;
-    factor = Math.max(this.options.minScale, Math.min(this.options.maxScale, factor));
-    this.currentScale = factor;
-    this.isAnimating = true;
-    this._updateUI();
-    const targetScale = this.baseImageScale * factor;
-    const topLeft = this._getObjectTopLeftPoint(this.originalImage);
-    this._setObjectOriginKeepingPosition(this.originalImage, "left", "top", topLeft);
-    const scaleXAnimation = new Promise((resolve) => {
-      this.originalImage.animate("scaleX", targetScale, {
-        duration: this.options.animationDuration,
-        onChange: this.canvas.renderAll.bind(this.canvas),
-        onComplete: resolve
-      });
-    });
-    const scaleYAnimation = new Promise((resolve) => {
-      this.originalImage.animate("scaleY", targetScale, {
-        duration: this.options.animationDuration,
-        onChange: this.canvas.renderAll.bind(this.canvas),
-        onComplete: resolve
-      });
-    });
-    return Promise.all([scaleXAnimation, scaleYAnimation]).then(() => {
+    let didStartAnimation = false;
+    try {
+      factor = Math.max(this.options.minScale, Math.min(this.options.maxScale, factor));
+      this.currentScale = factor;
+      this.isAnimating = true;
+      didStartAnimation = true;
+      this._updateUI();
+      const targetScale = this.baseImageScale * factor;
+      const topLeft = this._getObjectTopLeftPoint(this.originalImage);
+      this._setObjectOriginKeepingPosition(this.originalImage, "left", "top", topLeft);
+      await Promise.all([
+        this._animateFabricProperty(this.originalImage, "scaleX", targetScale),
+        this._animateFabricProperty(this.originalImage, "scaleY", targetScale)
+      ]);
+      if (this._disposed || !this.canvas || !this.originalImage) throw new Error("Editor was disposed during scale animation");
       this.originalImage.set({ scaleX: targetScale, scaleY: targetScale });
       this.originalImage.setCoords();
       if (this._shouldResizeCanvasToContentBounds()) {
@@ -1227,14 +1642,15 @@ var ImageEditor = class {
       this.canvas.getObjects().forEach((object) => {
         if (object.maskId) this._syncMaskLabel(object);
       });
-      this.isAnimating = false;
       this._updateInputs();
-      this._updateUI();
       if (saveHistory) this.saveState();
-    }).catch(() => {
-      this.isAnimating = false;
-      this._updateUI();
-    });
+    } finally {
+      if (didStartAnimation) {
+        this.isAnimating = false;
+        this._updateInputs();
+        this._updateUI();
+      }
+    }
   }
   /** 
    * Rotates the original image by a given number of degrees, with animation.
@@ -1244,7 +1660,14 @@ var ImageEditor = class {
    * @public
    */
   rotateImage(degrees, options = {}) {
-    return this.animationQueue.add(() => this._rotateImageImpl(degrees, options));
+    try {
+      this._assertCanQueueAnimation("rotateImage", options);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return this.animationQueue.add(() => this._rotateImageImpl(degrees, options)).finally(() => {
+      if (!this._disposed && this.canvas) this._updateUI();
+    });
   }
   /** 
    * Rotates the original image by a given number of degrees, with animation.
@@ -1253,43 +1676,50 @@ var ImageEditor = class {
    * @returns {Promise<void>} Promise that resolves once the rotation animation finishes.
    * @private
    */
-  _rotateImageImpl(degrees, options = {}) {
-    if (!this.originalImage) return Promise.resolve();
-    if (this.isAnimating) return Promise.resolve();
-    if (isNaN(degrees)) return Promise.resolve();
+  async _rotateImageImpl(degrees, options = {}) {
+    if (!this.originalImage || this._disposed) return;
+    if (this.isAnimating) return;
+    if (isNaN(degrees)) return;
     const saveHistory = options.saveHistory !== false;
-    this.currentRotation = degrees;
-    this.isAnimating = true;
-    this._updateUI();
-    const center = this.originalImage.getCenterPoint();
-    this._setObjectOriginKeepingPosition(this.originalImage, "center", "center", center);
-    const rotationAnimation = new Promise((resolve) => {
-      this.originalImage.animate("angle", degrees, {
-        duration: this.options.animationDuration,
-        onChange: this.canvas.renderAll.bind(this.canvas),
-        onComplete: resolve
-      });
-    });
-    return rotationAnimation.then(() => {
+    const image = this.originalImage;
+    const previousOriginX = image.originX || "left";
+    const previousOriginY = image.originY || "top";
+    const previousOriginPoint = this._getObjectOriginPoint(image, previousOriginX, previousOriginY);
+    let didStartAnimation = false;
+    let didCompleteRotation = false;
+    try {
+      this.currentRotation = degrees;
+      this.isAnimating = true;
+      didStartAnimation = true;
+      this._updateUI();
+      const center = image.getCenterPoint();
+      this._setObjectOriginKeepingPosition(image, "center", "center", center);
+      await this._animateFabricProperty(image, "angle", degrees);
+      if (this._disposed || !this.canvas || !this.originalImage) throw new Error("Editor was disposed during rotation animation");
       this.originalImage.set("angle", degrees);
       this.originalImage.setCoords();
       if (this._shouldResizeCanvasToContentBounds()) {
         this._updateCanvasSizeToImageBounds();
       }
       this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
-      const newTopLeft = this._getObjectTopLeftPoint(this.originalImage);
+      const newTopLeft = this._getObjectCoordinateTopLeftPoint(this.originalImage);
       this._setObjectOriginKeepingPosition(this.originalImage, "left", "top", newTopLeft);
       this.canvas.getObjects().forEach((object) => {
         if (object.maskId) this._syncMaskLabel(object);
       });
-      this.isAnimating = false;
       this._updateInputs();
-      this._updateUI();
       if (saveHistory) this.saveState();
-    }).catch(() => {
-      this.isAnimating = false;
-      this._updateUI();
-    });
+      didCompleteRotation = true;
+    } finally {
+      if (!didCompleteRotation && !this._disposed && image) {
+        this._setObjectOriginKeepingPosition(image, previousOriginX, previousOriginY, previousOriginPoint);
+      }
+      if (didStartAnimation) {
+        this.isAnimating = false;
+        this._updateInputs();
+        this._updateUI();
+      }
+    }
   }
   /**
    * Resets the image transform: scales to 1 and rotates to 0 degrees.
@@ -1299,14 +1729,22 @@ var ImageEditor = class {
    */
   resetImageTransform() {
     if (!this.originalImage) return Promise.resolve();
+    try {
+      this._assertCanQueueAnimation("resetImageTransform");
+    } catch (error) {
+      return Promise.reject(error);
+    }
     return this.animationQueue.add(async () => {
-      const before = this._lastSnapshot || this._serializeCanvasState();
+      const before = this._lastSnapshot || this._captureCanvasStateOrThrow("resetImageTransform");
       await this._scaleImageImpl(1, { saveHistory: false });
       await this._rotateImageImpl(0, { saveHistory: false });
-      const after = this._serializeCanvasState();
+      const after = this._captureCanvasStateOrThrow("resetImageTransform");
       this._pushStateTransition(before, after);
+    }).finally(() => {
+      if (!this._disposed && this.canvas) this._updateUI();
     }).catch((error) => {
       this._reportError("resetImageTransform() failed", error);
+      throw error;
     });
   }
   /**
@@ -1326,13 +1764,31 @@ var ImageEditor = class {
    * @public
    */
   loadFromState(serializedState) {
-    if (!serializedState || !this.canvas) return Promise.resolve();
-    return new Promise((resolve) => {
+    if (!serializedState || !this.canvas || this._disposed) return Promise.resolve();
+    if (this._cropMode || this._cropRect) {
+      this._removeCropRect();
+      this._restoreCropObjectState();
+      this._cropMode = false;
+      if (this._prevSelectionSetting !== void 0 && this.canvas) {
+        this.canvas.selection = !!this._prevSelectionSetting;
+      }
+      this._prevSelectionSetting = void 0;
+    }
+    return new Promise((resolve, reject) => {
       try {
         const state = typeof serializedState === "string" ? JSON.parse(serializedState) : serializedState;
         const editorMetadata = state && state.imageEditorMetadata ? state.imageEditorMetadata : null;
-        this.canvas.loadFromJSON(state, () => {
+        this.canvas.loadFromJSON(state, async () => {
           try {
+            if (this._disposed || !this.canvas) {
+              reject(new Error("Editor was disposed while loading state"));
+              return;
+            }
+            await this._waitForFabricImagesReady(this.canvas.getObjects());
+            if (this._disposed || !this.canvas) {
+              reject(new Error("Editor was disposed while loading state"));
+              return;
+            }
             this._hideAllMaskLabels();
             const canvasObjects = this.canvas.getObjects();
             this.originalImage = canvasObjects.find((object) => object.type === "image" && !object.maskId) || null;
@@ -1380,15 +1836,53 @@ var ImageEditor = class {
             this._updatePlaceholderStatus();
             this._lastSnapshot = this._serializeCanvasState();
             this._updateUI();
+            resolve();
           } catch (callbackError) {
             this._reportError("loadFromState() failed", callbackError);
-          } finally {
-            resolve();
+            reject(callbackError);
           }
         });
       } catch (error) {
         this._reportError("loadFromState() failed", error);
-        resolve();
+        reject(error);
+      }
+    });
+  }
+  async _waitForFabricImagesReady(canvasObjects) {
+    const imageObjects = (canvasObjects || []).filter((object) => object && object.type === "image");
+    await Promise.all(imageObjects.map((object) => this._waitForImageElementReady(
+      typeof object.getElement === "function" ? object.getElement() : object._element
+    )));
+  }
+  _waitForImageElementReady(imageElement) {
+    if (!imageElement) return Promise.resolve();
+    if (imageElement.complete || imageElement.naturalWidth > 0 || imageElement.width > 0) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      let isSettled = false;
+      const timerId = setTimeout(() => {
+        settle(() => reject(new Error("Image load timed out while restoring state")));
+      }, this._getSafeTimeoutMs(this.options.imageLoadTimeoutMs));
+      const settle = (callback) => {
+        if (isSettled) return;
+        isSettled = true;
+        clearTimeout(timerId);
+        if (typeof imageElement.removeEventListener === "function") {
+          imageElement.removeEventListener("load", handleLoad);
+          imageElement.removeEventListener("error", handleError);
+        } else {
+          imageElement.onload = null;
+          imageElement.onerror = null;
+        }
+        callback();
+      };
+      const handleLoad = () => settle(resolve);
+      const handleError = (error) => settle(() => reject(error));
+      if (typeof imageElement.addEventListener === "function") {
+        imageElement.addEventListener("load", handleLoad, { once: true });
+        imageElement.addEventListener("error", handleError, { once: true });
+      } else {
+        imageElement.onload = handleLoad;
+        imageElement.onerror = handleError;
       }
     });
   }
@@ -1403,9 +1897,8 @@ var ImageEditor = class {
    */
   saveState() {
     if (!this.canvas) return;
-    const activeObject = this.canvas.getActiveObject();
     try {
-      const after = this._serializeCanvasState();
+      const after = this._captureCanvasStateOrThrow("saveState");
       const before = this._lastSnapshot || after;
       if (after === before) return;
       let executedOnce = false;
@@ -1424,9 +1917,6 @@ var ImageEditor = class {
     } catch (error) {
       this._reportWarning("saveState: failed to save canvas snapshot", error);
     } finally {
-      if (activeObject && activeObject.maskId && !activeObject.__label && this.canvas.getObjects().includes(activeObject)) {
-        this._handleSelectionChanged([activeObject]);
-      }
       this._updateUI();
     }
   }
@@ -1442,7 +1932,10 @@ var ImageEditor = class {
    * @private
    */
   _pushStateTransition(before, after) {
-    if (!before || !after) return;
+    if (!before || !after) {
+      this._reportWarning("History transition skipped because a canvas snapshot is unavailable");
+      return;
+    }
     if (before === after) return;
     if (!this.historyManager) this.historyManager = new HistoryManager(this.maxHistorySize || 50);
     const command = new Command(
@@ -1464,6 +1957,7 @@ var ImageEditor = class {
       this._updateUI();
     }).catch((error) => {
       this._reportError("undo failed", error);
+      throw error;
     });
   }
   /**
@@ -1477,6 +1971,7 @@ var ImageEditor = class {
       this._updateUI();
     }).catch((error) => {
       this._reportError("redo failed", error);
+      throw error;
     });
   }
   _rebindMaskEvents(mask) {
@@ -1498,22 +1993,17 @@ var ImageEditor = class {
       metadata.originalStrokeWidth = Number.isFinite(Number(mask.strokeWidth)) ? Number(mask.strokeWidth) : 1;
     }
     if (Object.keys(metadata).length) mask.set(metadata);
-    const normalStyle = {
-      stroke: mask.originalStroke || "#ccc",
-      strokeWidth: mask.originalStrokeWidth,
-      opacity: mask.originalAlpha
-    };
-    const hoverStyle = {
-      stroke: "#ff5500",
-      strokeWidth: 2,
-      opacity: Math.min(mask.originalAlpha + 0.2, 1)
-    };
     const mouseover = () => {
-      mask.set(hoverStyle);
+      const opacity = Number(mask.originalAlpha);
+      mask.set({
+        stroke: "#ff5500",
+        strokeWidth: 2,
+        opacity: Math.min((Number.isFinite(opacity) ? opacity : 0.5) + 0.2, 1)
+      });
       if (mask.canvas) mask.canvas.requestRenderAll();
     };
     const mouseout = () => {
-      mask.set(normalStyle);
+      mask.set(this._getMaskNormalStyle(mask));
       if (mask.canvas) mask.canvas.requestRenderAll();
     };
     mask.on("mouseover", mouseover);
@@ -1550,6 +2040,7 @@ var ImageEditor = class {
    */
   createMask(config = {}) {
     if (!this.canvas) return null;
+    if (!this._canMutateNow("createMask")) return null;
     const shapeType = config.shape || "rect";
     const maskConfig = {
       shape: shapeType,
@@ -1586,14 +2077,10 @@ var ImageEditor = class {
     };
     if (maskConfig.left === void 0 && this._lastMask) {
       const previousMask = this._lastMask;
-      let previousMaskRight = previousMask.left;
-      if (previousMask.getScaledWidth) {
-        previousMaskRight += previousMask.getScaledWidth();
-      } else if (previousMask.width) {
-        previousMaskRight += previousMask.width * (previousMask.scaleX ?? 1);
-      }
-      left = Math.round(previousMaskRight + maskConfig.gap);
-      top = previousMask.top ?? firstOffset;
+      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");
@@ -1721,6 +2208,8 @@ var ImageEditor = class {
    * The associated label is also removed. UI and mask list are updated.
    */
   removeSelectedMask() {
+    if (!this.canvas) return;
+    if (!this._canMutateNow("removeSelectedMask")) return;
     const activeObject = this.canvas.getActiveObject();
     const selectedMasks = this._getModifiedMasks(activeObject);
     if (!selectedMasks.length) return;
@@ -1746,6 +2235,8 @@ var ImageEditor = class {
    * UI and internal mask placement memory are reset.
    */
   removeAllMasks(options = {}) {
+    if (!this.canvas) return;
+    if (!this._canMutateNow("removeAllMasks", options)) return;
     const saveHistory = options.saveHistory !== false;
     const masks = this.canvas.getObjects().filter((object) => object.maskId);
     masks.forEach((mask) => this._removeLabelForMask(mask));
@@ -1813,6 +2304,10 @@ var ImageEditor = class {
     let textObject = null;
     if (this.options.label && typeof this.options.label.create === "function") {
       textObject = this.options.label.create(mask, fabric);
+      if (!textObject || typeof textObject.set !== "function") {
+        this._reportWarning("label.create() returned an invalid Fabric object; using the default label");
+        textObject = null;
+      }
     }
     if (!textObject) {
       let labelText = mask.maskName;
@@ -1880,9 +2375,10 @@ var ImageEditor = class {
     if (!mask) return;
     if (!this.options.maskLabelOnSelect) return;
     if (!mask.__label) return;
-    const coords = mask.getCoords ? mask.getCoords() : null;
-    if (!coords || coords.length < 4) return;
-    const tl = coords[0];
+    if (typeof mask.setCoords === "function") mask.setCoords();
+    const bounds = mask.getBoundingRect ? mask.getBoundingRect(true, true) : null;
+    if (!bounds) return;
+    const tl = { x: bounds.left, y: bounds.top };
     const center = mask.getCenterPoint();
     const vx = center.x - tl.x;
     const vy = center.y - tl.y;
@@ -1960,7 +2456,7 @@ var ImageEditor = class {
    * @private
    */
   _updateMaskList() {
-    const maskListElement = document.getElementById(this.elements.maskList);
+    const maskListElement = this._getElement("maskList");
     if (!maskListElement) return;
     maskListElement.innerHTML = "";
     const masks = this.canvas.getObjects().filter((object) => object.maskId);
@@ -1968,13 +2464,20 @@ var ImageEditor = class {
       const listItemElement = document.createElement("li");
       listItemElement.className = "list-group-item mask-item";
       listItemElement.textContent = mask.maskName;
-      listItemElement.onclick = () => {
-        this.canvas.setActiveObject(mask);
-        this._handleSelectionChanged([mask]);
-      };
+      listItemElement.dataset.maskId = String(mask.maskId);
       maskListElement.appendChild(listItemElement);
     });
   }
+  _handleMaskListClick(event) {
+    if (!this.canvas) return;
+    const itemElement = event.target && event.target.closest ? event.target.closest(".mask-item") : null;
+    if (!itemElement || !itemElement.dataset) return;
+    const maskId = Number(itemElement.dataset.maskId);
+    const mask = this.canvas.getObjects().find((object) => Number(object.maskId) === maskId);
+    if (!mask) return;
+    this.canvas.setActiveObject(mask);
+    this._handleSelectionChanged([mask]);
+  }
   /**
    * Updates the visual selection (CSS 'active') state for the mask list in the DOM.
    * 
@@ -1982,12 +2485,13 @@ var ImageEditor = class {
    * @private
    */
   _updateMaskListSelection(selectedMask) {
-    const maskListElement = document.getElementById(this.elements.maskList);
+    const maskListElement = this._getElement("maskList");
     if (!maskListElement) return;
     const maskItems = maskListElement.querySelectorAll(".mask-item");
     maskItems.forEach((item) => {
-      const isSelected = !!selectedMask && item.textContent === selectedMask.maskName;
+      const isSelected = !!selectedMask && Number(item.dataset.maskId) === Number(selectedMask.maskId);
       item.classList.toggle("active", isSelected);
+      item.classList.toggle("selected", isSelected);
     });
   }
   /**
@@ -2002,19 +2506,36 @@ var ImageEditor = class {
    */
   async mergeMasks() {
     if (!this.originalImage) return;
+    this._assertIdleForOperation("mergeMasks");
     const masks = this.canvas.getObjects().filter((object) => object.maskId);
     if (!masks.length) return;
+    const beforeJson = this._serializeCanvasState();
+    const operationToken = this._beginBusyOperation("mergeMasks");
     this.canvas.discardActiveObject();
     this.canvas.renderAll();
     try {
-      const beforeJson = this._serializeCanvasState();
-      const merged = await this.exportImageBase64({ exportImageArea: true, multiplier: this.options.exportMultiplier });
-      this.removeAllMasks({ saveHistory: false });
-      await this.loadImage(merged, { preserveScroll: true });
+      const merged = await this.exportImageBase64(this._withInternalOperationOptions(operationToken, {
+        exportImageArea: true,
+        multiplier: this.options.exportMultiplier,
+        fileType: "png"
+      }));
+      this.removeAllMasks(this._withInternalOperationOptions(operationToken, { saveHistory: false }));
+      await this.loadImage(merged, this._withInternalOperationOptions(operationToken, {
+        preserveScroll: true,
+        resetMaskCounter: false
+      }));
       const afterJson = this._serializeCanvasState();
       this._pushStateTransition(beforeJson, afterJson);
     } catch (error) {
       this._reportError("merge error", error);
+      try {
+        await this.loadFromState(beforeJson);
+      } catch (restoreError) {
+        this._reportError("mergeMasks rollback failed", restoreError);
+      }
+      throw error;
+    } finally {
+      this._endBusyOperation(operationToken);
     }
   }
   /**
@@ -2036,6 +2557,7 @@ var ImageEditor = class {
    */
   downloadImage(fileName = this.options.defaultDownloadFileName) {
     if (!this.originalImage) return;
+    if (!this._canMutateNow("downloadImage")) return;
     const exportImageArea = this.options.exportImageAreaByDefault;
     this.exportImageBase64({ exportImageArea, multiplier: this.options.exportMultiplier }).then((imageBase64) => {
       const link = document.createElement("a");
@@ -2064,6 +2586,7 @@ var ImageEditor = class {
    */
   async exportImageBase64(options = {}) {
     if (!this.originalImage) throw new Error("No image loaded");
+    this._assertIdleForOperation("exportImageBase64", options);
     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);
@@ -2079,12 +2602,13 @@ var ImageEditor = class {
         this.canvas.renderAll();
         this.originalImage.setCoords();
         const imageBounds = this.originalImage.getBoundingRect(true, true);
-        const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+        const exportRegion = this._getClampedCanvasRegion(imageBounds);
         return await this._exportCanvasRegionToDataURL({
           ...exportRegion,
           multiplier,
           quality,
-          format
+          format,
+          sealPartialEdges: this._getPartialExportEdges(imageBounds)
         });
       } finally {
         maskVisibilityBackups.forEach((backup) => {
@@ -2119,12 +2643,13 @@ var ImageEditor = class {
       this.canvas.renderAll();
       this.originalImage.setCoords();
       const imageBounds = this.originalImage.getBoundingRect(true, true);
-      const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+      const exportRegion = this._getClampedCanvasRegion(imageBounds);
       finalBase64 = await this._exportCanvasRegionToDataURL({
         ...exportRegion,
         multiplier,
         quality,
-        format
+        format,
+        sealPartialEdges: this._getPartialExportEdges(imageBounds)
       });
     } finally {
       maskStyleBackups.forEach((backup) => {
@@ -2176,6 +2701,7 @@ var ImageEditor = class {
    */
   async exportImageFile(options = {}) {
     if (!this.originalImage) throw new Error("No image loaded");
+    this._assertIdleForOperation("exportImageFile");
     const {
       mergeMask = true,
       fileType = "jpeg",
@@ -2184,19 +2710,20 @@ var ImageEditor = class {
       fileName = this.options.defaultDownloadFileName ?? "exported_image.jpg"
     } = options;
     const safeFileType = this._normalizeImageFormat(fileType);
+    const normalizedQuality = this._normalizeQuality(quality);
     let imageBase64;
     if (mergeMask) {
       imageBase64 = await this.exportImageBase64({
         exportImageArea: true,
         multiplier,
-        quality,
+        quality: normalizedQuality,
         fileType: safeFileType
       });
     } else {
       imageBase64 = await this.exportImageBase64({
         exportImageArea: false,
         multiplier,
-        quality,
+        quality: normalizedQuality,
         fileType: safeFileType
       });
     }
@@ -2211,8 +2738,9 @@ var ImageEditor = class {
             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}`, quality);
+            const convertedDataUrl = offscreenCanvas.toDataURL(`image/${safeFileType}`, normalizedQuality);
             resolve(convertedDataUrl);
           } catch (error) {
             reject(error);
@@ -2278,7 +2806,9 @@ var ImageEditor = class {
       if (this._cropHandlers && this._cropHandlers.length) {
         this._cropHandlers.forEach((targetHandlers) => {
           targetHandlers.handlers.forEach((handlerRecord) => {
-            targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
+            if (targetHandlers.target && typeof targetHandlers.target.off === "function") {
+              targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
+            }
           });
         });
       }
@@ -2286,7 +2816,7 @@ var ImageEditor = class {
       void error;
     }
     try {
-      this.canvas.remove(this._cropRect);
+      if (this.canvas) this.canvas.remove(this._cropRect);
     } catch (error) {
       void error;
     }
@@ -2304,7 +2834,9 @@ var ImageEditor = class {
    */
   enterCropMode() {
     if (!this.canvas || !this.originalImage || this._cropMode) return;
+    if (!this._canMutateNow("enterCropMode")) return;
     if (!this.isImageLoaded()) return;
+    this._removeCropRect();
     this._cropMode = true;
     this._prevSelectionSetting = this.canvas.selection;
     this.canvas.selection = false;
@@ -2420,6 +2952,7 @@ 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 });
@@ -2444,12 +2977,8 @@ var ImageEditor = class {
             this._removeLabelForMask(mask);
             this.canvas.remove(mask);
             if (shouldPreserveMasks && intersectsCrop) {
-              mask.set({
-                left: (mask.left || 0) - cropRegion.sourceX,
-                top: (mask.top || 0) - cropRegion.sourceY,
-                visible: true
-              });
-              mask.setCoords();
+              this._translateObjectByCanvasOffset(mask, -cropRegion.sourceX, -cropRegion.sourceY);
+              mask.set({ visible: true });
               preservedMasks.push(mask);
             }
           } catch (error) {
@@ -2480,7 +3009,7 @@ var ImageEditor = class {
       return;
     }
     try {
-      await this.loadImage(croppedBase64);
+      await this.loadImage(croppedBase64, { resetMaskCounter: false });
       if (preservedMasks.length) {
         preservedMasks.forEach((mask) => {
           this._rebindMaskEvents(mask);
@@ -2498,7 +3027,7 @@ var ImageEditor = class {
     }
     let afterJson;
     try {
-      afterJson = this._serializeCanvasState();
+      afterJson = preservedMasks.length ? this._serializeCanvasState() : this._lastSnapshot;
     } catch (error) {
       this._reportWarning("applyCrop: failed to serialize after state", error);
       afterJson = null;
@@ -2518,7 +3047,7 @@ var ImageEditor = class {
    * @private
    */
   _updateInputs() {
-    const scaleInputElement = document.getElementById(this.elements.scaleRate);
+    const scaleInputElement = this._getElement("scaleRate");
     if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
   }
   /**
@@ -2527,6 +3056,7 @@ var ImageEditor = class {
    * @private
    */
   _updateUI() {
+    if (!this.canvas) return;
     const hasImage = !!this.originalImage;
     const masks = hasImage ? this.canvas.getObjects().filter((object) => object.maskId) : [];
     const hasMasks = masks.length > 0;
@@ -2536,9 +3066,10 @@ var ImageEditor = class {
     const canUndo = this.historyManager?.canUndo();
     const canRedo = this.historyManager?.canRedo();
     const isInCropMode = !!this._cropMode;
+    const isBusy = this.isAnimating || this._isLoading || !!this._activeOperationToken || !!(this.animationQueue && this.animationQueue.isBusy());
     if (isInCropMode) {
       for (const key of Object.keys(this.elements || {})) {
-        const element = document.getElementById(this.elements[key]);
+        const element = this._getElement(key);
         if (!element) continue;
         if (key === "applyCropBtn" || key === "cancelCropBtn") {
           this._setDisabled(key, false);
@@ -2548,23 +3079,23 @@ var ImageEditor = class {
       }
       return;
     }
-    this._setDisabled("zoomInBtn", !hasImage || this.isAnimating || this.currentScale >= this.options.maxScale);
-    this._setDisabled("zoomOutBtn", !hasImage || this.isAnimating || this.currentScale <= this.options.minScale);
-    this._setDisabled("rotateLeftBtn", !hasImage || this.isAnimating);
-    this._setDisabled("rotateRightBtn", !hasImage || this.isAnimating);
-    this._setDisabled("addMaskBtn", !hasImage || this.isAnimating);
-    this._setDisabled("removeMaskBtn", !hasSelectedMask || this.isAnimating);
-    this._setDisabled("removeAllMasksBtn", !hasMasks || this.isAnimating);
-    this._setDisabled("mergeBtn", !hasImage || !hasMasks || this.isAnimating);
-    this._setDisabled("downloadBtn", !hasImage || this.isAnimating);
-    this._setDisabled("resetBtn", !hasImage || isDefaultTransform || this.isAnimating);
-    this._setDisabled("undoBtn", !hasImage || this.isAnimating || !canUndo);
-    this._setDisabled("redoBtn", !hasImage || this.isAnimating || !canRedo);
-    this._setDisabled("cropBtn", !hasImage || this.isAnimating);
+    this._setDisabled("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("imageInput", this.isAnimating);
-    this._setDisabled("uploadArea", this.isAnimating);
+    this._setDisabled("imageInput", isBusy);
+    this._setDisabled("uploadArea", isBusy);
   }
   /**
    * Enables or disables a specific UI element (typically a button) by its key.
@@ -2574,18 +3105,22 @@ var ImageEditor = class {
    * @private
    */
   _setDisabled(key, disabled) {
-    const element = document.getElementById(this.elements[key]);
+    const element = this._getElement(key);
     if (!element) return;
     if ("disabled" in element) {
       element.disabled = !!disabled;
       return;
     }
+    if (!this._elementOriginalPointerEvents) this._elementOriginalPointerEvents = /* @__PURE__ */ new Map();
+    if (!this._elementOriginalPointerEvents.has(key)) {
+      this._elementOriginalPointerEvents.set(key, element.style.pointerEvents || "");
+    }
     if (disabled) {
       element.setAttribute("aria-disabled", "true");
       element.style.pointerEvents = "none";
     } else {
       element.removeAttribute("aria-disabled");
-      element.style.pointerEvents = "";
+      element.style.pointerEvents = this._elementOriginalPointerEvents.get(key) ?? "";
     }
   }
   _isElementDisabled(element) {
@@ -2608,9 +3143,18 @@ var ImageEditor = class {
    * @private
    */
   _setPlaceholderVisible(show) {
-    if (!this.placeholderElement || !this.containerElement) return;
-    this._setElementVisible(this.placeholderElement, show);
-    this._setElementVisible(this.containerElement, !show);
+    if (this.placeholderElement) this._setElementVisible(this.placeholderElement, show);
+    const canvasVisibilityElement = this._getCanvasVisibilityElement();
+    if (canvasVisibilityElement && canvasVisibilityElement !== this.placeholderElement) {
+      this._setElementVisible(canvasVisibilityElement, !show);
+    }
+  }
+  _getCanvasVisibilityElement() {
+    const wrapperElement = this.canvas && this.canvas.wrapperEl ? this.canvas.wrapperEl : null;
+    if (this.containerElement && this.placeholderElement && (this.containerElement === this.placeholderElement || this.containerElement.contains(this.placeholderElement))) {
+      return wrapperElement || this.canvasElement;
+    }
+    return this.containerElement || wrapperElement || this.canvasElement;
   }
   /**
    * Updates element visibility.
@@ -2622,9 +3166,34 @@ var ImageEditor = class {
    */
   _setElementVisible(element, isVisible) {
     if (!element) return;
+    this._rememberElementVisibility(element);
     element.hidden = !isVisible;
     element.setAttribute("aria-hidden", isVisible ? "false" : "true");
-    if (isVisible && element.classList) element.classList.remove("d-none");
+    if (element.classList) {
+      element.classList.toggle("d-none", !isVisible);
+    }
+  }
+  _rememberElementVisibility(element) {
+    if (!element || this._visibilityStateByElement.has(element)) return;
+    this._visibilityStateByElement.set(element, this._captureElementVisibility(element));
+  }
+  _captureElementVisibility(element) {
+    if (!element) return null;
+    return {
+      hidden: element.hidden,
+      ariaHidden: element.getAttribute("aria-hidden"),
+      className: element.className
+    };
+  }
+  _restoreElementVisibility(element, state) {
+    if (!element || !state) return;
+    element.hidden = !!state.hidden;
+    if (state.ariaHidden === null) {
+      element.removeAttribute("aria-hidden");
+    } else {
+      element.setAttribute("aria-hidden", state.ariaHidden);
+    }
+    element.className = state.className || "";
   }
   /**
    * Cleans up and disposes of the canvas and related references.
@@ -2632,10 +3201,17 @@ var ImageEditor = class {
    * @public
    */
   dispose() {
+    this._disposed = true;
+    this._rejectActiveAnimations(new Error("Editor disposed during animation"));
+    if (this.animationQueue) {
+      this.animationQueue.cancelAll(new Error("Editor disposed"));
+    }
+    this._isLoading = false;
+    this._activeOperationName = null;
+    this._activeOperationToken = null;
     try {
-      for (const key in this._handlersByElementKey || {}) {
-        const handlers = this._handlersByElementKey[key] || [];
-        const element = document.getElementById(this.elements[key]);
+      for (const [key, handlers] of Object.entries(this._handlersByElementKey || {})) {
+        const element = this._getElement(key);
         if (!element) continue;
         handlers.forEach((handlerRecord) => {
           try {
@@ -2656,9 +3232,28 @@ var ImageEditor = class {
       }
       this._cropRect = null;
     }
-    if (this.containerElement && this._containerOriginalOverflow !== void 0) {
+    if (this.containerElement && this._containerOriginalOverflow) {
+      try {
+        this._restoreContainerOverflowState();
+      } catch (error) {
+        void error;
+      }
+    }
+    if (this._visibilityStateByElement) {
+      try {
+        [this.placeholderElement, this._getCanvasVisibilityElement()].forEach((element) => {
+          const state = element ? this._visibilityStateByElement.get(element) : null;
+          if (state) this._restoreElementVisibility(element, state);
+        });
+      } catch (error) {
+        void error;
+      }
+    }
+    if (this.canvasElement && this._canvasElementOriginalStyle) {
       try {
-        this.containerElement.style.overflow = this._containerOriginalOverflow;
+        this.canvasElement.style.display = this._canvasElementOriginalStyle.display;
+        this.canvasElement.style.width = this._canvasElementOriginalStyle.width;
+        this.canvasElement.style.height = this._canvasElementOriginalStyle.height;
       } catch (error) {
         void error;
       }
@@ -2674,6 +3269,22 @@ var ImageEditor = class {
       this.isImageLoadedToCanvas = false;
     }
     this._handlersByElementKey = {};
+    this._elementCache = {};
+    this._elementOriginalPointerEvents = /* @__PURE__ */ new Map();
+    this._clearMaskPlacementMemory();
+    this.originalImage = null;
+    this.baseImageScale = 1;
+    this.currentScale = 1;
+    this.currentRotation = 0;
+    this.isAnimating = false;
+    this._isLoading = false;
+    this._cropMode = false;
+    this._cropRect = null;
+    this._cropHandlers = [];
+    this._cropPrevEvented = null;
+    this._prevSelectionSetting = void 0;
+    this._lastContainerViewportSize = null;
+    this._initialized = false;
   }
 };
 var AnimationQueue = class {
@@ -2683,6 +3294,8 @@ var AnimationQueue = class {
   constructor() {
     this.animationTasks = [];
     this.isRunning = false;
+    this.currentTask = null;
+    this._generation = 0;
   }
   /**
    * Adds an animation function to the queue.
@@ -2692,12 +3305,30 @@ var AnimationQueue = class {
    */
   async add(animationFn) {
     return new Promise((resolve, reject) => {
-      this.animationTasks.push({ animationFn, resolve, reject });
+      this.animationTasks.push({ animationFn, resolve, reject, isSettled: false });
       if (!this.isRunning) {
         this._drainQueue();
       }
     });
   }
+  isBusy() {
+    return this.isRunning || this.animationTasks.length > 0;
+  }
+  cancelAll(reason = new Error("Animation queue cancelled")) {
+    this._generation += 1;
+    const cancellationError = reason instanceof Error ? reason : new Error(String(reason));
+    const tasks = [
+      ...this.currentTask ? [this.currentTask] : [],
+      ...this.animationTasks.splice(0)
+    ];
+    tasks.forEach((task) => {
+      if (!task || task.isSettled) return;
+      task.isSettled = true;
+      task.reject(cancellationError);
+    });
+    this.isRunning = false;
+    this.currentTask = null;
+  }
   /**
    * Runs queued animation tasks sequentially until the queue is empty.
    *
@@ -2705,19 +3336,34 @@ var AnimationQueue = class {
    * @returns {Promise<void>}
    */
   async _drainQueue() {
-    if (this.animationTasks.length === 0) {
-      this.isRunning = false;
-      return;
-    }
+    if (this.isRunning) return;
+    const generation = this._generation;
     this.isRunning = true;
-    const { animationFn, resolve, reject } = this.animationTasks.shift();
     try {
-      const result = await animationFn();
-      resolve(result);
-    } catch (error) {
-      reject(error);
+      while (this.animationTasks.length > 0 && generation === this._generation) {
+        const task = this.animationTasks.shift();
+        this.currentTask = task;
+        try {
+          const result = await task.animationFn();
+          if (generation === this._generation && !task.isSettled) {
+            task.isSettled = true;
+            task.resolve(result);
+          }
+        } catch (error) {
+          if (generation === this._generation && !task.isSettled) {
+            task.isSettled = true;
+            task.reject(error);
+          }
+        } finally {
+          if (generation === this._generation && this.currentTask === task) this.currentTask = null;
+        }
+      }
+    } finally {
+      if (generation === this._generation) {
+        this.isRunning = false;
+        this.currentTask = null;
+      }
     }
-    await this._drainQueue();
   }
 };
 var Command = class {
@@ -2748,15 +3394,8 @@ var HistoryManager = class {
    * @private
    */
   enqueue(task) {
-    const nextTask = this.pending.then(task, task);
-    let pendingAfterTask;
-    const resetPending = () => {
-      if (this.pending === pendingAfterTask) {
-        this.pending = Promise.resolve();
-      }
-    };
-    pendingAfterTask = nextTask.then(resetPending, resetPending);
-    this.pending = pendingAfterTask;
+    const nextTask = this.pending.then(() => Promise.resolve().then(task));
+    this.pending = nextTask.catch(() => void 0);
     return nextTask;
   }
   /**
@@ -2767,8 +3406,14 @@ var HistoryManager = class {
    * @returns {void}
    */
   execute(command) {
-    command.execute();
+    const result = command.execute();
+    if (result && typeof result.then === "function") {
+      return Promise.resolve(result).then(() => {
+        this.push(command);
+      });
+    }
     this.push(command);
+    return result;
   }
   /**
    * Pushes an already-applied command onto the history stack.
@@ -2784,9 +3429,8 @@ var HistoryManager = class {
     this.history.push(command);
     if (this.history.length > this.maxSize) {
       this.history.shift();
-    } else {
-      this.currentIndex++;
     }
+    this.currentIndex = this.history.length - 1;
   }
   /**
    * Checks whether an undo operation is possible.