@bensitu/image-editor 1.3.0 → 1.4.0

package/dist/image-editor.js

@@ -3,19 +3,16 @@
   /**
    * @file image-editor.js
    * @module image-editor
-   * @version 1.3.0
+   * @version 1.4.0
    * @author Ben Situ
    * @license MIT
    * @description Lightweight canvas-based image editor with masking/transform/export support.
    */
   var fabric = null;
   function getGlobalScope() {
-    if (typeof globalThis !== "undefined")
-      return globalThis;
-    if (typeof self !== "undefined")
-      return self;
-    if (typeof window !== "undefined")
-      return window;
+    if (typeof globalThis !== "undefined") return globalThis;
+    if (typeof self !== "undefined") return self;
+    if (typeof window !== "undefined") return window;
     return null;
   }
   function getGlobalFabric() {
@@ -27,8 +24,7 @@
     return fabric;
   }
   function ensureFabric() {
-    if (!fabric)
-      setFabric();
+    if (!fabric) setFabric();
     return fabric;
   }
   var ImageEditor = class {
@@ -74,6 +70,8 @@
         downsampleMaxWidth: 4e3,
         downsampleMaxHeight: 3e3,
         downsampleQuality: 0.92,
+        preserveSourceFormat: true,
+        downsampleMimeType: null,
         imageLoadTimeoutMs: 3e4,
         exportMultiplier: 1,
         exportImageAreaByDefault: true,
@@ -122,6 +120,7 @@
       this.isImageLoadedToCanvas = false;
       this.maxHistorySize = 50;
       this._handlersByElementKey = {};
+      this._elementCache = {};
       this._lastMask = null;
       this._lastMaskInitialLeft = null;
       this._lastMaskInitialTop = null;
@@ -132,8 +131,14 @@
       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);
@@ -196,8 +201,17 @@
      * });
      */
     init(idMap = {}) {
-      if (!this._fabricLoaded)
-        return;
+      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._containerOriginalOverflow = null;
+      this._lastContainerViewportSize = null;
+      this._canvasElementOriginalStyle = null;
       const defaults = {
         canvas: "fabricCanvas",
         canvasContainer: null,
@@ -225,6 +239,7 @@
         cancelCropBtn: "cancelCropBtn"
       };
       this.elements = { ...defaults, ...idMap };
+      this._elementCache = {};
       this._initCanvas();
       this._bindEvents();
       this._updateInputs();
@@ -238,8 +253,7 @@
     }
     _reportError(message, error = null) {
       const handler = this.options && this.options.onError;
-      if (typeof handler !== "function")
-        return;
+      if (typeof handler !== "function") return;
       try {
         handler(error, message);
       } catch {
@@ -247,8 +261,7 @@
     }
     _reportWarning(message, error = null) {
       const handler = this.options && this.options.onWarning;
-      if (typeof handler !== "function")
-        return;
+      if (typeof handler !== "function") return;
       try {
         handler(error, message);
       } catch {
@@ -261,17 +274,22 @@
      * @private
      */
     _initCanvas() {
-      const canvasElement = document.getElementById(this.elements.canvas);
-      if (!canvasElement)
-        throw new Error("Canvas is not found: " + 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) {
@@ -280,6 +298,10 @@
         if (containerWidth > 0 && containerHeight > 0) {
           initialWidth = containerWidth;
           initialHeight = containerHeight;
+          this._lastContainerViewportSize = {
+            width: containerWidth,
+            height: containerHeight
+          };
         }
       }
       this.canvas = new fabric.Canvas(canvasElement, {
@@ -293,20 +315,34 @@
       this.canvas.on("selection:updated", (event) => this._handleSelectionChanged(event.selected));
       this.canvas.on("selection:cleared", () => this._handleSelectionChanged([]));
       this.canvas.on("object:moving", (event) => {
-        if (event.target && event.target.maskId)
-          this._syncMaskLabel(event.target);
+        if (event.target && event.target.maskId) this._syncMaskLabel(event.target);
       });
       this.canvas.on("object:scaling", (event) => {
-        if (event.target && event.target.maskId)
-          this._syncMaskLabel(event.target);
+        if (event.target && event.target.maskId) this._syncMaskLabel(event.target);
       });
       this.canvas.on("object:rotating", (event) => {
-        if (event.target && event.target.maskId)
-          this._syncMaskLabel(event.target);
+        if (event.target && event.target.maskId) this._syncMaskLabel(event.target);
       });
       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.
      *
@@ -316,11 +352,9 @@
      */
     _handleObjectModified(target) {
       const masks = this._getModifiedMasks(target);
-      if (!masks.length)
-        return;
+      if (!masks.length) return;
       masks.forEach((mask) => {
-        if (typeof mask.setCoords === "function")
-          mask.setCoords();
+        if (typeof mask.setCoords === "function") mask.setCoords();
         this._syncMaskLabel(mask);
       });
       this._expandCanvasToFitObjects(masks);
@@ -334,10 +368,8 @@
      * @private
      */
     _getModifiedMasks(target) {
-      if (!target)
-        return [];
-      if (target.maskId)
-        return [target];
+      if (!target) return [];
+      if (target.maskId) return [target];
       const objects = typeof target.getObjects === "function" ? target.getObjects() : [];
       return Array.isArray(objects) ? objects.filter((object) => object && object.maskId) : [];
     }
@@ -350,11 +382,8 @@
      * @private
      */
     _syncContainerOverflow(options = {}) {
-      if (!this.containerElement || !this.containerElement.style)
-        return;
-      if (this._containerOriginalOverflow === void 0) {
-        this._containerOriginalOverflow = this.containerElement.style.overflow || "";
-      }
+      if (!this.containerElement || !this.containerElement.style) return;
+      this._captureContainerOverflowState();
       const shouldPreserveScroll = options.preserveScroll === true;
       if (this.options.coverImageToCanvas) {
         this.containerElement.style.overflow = "scroll";
@@ -369,62 +398,77 @@
           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;
+    }
     /** 
      * DOM / UI bindings
      * @private
      */
     _bindEvents() {
       this._bindIfExists("uploadArea", "click", () => {
-        const uploadAreaElement = document.getElementById(this.elements.uploadArea);
-        if (this._isElementDisabled(uploadAreaElement))
-          return;
-        document.getElementById(this.elements.imageInput)?.click();
+        const uploadAreaElement = this._getElement("uploadArea");
+        if (this._isElementDisabled(uploadAreaElement)) return;
+        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;
+          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;
+          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.
@@ -435,12 +479,11 @@
      * @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 || {};
-        if (!this._handlersByElementKey[key])
-          this._handlersByElementKey[key] = [];
+        if (!this._handlersByElementKey[key]) this._handlersByElementKey[key] = [];
         this._handlersByElementKey[key].push({ eventName, handler });
       }
     }
@@ -448,17 +491,33 @@
      * 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.
@@ -472,8 +531,7 @@
         ["coverImageToCanvas", this.options.coverImageToCanvas],
         ["expandCanvasToImage", this.options.expandCanvasToImage]
       ].filter(([, isEnabled]) => !!isEnabled).map(([name]) => name);
-      if (activeModes.length <= 1)
-        return;
+      if (activeModes.length <= 1) return;
       this._reportWarning(
         `Only one image layout mode should be enabled. Active modes: ${activeModes.join(", ")}.`
       );
@@ -488,103 +546,98 @@
      * @public
      */
     async loadImage(imageBase64, options = {}) {
-      if (!this._fabricLoaded)
-        return;
-      if (!this.canvas)
-        return;
-      if (!imageBase64 || typeof imageBase64 !== "string" || !imageBase64.startsWith("data:image/"))
-        return;
+      if (!this._fabricLoaded) return;
+      if (!this.canvas || this._disposed) return;
+      if (!imageBase64 || typeof imageBase64 !== "string" || !imageBase64.startsWith("data:image/")) return;
+      this._assertIdleForOperation("loadImage");
       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.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;
       }
-      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.
@@ -609,8 +662,7 @@
         const safeTimeoutMs = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0 ? Number(timeoutMs) : 3e4;
         let timerId;
         const settle = (callback) => {
-          if (isSettled)
-            return;
+          if (isSettled) return;
           isSettled = true;
           clearTimeout(timerId);
           imageElement.onload = null;
@@ -622,6 +674,7 @@
           try {
             imageElement.src = "";
           } catch (error) {
+            void error;
           }
         }, safeTimeoutMs);
         imageElement.onload = () => settle(() => resolve(imageElement));
@@ -629,25 +682,132 @@
         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;
+      try {
+        if (transaction.canvasState) await this.loadFromState(transaction.canvasState);
+      } catch (error) {
+        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;
+      this._lastMaskInitialLeft = transaction.lastMaskInitialLeft;
+      this._lastMaskInitialTop = transaction.lastMaskInitialTop;
+      this._lastMaskInitialWidth = transaction.lastMaskInitialWidth;
+      this._containerOriginalOverflow = transaction.containerOverflow;
+      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._restoreContainerOverflowState();
+      }
+      this._updateInputs();
+      this._updateMaskList();
+      this._updateUI();
+      if (this.canvas) this.canvas.renderAll();
+    }
     /**
-     * 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");
+      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.
@@ -662,19 +822,16 @@
       const integerHeight = Math.max(1, Math.round(Number(height) || 1));
       this.canvas.setWidth(integerWidth);
       this.canvas.setHeight(integerHeight);
-      if (typeof this.canvas.calcOffset === "function")
-        this.canvas.calcOffset();
+      if (typeof this.canvas.calcOffset === "function") this.canvas.calcOffset();
       if (this.canvasElement) {
         this.canvasElement.style.width = integerWidth + "px";
         this.canvasElement.style.height = integerHeight + "px";
-        this.canvasElement.style.maxWidth = "none";
       }
     }
     _ceilCanvasDimension(value) {
       const numericValue = Number(value) || 0;
       const roundedValue = Math.round(numericValue);
-      if (Math.abs(numericValue - roundedValue) < 0.01)
-        return roundedValue;
+      if (Math.abs(numericValue - roundedValue) < 0.01) return roundedValue;
       return Math.ceil(numericValue);
     }
     _getContainerViewportSize() {
@@ -684,19 +841,36 @@
           height: Math.max(1, Math.floor(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: Math.max(1, Math.floor(this.containerElement.clientWidth || this.options.canvasWidth || 1)),
-          height: Math.max(1, Math.floor(this.containerElement.clientHeight || this.options.canvasHeight || 1))
-        };
+        return { width, height };
+      }
+      const overflow = this._getContainerOverflowValues();
+      const canScrollX = overflow.x.some((value) => value === "auto" || value === "scroll");
+      const canScrollY = overflow.y.some((value) => value === "auto" || value === "scroll");
+      const hasHorizontalScrollbar = canScrollX && this.containerElement.scrollWidth > this.containerElement.clientWidth;
+      const hasVerticalScrollbar = canScrollY && this.containerElement.scrollHeight > this.containerElement.clientHeight;
+      if (hasHorizontalScrollbar || hasVerticalScrollbar) {
+        const scrollbar = this._getScrollbarSize();
+        if (hasVerticalScrollbar) width += scrollbar.width;
+        if (hasHorizontalScrollbar) height += scrollbar.height;
       }
-      const width = Math.max(1, Math.floor(this.containerElement.clientWidth || this.options.canvasWidth || 1));
-      const height = Math.max(1, Math.floor(this.containerElement.clientHeight || this.options.canvasHeight || 1));
       return { width, height };
     }
-    _hasFixedContainerScrollbars() {
-      if (!this.containerElement)
-        return false;
+    /**
+     * Reads inline and computed overflow values for both scroll axes.
+     *
+     * @returns {{x:string[], y:string[]}} Overflow values grouped by axis.
+     * @private
+     */
+    _getContainerOverflowValues() {
+      if (!this.containerElement) return { x: [], y: [] };
       const inlineOverflow = this.containerElement.style.overflow;
       const inlineOverflowX = this.containerElement.style.overflowX;
       const inlineOverflowY = this.containerElement.style.overflowY;
@@ -709,7 +883,15 @@
         computedOverflowX = style.overflowX;
         computedOverflowY = style.overflowY;
       }
-      return [inlineOverflow, inlineOverflowX, inlineOverflowY, computedOverflow, computedOverflowX, computedOverflowY].some((value) => value === "scroll");
+      return {
+        x: [inlineOverflow, inlineOverflowX, computedOverflow, computedOverflowX],
+        y: [inlineOverflow, inlineOverflowY, computedOverflow, computedOverflowY]
+      };
+    }
+    _hasFixedContainerScrollbars() {
+      if (!this.containerElement) return false;
+      const overflow = this._getContainerOverflowValues();
+      return [...overflow.x, ...overflow.y].some((value) => value === "scroll");
     }
     _getScrollbarSize() {
       if (this._scrollbarSizeCache) {
@@ -752,15 +934,14 @@
       const scrollbar = this._getScrollbarSize();
       let hasVertical = false;
       let hasHorizontal = false;
-      let effectiveWidth = viewport.width;
-      let effectiveHeight = viewport.height;
+      let effectiveWidth;
+      let effectiveHeight;
       for (let i = 0; i < 4; i += 1) {
         effectiveWidth = Math.max(1, viewport.width - (hasVertical ? scrollbar.width : 0));
         effectiveHeight = Math.max(1, viewport.height - (hasHorizontal ? scrollbar.height : 0));
         const nextHasVertical = contentHeight > effectiveHeight + 0.5;
         const nextHasHorizontal = contentWidth > effectiveWidth + 0.5;
-        if (nextHasVertical === hasVertical && nextHasHorizontal === hasHorizontal)
-          break;
+        if (nextHasVertical === hasVertical && nextHasHorizontal === hasHorizontal) break;
         hasVertical = nextHasVertical;
         hasHorizontal = nextHasHorizontal;
       }
@@ -797,8 +978,8 @@
       let scale = 1;
       let contentWidth = imageWidth;
       let contentHeight = imageHeight;
-      let effectiveWidth = viewport.width;
-      let effectiveHeight = viewport.height;
+      let effectiveWidth;
+      let effectiveHeight;
       for (let i = 0; i < 4; i += 1) {
         effectiveWidth = Math.max(1, viewport.width - (hasVertical ? scrollbar.width : 0));
         effectiveHeight = Math.max(1, viewport.height - (hasHorizontal ? scrollbar.height : 0));
@@ -807,8 +988,7 @@
         contentHeight = imageHeight * scale;
         const nextHasVertical = contentHeight > effectiveHeight + 0.5;
         const nextHasHorizontal = contentWidth > effectiveWidth + 0.5;
-        if (nextHasVertical === hasVertical && nextHasHorizontal === hasHorizontal)
-          break;
+        if (nextHasVertical === hasVertical && nextHasHorizontal === hasHorizontal) break;
         hasVertical = nextHasVertical;
         hasHorizontal = nextHasHorizontal;
       }
@@ -847,41 +1027,48 @@
         stroke: mask && mask.originalStroke || "#ccc",
         strokeWidth: Number.isFinite(strokeWidth) ? strokeWidth : 1
       };
-      if (Number.isFinite(opacity))
-        style.opacity = opacity;
+      if (Number.isFinite(opacity)) style.opacity = opacity;
       return style;
     }
     _withNormalizedMaskStyles(callback) {
-      if (!this.canvas)
-        return callback();
+      if (!this.canvas) return callback();
       const masks = this.canvas.getObjects().filter((object) => object.maskId);
-      const maskStyleBackups = masks.map((mask) => ({
-        object: mask,
-        stroke: mask.stroke,
-        strokeWidth: mask.strokeWidth,
-        opacity: mask.opacity
-      }));
+      const maskStyleBackups = [];
       try {
         masks.forEach((mask) => {
-          mask.set(this._getMaskNormalStyle(mask));
+          const normalStyle = this._getMaskNormalStyle(mask);
+          const stylePatch = {};
+          Object.keys(normalStyle).forEach((property) => {
+            if (mask[property] !== normalStyle[property]) {
+              stylePatch[property] = normalStyle[property];
+            }
+          });
+          const changedProperties = Object.keys(stylePatch);
+          if (!changedProperties.length) return;
+          const backup = { object: mask };
+          changedProperties.forEach((property) => {
+            backup[property] = mask[property];
+          });
+          maskStyleBackups.push(backup);
+          mask.set(stylePatch);
         });
         return callback();
       } finally {
         maskStyleBackups.forEach((backup) => {
           try {
-            backup.object.set({
-              stroke: backup.stroke,
-              strokeWidth: backup.strokeWidth,
-              opacity: backup.opacity
+            const restorePatch = {};
+            Object.keys(backup).forEach((property) => {
+              if (property !== "object") restorePatch[property] = backup[property];
             });
+            backup.object.set(restorePatch);
           } catch (error) {
+            void error;
           }
         });
       }
     }
     _restoreMaskControls(mask) {
-      if (!mask)
-        return;
+      if (!mask) return;
       const cornerSize = Number(mask.cornerSize);
       mask.set({
         selectable: mask.selectable !== false,
@@ -894,8 +1081,7 @@
         transparentCorners: mask.transparentCorners === true,
         strokeUniform: mask.strokeUniform !== false
       });
-      if (typeof mask.setCoords === "function")
-        mask.setCoords();
+      if (typeof mask.setCoords === "function") mask.setCoords();
     }
     /**
      * Captures editor-owned runtime state that Fabric does not include in canvas JSON.
@@ -917,8 +1103,7 @@
       };
     }
     _serializeCanvasState() {
-      if (!this.canvas)
-        return null;
+      if (!this.canvas) return null;
       return this._withNormalizedMaskStyles(() => {
         const jsonObject = this.canvas.toJSON(this._getStateProperties());
         if (Array.isArray(jsonObject.objects)) {
@@ -937,8 +1122,7 @@
      */
     _normalizeQuality(quality) {
       const numericQuality = Number(quality);
-      if (!Number.isFinite(numericQuality))
-        return this.options.downsampleQuality ?? 0.92;
+      if (!Number.isFinite(numericQuality)) return this.options.downsampleQuality ?? 0.92;
       return Math.max(0, Math.min(1, numericQuality));
     }
     /**
@@ -1011,8 +1195,7 @@
         const safeTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 3e4;
         let timerId;
         const settle = (callback) => {
-          if (isSettled)
-            return;
+          if (isSettled) return;
           isSettled = true;
           clearTimeout(timerId);
           imageElement.onload = null;
@@ -1024,6 +1207,7 @@
           try {
             imageElement.src = "";
           } catch (error) {
+            void error;
           }
         }, safeTimeoutMs);
         imageElement.onload = () => {
@@ -1037,8 +1221,7 @@
             offscreenCanvas.width = scaledSourceWidth;
             offscreenCanvas.height = scaledSourceHeight;
             const context = offscreenCanvas.getContext("2d");
-            if (!context)
-              throw new Error("2D canvas context is unavailable");
+            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) {
@@ -1050,7 +1233,7 @@
       });
     }
     /**
-     * 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.
@@ -1063,14 +1246,17 @@
      * @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" }) {
+    _exportCanvasRegionToDataURL({ sourceX, sourceY, sourceWidth, sourceHeight, multiplier = 1, quality = 0.92, format = "jpeg" }) {
       const safeMultiplier = Math.max(1, Number(multiplier) || 1);
-      const fullDataUrl = this.canvas.toDataURL({
+      return this.canvas.toDataURL({
         format,
         quality,
-        multiplier: safeMultiplier
+        multiplier: safeMultiplier,
+        left: sourceX,
+        top: sourceY,
+        width: sourceWidth,
+        height: sourceHeight
       });
-      return this._cropDataUrl(fullDataUrl, sourceX, sourceY, sourceWidth, sourceHeight, safeMultiplier, format, quality);
     }
     /** 
      * Gets the top-left corner coordinates of the given object.
@@ -1081,15 +1267,39 @@
      * @private
      */
     _getObjectTopLeftPoint(fabricObject) {
-      if (!fabricObject)
-        return { x: 0, y: 0 };
+      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.
      * 
@@ -1100,8 +1310,7 @@
      * @private
      */
     _setObjectOriginKeepingPosition(fabricObject, originX, originY, refPoint) {
-      if (!fabricObject || !refPoint || !fabricObject.setPositionByOrigin)
-        return;
+      if (!fabricObject || !refPoint || !fabricObject.setPositionByOrigin) return;
       fabricObject.set({ originX, originY });
       fabricObject.setPositionByOrigin(refPoint, originX, originY);
       fabricObject.setCoords();
@@ -1113,8 +1322,7 @@
      * @private
      */
     _alignObjectBoundingBoxToCanvasTopLeft(fabricObject) {
-      if (!fabricObject)
-        return;
+      if (!fabricObject) return;
       fabricObject.setCoords();
       const boundingRect = fabricObject.getBoundingRect(true, true);
       const deltaX = boundingRect.left;
@@ -1129,8 +1337,7 @@
      * @private
      */
     _updateCanvasSizeToImageBounds() {
-      if (!this.originalImage)
-        return;
+      if (!this.originalImage) return;
       this.originalImage.setCoords();
       const imageBounds = this.originalImage.getBoundingRect(true, true);
       const size = this._getScrollableCanvasSize(imageBounds.width, imageBounds.height);
@@ -1154,25 +1361,34 @@
      * @private
      */
     _expandCanvasToFitObjects(fabricObjects, padding = 10) {
-      if (!this.canvas || !Array.isArray(fabricObjects) || !fabricObjects.length || !this._shouldResizeCanvasToContentBounds())
-        return;
+      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();
+          if (!fabricObject) return;
+          if (typeof fabricObject.setCoords === "function") fabricObject.setCoords();
           const boundingRect = fabricObject.getBoundingRect(true, true);
           requiredWidth = Math.max(requiredWidth, Math.ceil(boundingRect.left + boundingRect.width + padding));
           requiredHeight = Math.max(requiredHeight, Math.ceil(boundingRect.top + boundingRect.height + padding));
         });
-        const minWidth = this.containerElement ? Math.floor(this.containerElement.clientWidth || 0) : 0;
-        const minHeight = this.containerElement ? Math.floor(this.containerElement.clientHeight || 0) : 0;
-        const newWidth = Math.max(this.canvas.getWidth(), minWidth, requiredWidth);
-        const newHeight = Math.max(this.canvas.getHeight(), minHeight, requiredHeight);
-        if (newWidth !== this.canvas.getWidth() || newHeight !== this.canvas.getHeight()) {
+        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) {
@@ -1200,6 +1416,66 @@
     scaleImage(factor, options = {}) {
       return this.animationQueue.add(() => this._scaleImageImpl(factor, options));
     }
+    _assertIdleForOperation(operationName) {
+      if (this._disposed || !this.canvas) throw new Error(`${operationName} cannot run after the editor has been disposed`);
+      if (this.isAnimating || this.animationQueue && this.animationQueue.isBusy()) {
+        throw new Error(`${operationName} cannot run while an animation is running`);
+      }
+    }
+    _canMutateNow(operationName) {
+      try {
+        this._assertIdleForOperation(operationName);
+        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.
      * Returns a promise that resolves when the scale animation is complete.
@@ -1207,34 +1483,25 @@
      * @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()) {
@@ -1242,18 +1509,17 @@
         }
         this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
         this.canvas.getObjects().forEach((object) => {
-          if (object.maskId)
-            this._syncMaskLabel(object);
+          if (object.maskId) this._syncMaskLabel(object);
         });
-        this.isAnimating = false;
         this._updateInputs();
-        this._updateUI();
-        if (saveHistory)
-          this.saveState();
-      }).catch(() => {
-        this.isAnimating = false;
-        this._updateUI();
-      });
+        if (saveHistory) this.saveState();
+      } finally {
+        if (didStartAnimation) {
+          this.isAnimating = false;
+          this._updateInputs();
+          this._updateUI();
+        }
+      }
     }
     /** 
      * Rotates the original image by a given number of degrees, with animation.
@@ -1272,48 +1538,50 @@
      * @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);
+          if (object.maskId) this._syncMaskLabel(object);
         });
-        this.isAnimating = false;
         this._updateInputs();
-        this._updateUI();
-        if (saveHistory)
-          this.saveState();
-      }).catch(() => {
-        this.isAnimating = false;
-        this._updateUI();
-      });
+        if (saveHistory) this.saveState();
+        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.
@@ -1322,16 +1590,16 @@
      * @public
      */
     resetImageTransform() {
-      if (!this.originalImage)
-        return Promise.resolve();
+      if (!this.originalImage) return Promise.resolve();
       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);
       }).catch((error) => {
         this._reportError("resetImageTransform() failed", error);
+        throw error;
       });
     }
     /**
@@ -1351,14 +1619,31 @@
      * @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;
@@ -1406,18 +1691,44 @@
               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);
+          imageElement.onload = null;
+          imageElement.onerror = null;
+          callback();
+        };
+        imageElement.onload = () => settle(resolve);
+        imageElement.onerror = (error) => settle(() => reject(error));
+      });
+    }
     /**
      * Saves the current editable canvas state as an undoable history transition.
      *
@@ -1428,14 +1739,11 @@
      * @public
      */
     saveState() {
-      if (!this.canvas)
-        return;
-      const activeObject = this.canvas.getActiveObject();
+      if (!this.canvas) return;
       try {
-        const after = this._serializeCanvasState();
+        const after = this._captureCanvasStateOrThrow("saveState");
         const before = this._lastSnapshot || after;
-        if (after === before)
-          return;
+        if (after === before) return;
         let executedOnce = false;
         const command = new Command(
           () => {
@@ -1452,9 +1760,6 @@
       } 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();
       }
     }
@@ -1470,12 +1775,12 @@
      * @private
      */
     _pushStateTransition(before, after) {
-      if (!before || !after)
-        return;
-      if (before === after)
+      if (!before || !after) {
+        this._reportWarning("History transition skipped because a canvas snapshot is unavailable");
         return;
-      if (!this.historyManager)
-        this.historyManager = new HistoryManager(this.maxHistorySize || 50);
+      }
+      if (before === after) return;
+      if (!this.historyManager) this.historyManager = new HistoryManager(this.maxHistorySize || 50);
       const command = new Command(
         () => this.loadFromState(after),
         () => this.loadFromState(before)
@@ -1495,6 +1800,7 @@
         this._updateUI();
       }).catch((error) => {
         this._reportError("undo failed", error);
+        throw error;
       });
     }
     /**
@@ -1508,48 +1814,40 @@
         this._updateUI();
       }).catch((error) => {
         this._reportError("redo failed", error);
+        throw error;
       });
     }
     _rebindMaskEvents(mask) {
-      if (!mask)
-        return;
+      if (!mask) return;
       if (mask.__imageEditorMaskHandlers) {
         try {
           mask.off("mouseover", mask.__imageEditorMaskHandlers.mouseover);
           mask.off("mouseout", mask.__imageEditorMaskHandlers.mouseout);
         } catch (error) {
+          void error;
         }
       }
       const metadata = {};
       if (!Number.isFinite(Number(mask.originalAlpha))) {
         metadata.originalAlpha = Number.isFinite(Number(mask.opacity)) ? Number(mask.opacity) : 0.5;
       }
-      if (!mask.originalStroke)
-        metadata.originalStroke = mask.stroke || "#ccc";
+      if (!mask.originalStroke) metadata.originalStroke = mask.stroke || "#ccc";
       if (!Number.isFinite(Number(mask.originalStrokeWidth))) {
         metadata.originalStrokeWidth = Number.isFinite(Number(mask.strokeWidth)) ? Number(mask.strokeWidth) : 1;
       }
-      if (Object.keys(metadata).length)
-        mask.set(metadata);
-      const normalStyle = {
-        stroke: mask.originalStroke || "#ccc",
-        strokeWidth: mask.originalStrokeWidth,
-        opacity: mask.originalAlpha
-      };
-      const hoverStyle = {
-        stroke: "#ff5500",
-        strokeWidth: 2,
-        opacity: Math.min(mask.originalAlpha + 0.2, 1)
-      };
+      if (Object.keys(metadata).length) mask.set(metadata);
       const mouseover = () => {
-        mask.set(hoverStyle);
-        if (mask.canvas)
-          mask.canvas.requestRenderAll();
+        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);
-        if (mask.canvas)
-          mask.canvas.requestRenderAll();
+        mask.set(this._getMaskNormalStyle(mask));
+        if (mask.canvas) mask.canvas.requestRenderAll();
       };
       mask.on("mouseover", mouseover);
       mask.on("mouseout", mouseout);
@@ -1584,8 +1882,8 @@
      * @public
      */
     createMask(config = {}) {
-      if (!this.canvas)
-        return null;
+      if (!this.canvas) return null;
+      if (!this._canMutateNow("createMask")) return null;
       const shapeType = config.shape || "rect";
       const maskConfig = {
         shape: shapeType,
@@ -1601,33 +1899,37 @@
         ...config
       };
       const firstOffset = 10;
-      let left = firstOffset;
-      let top = firstOffset;
-      const resolveValue = (value, fallback) => {
+      let left;
+      let top;
+      const getCanvasBasis = (axis) => {
+        const canvasWidth = this.canvas ? this.canvas.getWidth() : 0;
+        const canvasHeight = this.canvas ? this.canvas.getHeight() : 0;
+        if (axis === "height") return canvasHeight;
+        if (axis === "min") return Math.min(canvasWidth, canvasHeight);
+        return canvasWidth;
+      };
+      const resolveValue = (value, fallback, axis = "width") => {
         if (typeof value === "function")
           return value(this.canvas, this.options);
         if (typeof value === "string" && value.endsWith("%")) {
-          const percent = parseFloat(value) / 100;
-          return Math.floor((this.canvas ? this.canvas.getWidth() : 0) * percent);
+          const percent = Number.parseFloat(value) / 100;
+          if (!Number.isFinite(percent)) return fallback;
+          return Math.floor(getCanvasBasis(axis) * percent);
         }
         return value != null ? value : fallback;
       };
       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);
-        top = resolveValue(maskConfig.top, firstOffset);
+        left = resolveValue(maskConfig.left, firstOffset, "width");
+        top = resolveValue(maskConfig.top, firstOffset, "height");
       }
-      maskConfig.width = resolveValue(maskConfig.width, this.options.defaultMaskWidth);
-      maskConfig.height = resolveValue(maskConfig.height, this.options.defaultMaskHeight);
+      maskConfig.width = resolveValue(maskConfig.width, this.options.defaultMaskWidth, "width");
+      maskConfig.height = resolveValue(maskConfig.height, this.options.defaultMaskHeight, "height");
       maskConfig.left = left;
       maskConfig.top = top;
       let mask;
@@ -1639,7 +1941,7 @@
             mask = new fabric.Circle({
               left,
               top,
-              radius: resolveValue(maskConfig.radius, Math.min(maskConfig.width, maskConfig.height) / 2),
+              radius: resolveValue(maskConfig.radius, Math.min(maskConfig.width, maskConfig.height) / 2, "min"),
               fill: maskConfig.color,
               opacity: maskConfig.alpha,
               angle: maskConfig.angle,
@@ -1650,8 +1952,8 @@
             mask = new fabric.Ellipse({
               left,
               top,
-              rx: resolveValue(maskConfig.rx, maskConfig.width / 2),
-              ry: resolveValue(maskConfig.ry, maskConfig.height / 2),
+              rx: resolveValue(maskConfig.rx, maskConfig.width / 2, "width"),
+              ry: resolveValue(maskConfig.ry, maskConfig.height / 2, "height"),
               fill: maskConfig.color,
               opacity: maskConfig.alpha,
               angle: maskConfig.angle,
@@ -1678,8 +1980,8 @@
             mask = new fabric.Rect({
               left,
               top,
-              width: resolveValue(maskConfig.width, this.options.defaultMaskWidth),
-              height: resolveValue(maskConfig.height, this.options.defaultMaskHeight),
+              width: resolveValue(maskConfig.width, this.options.defaultMaskWidth, "width"),
+              height: resolveValue(maskConfig.height, this.options.defaultMaskHeight, "height"),
               fill: maskConfig.color,
               opacity: maskConfig.alpha,
               angle: maskConfig.angle,
@@ -1704,8 +2006,7 @@
         opacity: hasStyle("opacity") ? styles.opacity : maskConfig.alpha,
         strokeUniform: "strokeUniform" in maskConfig ? maskConfig.strokeUniform : hasStyle("strokeUniform") ? styles.strokeUniform : true
       };
-      if (hasStyle("strokeDashArray"))
-        maskSettings.strokeDashArray = styles.strokeDashArray;
+      if (hasStyle("strokeDashArray")) maskSettings.strokeDashArray = styles.strokeDashArray;
       mask.set(maskSettings);
       mask.setCoords();
       mask.set({
@@ -1717,7 +2018,7 @@
       this._expandCanvasToFitObject(mask);
       this._lastMaskInitialLeft = left;
       this._lastMaskInitialTop = top;
-      this._lastMaskInitialWidth = resolveValue(maskConfig.width, this.options.defaultMaskWidth);
+      this._lastMaskInitialWidth = resolveValue(maskConfig.width, this.options.defaultMaskWidth, "width");
       const maskId = ++this.maskCounter;
       mask.set({
         maskId,
@@ -1726,15 +2027,13 @@
       this._lastMask = mask;
       this.canvas.add(mask);
       this.canvas.bringToFront(mask);
-      if (maskConfig.selectable)
-        this.canvas.setActiveObject(mask);
+      if (maskConfig.selectable) this.canvas.setActiveObject(mask);
       this._handleSelectionChanged([mask]);
       this._updateMaskList();
       this._updateUI();
       this.canvas.renderAll();
       this.saveState();
-      if (typeof maskConfig.onCreate === "function")
-        maskConfig.onCreate(mask, this.canvas);
+      if (typeof maskConfig.onCreate === "function") maskConfig.onCreate(mask, this.canvas);
       return mask;
     }
     /**
@@ -1752,10 +2051,11 @@
      * 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;
+      if (!selectedMasks.length) return;
       this.canvas.discardActiveObject();
       selectedMasks.forEach((mask) => {
         this._removeLabelForMask(mask);
@@ -1778,6 +2078,8 @@
      * UI and internal mask placement memory are reset.
      */
     removeAllMasks(options = {}) {
+      if (!this.canvas) return;
+      if (!this._canMutateNow("removeAllMasks")) return;
       const saveHistory = options.saveHistory !== false;
       const masks = this.canvas.getObjects().filter((object) => object.maskId);
       masks.forEach((mask) => this._removeLabelForMask(mask));
@@ -1790,8 +2092,7 @@
       this._updateMaskList();
       this._updateUI();
       this.canvas.renderAll();
-      if (saveHistory)
-        this.saveState();
+      if (saveHistory) this.saveState();
     }
     /**
      * Removes the label associated with the specified mask object, if it exists.
@@ -1800,8 +2101,7 @@
      * @private
      */
     _removeLabelForMask(mask) {
-      if (!mask || !this.canvas)
-        return;
+      if (!mask || !this.canvas) return;
       if (mask.__label) {
         try {
           const canvasObjects = this.canvas.getObjects();
@@ -1809,10 +2109,12 @@
             this.canvas.remove(mask.__label);
           }
         } catch (error) {
+          void error;
         }
         try {
           delete mask.__label;
         } catch (error) {
+          void error;
         }
       }
     }
@@ -1828,8 +2130,7 @@
      */
     _getMaskCreationIndex(mask) {
       const maskId = Number(mask && mask.maskId);
-      if (Number.isFinite(maskId) && maskId > 0)
-        return Math.floor(maskId) - 1;
+      if (Number.isFinite(maskId) && maskId > 0) return Math.floor(maskId) - 1;
       const masks = this.canvas ? this.canvas.getObjects().filter((object) => object.maskId) : [];
       return Math.max(0, masks.indexOf(mask));
     }
@@ -1841,12 +2142,15 @@
      * @private
      */
     _createLabelForMask(mask) {
-      if (!mask || !this.options.maskLabelOnSelect)
-        return;
+      if (!mask || !this.options.maskLabelOnSelect) return;
       this._removeLabelForMask(mask);
       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;
@@ -1884,15 +2188,14 @@
      * @private
      */
     _hideAllMaskLabels() {
-      if (!this.canvas)
-        return;
+      if (!this.canvas) return;
       const canvasObjects = this.canvas.getObjects();
       const labels = canvasObjects.filter((object) => object.maskLabel);
       labels.forEach((label) => {
         try {
-          if (canvasObjects.includes(label))
-            this.canvas.remove(label);
+          if (canvasObjects.includes(label)) this.canvas.remove(label);
         } catch (error) {
+          void error;
         }
       });
       canvasObjects.forEach((object) => {
@@ -1900,6 +2203,7 @@
           try {
             delete object.__label;
           } catch (error) {
+            void error;
           }
         }
       });
@@ -1911,16 +2215,13 @@
      * @private
      */
     _syncMaskLabel(mask) {
-      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 (!mask) return;
+      if (!this.options.maskLabelOnSelect) return;
+      if (!mask.__label) return;
+      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;
@@ -1952,12 +2253,9 @@
      * @private
      */
     _showLabelForMask(mask) {
-      if (!mask)
-        return;
-      if (!this.options.maskLabelOnSelect)
-        return;
-      if (!mask.__label)
-        this._createLabelForMask(mask);
+      if (!mask) return;
+      if (!this.options.maskLabelOnSelect) return;
+      if (!mask.__label) this._createLabelForMask(mask);
       mask.__label.set({ visible: true });
       this._syncMaskLabel(mask);
     }
@@ -1977,6 +2275,7 @@
             try {
               this.canvas.remove(mask.__label);
             } catch (error) {
+              void error;
             }
             delete mask.__label;
           }
@@ -1989,8 +2288,7 @@
           mask.set({ stroke: "#ff0000", strokeWidth: 1 });
         }
       });
-      if (selectedMask)
-        this._showLabelForMask(selectedMask);
+      if (selectedMask) this._showLabelForMask(selectedMask);
       this._updateMaskListSelection(selectedMask);
       this.canvas.renderAll();
       this._updateUI();
@@ -2001,22 +2299,28 @@
      * @private
      */
     _updateMaskList() {
-      const maskListElement = document.getElementById(this.elements.maskList);
-      if (!maskListElement)
-        return;
+      const maskListElement = this._getElement("maskList");
+      if (!maskListElement) return;
       maskListElement.innerHTML = "";
       const masks = this.canvas.getObjects().filter((object) => object.maskId);
       masks.forEach((mask) => {
         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.
      * 
@@ -2024,13 +2328,13 @@
      * @private
      */
     _updateMaskListSelection(selectedMask) {
-      const maskListElement = document.getElementById(this.elements.maskList);
-      if (!maskListElement)
-        return;
+      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);
       });
     }
     /**
@@ -2044,22 +2348,22 @@
      * @public
      */
     async mergeMasks() {
-      if (!this.originalImage)
-        return;
+      if (!this.originalImage) return;
+      this._assertIdleForOperation("mergeMasks");
       const masks = this.canvas.getObjects().filter((object) => object.maskId);
-      if (!masks.length)
-        return;
+      if (!masks.length) return;
       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 });
+        await this.loadImage(merged, { preserveScroll: true, resetMaskCounter: false });
         const afterJson = this._serializeCanvasState();
         this._pushStateTransition(beforeJson, afterJson);
       } catch (error) {
         this._reportError("merge error", error);
+        throw error;
       }
     }
     /**
@@ -2080,8 +2384,8 @@
      * @public
      */
     downloadImage(fileName = this.options.defaultDownloadFileName) {
-      if (!this.originalImage)
-        return;
+      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");
@@ -2109,8 +2413,8 @@
      * @public
      */
     async exportImageBase64(options = {}) {
-      if (!this.originalImage)
-        throw new Error("No image loaded");
+      if (!this.originalImage) throw new Error("No image loaded");
+      this._assertIdleForOperation("exportImageBase64");
       const exportImageArea = typeof options.exportImageArea === "boolean" ? options.exportImageArea : this.options.exportImageAreaByDefault;
       const multiplier = options.multiplier || this.options.exportMultiplier || 1;
       const quality = this._normalizeQuality(options.quality ?? this.options.downsampleQuality);
@@ -2127,7 +2431,7 @@
           this.originalImage.setCoords();
           const imageBounds = this.originalImage.getBoundingRect(true, true);
           const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
-          return await this._exportCanvasRegionToDataURL({
+          return this._exportCanvasRegionToDataURL({
             ...exportRegion,
             multiplier,
             quality,
@@ -2138,6 +2442,7 @@
             try {
               backup.object.set({ visible: backup.visible });
             } catch (error) {
+              void error;
             }
           });
           this.canvas.renderAll();
@@ -2166,7 +2471,7 @@
         this.originalImage.setCoords();
         const imageBounds = this.originalImage.getBoundingRect(true, true);
         const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
-        finalBase64 = await this._exportCanvasRegionToDataURL({
+        finalBase64 = this._exportCanvasRegionToDataURL({
           ...exportRegion,
           multiplier,
           quality,
@@ -2185,6 +2490,7 @@
             });
             backup.object.setCoords();
           } catch (error) {
+            void error;
           }
         });
         this.canvas.renderAll();
@@ -2220,8 +2526,8 @@
      *   const file = await this.exportImageFile({ mergeMask: false, fileType: 'png' });
      */
     async exportImageFile(options = {}) {
-      if (!this.originalImage)
-        throw new Error("No image loaded");
+      if (!this.originalImage) throw new Error("No image loaded");
+      this._assertIdleForOperation("exportImageFile");
       const {
         mergeMask = true,
         fileType = "jpeg",
@@ -2257,6 +2563,7 @@
               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);
               resolve(convertedDataUrl);
@@ -2285,8 +2592,7 @@
     }
     async _restoreStateAfterCropFailure(beforeJson, message, error) {
       this._reportError(message, error);
-      if (this._cropRect && this.canvas)
-        this._removeCropRect();
+      if (this._cropRect && this.canvas) this._removeCropRect();
       this._cropRect = null;
       this._cropMode = false;
       if (this.canvas && this._prevSelectionSetting !== void 0) {
@@ -2301,8 +2607,7 @@
         }
       }
       this._updateUI();
-      if (this.canvas)
-        this.canvas.renderAll();
+      if (this.canvas) this.canvas.renderAll();
     }
     _restoreCropObjectState() {
       if (Array.isArray(this._cropPrevEvented)) {
@@ -2314,27 +2619,31 @@
               visible: state.visible
             });
           } catch (error) {
+            void error;
           }
         });
       }
       this._cropPrevEvented = null;
     }
     _removeCropRect() {
-      if (!this._cropRect)
-        return;
+      if (!this._cropRect) return;
       try {
         if (this._cropHandlers && this._cropHandlers.length) {
           this._cropHandlers.forEach((targetHandlers) => {
             targetHandlers.handlers.forEach((handlerRecord) => {
-              targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
+              if (targetHandlers.target && typeof targetHandlers.target.off === "function") {
+                targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
+              }
             });
           });
         }
       } catch (error) {
+        void error;
       }
       try {
-        this.canvas.remove(this._cropRect);
+        if (this.canvas) this.canvas.remove(this._cropRect);
       } catch (error) {
+        void error;
       }
       this._cropRect = null;
       this._cropHandlers = [];
@@ -2349,10 +2658,10 @@
      * @public
      */
     enterCropMode() {
-      if (!this.canvas || !this.originalImage || this._cropMode)
-        return;
-      if (!this.isImageLoaded())
-        return;
+      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;
@@ -2404,10 +2713,10 @@
               evented: false,
               selectable: false
             };
-            if (shouldHideMasks && (object.maskId || object.maskLabel))
-              updates.visible = false;
+            if (shouldHideMasks && (object.maskId || object.maskLabel)) updates.visible = false;
             object.set(updates);
           } catch (error) {
+            void error;
           }
         }
       });
@@ -2421,6 +2730,7 @@
           cropRect.setCoords();
           this.canvas.requestRenderAll();
         } catch (error) {
+          void error;
         }
       };
       cropRect.on("modified", handleCropRectModified);
@@ -2444,8 +2754,7 @@
      * @public
      */
     cancelCrop() {
-      if (!this.canvas || !this._cropMode)
-        return;
+      if (!this.canvas || !this._cropMode) return;
       this._removeCropRect();
       this._restoreCropObjectState();
       this._cropMode = false;
@@ -2467,14 +2776,14 @@
      * @public
      */
     async applyCrop() {
-      if (!this.canvas || !this._cropMode || !this._cropRect)
-        return;
+      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);
+      const cropRegion = this._getClampedCanvasRegion(rectBounds, { includePartialPixels: false });
       const shouldPreserveMasks = !!(this.options.crop && this.options.crop.preserveMasksAfterCrop);
       this._restoreCropObjectState();
-      let beforeJson = null;
+      let beforeJson;
       try {
         beforeJson = this._serializeCanvasState();
       } catch (error) {
@@ -2493,12 +2802,8 @@
               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) {
@@ -2529,7 +2834,7 @@
         return;
       }
       try {
-        await this.loadImage(croppedBase64);
+        await this.loadImage(croppedBase64, { resetMaskCounter: false });
         if (preservedMasks.length) {
           preservedMasks.forEach((mask) => {
             this._rebindMaskEvents(mask);
@@ -2545,9 +2850,9 @@
         await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: loadImage(croppedBase64) failed", error);
         return;
       }
-      let afterJson = null;
+      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;
@@ -2567,9 +2872,8 @@
      * @private
      */
     _updateInputs() {
-      const scaleInputElement = document.getElementById(this.elements.scaleRate);
-      if (scaleInputElement)
-        scaleInputElement.value = Math.round(this.currentScale * 100);
+      const scaleInputElement = this._getElement("scaleRate");
+      if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
     }
     /**
      * Updates the enabled/disabled state of various UI controls (buttons)
@@ -2577,6 +2881,7 @@
      * @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;
@@ -2588,9 +2893,8 @@
       const isInCropMode = !!this._cropMode;
       if (isInCropMode) {
         for (const key of Object.keys(this.elements || {})) {
-          const element = document.getElementById(this.elements[key]);
-          if (!element)
-            continue;
+          const element = this._getElement(key);
+          if (!element) continue;
           if (key === "applyCropBtn" || key === "cancelCropBtn") {
             this._setDisabled(key, false);
           } else {
@@ -2625,9 +2929,8 @@
      * @private
      */
     _setDisabled(key, disabled) {
-      const element = document.getElementById(this.elements[key]);
-      if (!element)
-        return;
+      const element = this._getElement(key);
+      if (!element) return;
       if ("disabled" in element) {
         element.disabled = !!disabled;
         return;
@@ -2641,10 +2944,8 @@
       }
     }
     _isElementDisabled(element) {
-      if (!element)
-        return false;
-      if ("disabled" in element)
-        return !!element.disabled;
+      if (!element) return false;
+      if ("disabled" in element) return !!element.disabled;
       return element.getAttribute("aria-disabled") === "true";
     }
     /**
@@ -2652,8 +2953,7 @@
      * @private
      */
     _updatePlaceholderStatus() {
-      if (!this.options.showPlaceholder)
-        return;
+      if (!this.options.showPlaceholder) return;
       this._setPlaceholderVisible(!this.originalImage);
     }
     /**
@@ -2663,17 +2963,57 @@
      * @private
      */
     _setPlaceholderVisible(show) {
-      if (!this.placeholderElement || !this.containerElement)
-        return;
-      if (show) {
-        this.placeholderElement.classList.remove("d-none");
-        this.placeholderElement.classList.add("d-flex");
-        this.containerElement.classList.add("d-none");
+      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.
+     *
+     * @param {HTMLElement} element - Element whose visibility should be updated.
+     * @param {boolean} isVisible - If true, removes the hidden state.
+     * @returns {void}
+     * @private
+     */
+    _setElementVisible(element, isVisible) {
+      if (!element) return;
+      this._rememberElementVisibility(element);
+      element.hidden = !isVisible;
+      element.setAttribute("aria-hidden", isVisible ? "false" : "true");
+      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 {
-        this.placeholderElement.classList.remove("d-flex");
-        this.placeholderElement.classList.add("d-none");
-        this.containerElement.classList.remove("d-none");
+        element.setAttribute("aria-hidden", state.ariaHidden);
       }
+      element.className = state.className || "";
     }
     /**
      * Cleans up and disposes of the canvas and related references.
@@ -2681,44 +3021,84 @@
      * @public
      */
     dispose() {
+      this._disposed = true;
+      this._rejectActiveAnimations(new Error("Editor disposed during animation"));
+      if (this.animationQueue) {
+        this.animationQueue.cancelAll(new Error("Editor disposed"));
+      }
       try {
-        for (const key in this._handlersByElementKey || {}) {
-          const handlers = this._handlersByElementKey[key] || [];
-          const element = document.getElementById(this.elements[key]);
-          if (!element)
-            continue;
+        for (const [key, handlers] of Object.entries(this._handlersByElementKey || {})) {
+          const element = this._getElement(key);
+          if (!element) continue;
           handlers.forEach((handlerRecord) => {
             try {
               element.removeEventListener(handlerRecord.eventName, handlerRecord.handler);
             } catch (error) {
+              void error;
             }
           });
         }
       } catch (error) {
+        void error;
       }
       if (this._cropRect) {
         try {
           this.canvas.remove(this._cropRect);
         } catch (error) {
+          void error;
         }
         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;
         }
       }
       if (this.canvas) {
         try {
           this.canvas.dispose();
         } catch (error) {
+          void error;
         }
         this.canvas = null;
         this.canvasElement = null;
         this.isImageLoadedToCanvas = false;
       }
       this._handlersByElementKey = {};
+      this._elementCache = {};
+      this._clearMaskPlacementMemory();
+      this.originalImage = null;
+      this.baseImageScale = 1;
+      this.currentScale = 1;
+      this.currentRotation = 0;
+      this.isAnimating = false;
+      this._cropMode = false;
+      this._cropRect = null;
+      this._cropHandlers = [];
+      this._cropPrevEvented = null;
+      this._prevSelectionSetting = void 0;
+      this._initialized = false;
     }
   };
   var AnimationQueue = class {
@@ -2728,6 +3108,7 @@
     constructor() {
       this.animationTasks = [];
       this.isRunning = false;
+      this.currentTask = null;
     }
     /**
      * Adds an animation function to the queue.
@@ -2737,12 +3118,29 @@
      */
     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")) {
+      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.
      *
@@ -2750,19 +3148,27 @@
      * @returns {Promise<void>}
      */
     async _drainQueue() {
-      if (this.animationTasks.length === 0) {
-        this.isRunning = false;
-        return;
-      }
+      if (this.isRunning) return;
       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) {
+        const task = this.animationTasks.shift();
+        this.currentTask = task;
+        try {
+          const result = await task.animationFn();
+          if (!task.isSettled) {
+            task.isSettled = true;
+            task.resolve(result);
+          }
+        } catch (error) {
+          if (!task.isSettled) {
+            task.isSettled = true;
+            task.reject(error);
+          }
+        } finally {
+          if (this.currentTask === task) this.currentTask = null;
+        }
       }
-      await this._drainQueue();
+      this.isRunning = false;
     }
   };
   var Command = class {
@@ -2793,15 +3199,8 @@
      * @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;
     }
     /**
@@ -2812,8 +3211,14 @@
      * @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.
@@ -2829,9 +3234,8 @@
       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.