@bensitu/image-editor 1.2.2 → 1.3.1

package/dist/image-editor.esm.mjs

@@ -5,19 +5,16 @@ import fabricModule from "fabric";
 /**
  * @file image-editor.js
  * @module image-editor
- * @version 1.2.2
+ * @version 1.3.1
  * @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() {
@@ -29,8 +26,7 @@ function setFabric(fabricInstance2) {
   return fabric;
 }
 function ensureFabric() {
-  if (!fabric)
-    setFabric();
+  if (!fabric) setFabric();
   return fabric;
 }
 var ImageEditor = class {
@@ -76,6 +72,7 @@ var ImageEditor = class {
       downsampleMaxWidth: 4e3,
       downsampleMaxHeight: 3e3,
       downsampleQuality: 0.92,
+      imageLoadTimeoutMs: 3e4,
       exportMultiplier: 1,
       exportImageAreaByDefault: true,
       defaultMaskWidth: 50,
@@ -134,12 +131,16 @@ var ImageEditor = class {
     this._cropPrevEvented = null;
     this._prevSelectionSetting = void 0;
     this._containerOriginalOverflow = void 0;
+    this._scrollbarSizeCache = null;
     this.onImageLoaded = typeof options.onImageLoaded === "function" ? options.onImageLoaded : null;
-    this.animQueue = new AnimationQueue();
+    this.animationQueue = new AnimationQueue();
     this.historyManager = new HistoryManager(this.maxHistorySize);
   }
   /**
-   * @deprecated Use canvasElement instead.
+   * Backward-compatible alias for {@link ImageEditor#canvasElement}.
+   *
+   * @deprecated Use canvasElement instead. This alias will be removed in v2.0.0.
+   * @returns {HTMLCanvasElement|null} The canvas element currently owned by the editor.
    */
   get canvasEl() {
     return this.canvasElement;
@@ -148,7 +149,10 @@ var ImageEditor = class {
     this.canvasElement = value;
   }
   /**
-   * @deprecated Use containerElement instead.
+   * Backward-compatible alias for {@link ImageEditor#containerElement}.
+   *
+   * @deprecated Use containerElement instead. This alias will be removed in v2.0.0.
+   * @returns {HTMLElement|null} The canvas viewport/container element.
    */
   get containerEl() {
     return this.containerElement;
@@ -157,7 +161,10 @@ var ImageEditor = class {
     this.containerElement = value;
   }
   /**
-   * @deprecated Use placeholderElement instead.
+   * Backward-compatible alias for {@link ImageEditor#placeholderElement}.
+   *
+   * @deprecated Use placeholderElement instead. This alias will be removed in v2.0.0.
+   * @returns {HTMLElement|null} The placeholder element shown before an image loads.
    */
   get placeholderEl() {
     return this.placeholderElement;
@@ -171,9 +178,10 @@ var ImageEditor = class {
    * Use this method to set up the editor UI before interacting with it.
    *
    * @param {Object} [idMap={}] - Optional mapping from logical element names to actual DOM element IDs.
-   *   Supported keys include: canvas, canvasContainer, imgPlaceholder, scaleRate, rotationLeftInput, rotationRightInput,
-   *   rotateLeftBtn, rotateRightBtn, addMaskBtn, removeMaskBtn, removeAllMasksBtn, mergeBtn, downloadBtn, maskList,
-   *   zoomInBtn, zoomOutBtn, resetBtn, imageInput. Unknown keys are ignored.
+   *   Supported keys include: canvas, canvasContainer, imgPlaceholder, scaleRate, rotationLeftInput,
+   *   rotationRightInput, rotateLeftBtn, rotateRightBtn, addMaskBtn, removeMaskBtn, removeAllMasksBtn,
+   *   mergeBtn, downloadBtn, maskList, zoomInBtn, zoomOutBtn, resetBtn, undoBtn, redoBtn, imageInput,
+   *   uploadArea, cropBtn, applyCropBtn, and cancelCropBtn. Unknown keys are ignored.
    *
    * @returns {void}
    *
@@ -186,8 +194,7 @@ var ImageEditor = class {
    * });
    */
   init(idMap = {}) {
-    if (!this._fabricLoaded)
-      return;
+    if (!this._fabricLoaded) return;
     const defaults = {
       canvas: "fabricCanvas",
       canvasContainer: null,
@@ -228,8 +235,7 @@ var ImageEditor = class {
   }
   _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 {
@@ -237,21 +243,21 @@ var ImageEditor = class {
   }
   _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 {
     }
   }
   /**
-   * Canvas setup helpers
+   * Initializes the Fabric canvas, viewport elements, and selection event handlers.
+   *
+   * @returns {void}
    * @private
    */
   _initCanvas() {
     const canvasElement = document.getElementById(this.elements.canvas);
-    if (!canvasElement)
-      throw new Error("Canvas is not found: " + this.elements.canvas);
+    if (!canvasElement) throw new Error("Canvas is not found: " + this.elements.canvas);
     this.canvasElement = canvasElement;
     if (this.elements.canvasContainer) {
       const containerElement = document.getElementById(this.elements.canvasContainer);
@@ -281,57 +287,73 @@ var ImageEditor = class {
     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";
   }
+  /**
+   * Records a history entry after Fabric finishes modifying one or more masks.
+   *
+   * @param {fabric.Object|fabric.ActiveSelection|null} target - Modified Fabric object or selection.
+   * @returns {void}
+   * @private
+   */
   _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._expandCanvasToFitObject(mask);
     });
+    this._expandCanvasToFitObjects(masks);
     this.saveState();
   }
+  /**
+   * Extracts editable mask objects from a Fabric modification target.
+   *
+   * @param {fabric.Object|fabric.ActiveSelection|null} target - Fabric object or active selection.
+   * @returns {Array<fabric.Object>} Modified mask objects.
+   * @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) : [];
   }
-  _syncContainerOverflow() {
-    if (!this.containerElement || !this.containerElement.style)
-      return;
+  /**
+   * Updates container overflow behavior for fit and cover image modes.
+   *
+   * @param {Object} [options={}] - Overflow update options.
+   * @param {boolean} [options.preserveScroll=false] - If true, keeps the current scroll offsets.
+   * @returns {void}
+   * @private
+   */
+  _syncContainerOverflow(options = {}) {
+    if (!this.containerElement || !this.containerElement.style) return;
     if (this._containerOriginalOverflow === void 0) {
       this._containerOriginalOverflow = this.containerElement.style.overflow || "";
     }
+    const shouldPreserveScroll = options.preserveScroll === true;
     if (this.options.coverImageToCanvas) {
-      const shouldResetScroll = !this.isImageLoadedToCanvas;
       this.containerElement.style.overflow = "scroll";
-      if (shouldResetScroll) {
+      if (!shouldPreserveScroll) {
         this.containerElement.scrollLeft = 0;
         this.containerElement.scrollTop = 0;
       }
     } else if (this.options.fitImageToCanvas) {
       this.containerElement.style.overflow = "auto";
-      this.containerElement.scrollLeft = 0;
-      this.containerElement.scrollTop = 0;
+      if (!shouldPreserveScroll) {
+        this.containerElement.scrollLeft = 0;
+        this.containerElement.scrollTop = 0;
+      }
     } else {
       this.containerElement.style.overflow = this._containerOriginalOverflow;
     }
@@ -343,14 +365,12 @@ var ImageEditor = class {
   _bindEvents() {
     this._bindIfExists("uploadArea", "click", () => {
       const uploadAreaElement = document.getElementById(this.elements.uploadArea);
-      if (this._isElementDisabled(uploadAreaElement))
-        return;
+      if (this._isElementDisabled(uploadAreaElement)) return;
       document.getElementById(this.elements.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);
     });
     this._bindIfExists("zoomInBtn", "click", () => this.scaleImage(this.currentScale + this.options.scaleStep));
     this._bindIfExists("zoomOutBtn", "click", () => this.scaleImage(this.currentScale - this.options.scaleStep));
@@ -369,8 +389,7 @@ var ImageEditor = class {
       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);
     });
@@ -379,8 +398,7 @@ var ImageEditor = class {
       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);
     });
@@ -390,12 +408,12 @@ var ImageEditor = class {
     });
     this._bindIfExists("cancelCropBtn", "click", () => this.cancelCrop());
   }
-  /** 
-   * Event binding element check
-   * 
-   * @param {*} eventName
-   * @param {*} handler 
-   * @param {*} key 
+  /**
+   * Binds a DOM event listener when the configured element exists and records it for disposal.
+   *
+   * @param {string} key - Key in this.elements for the target DOM element.
+   * @param {string} eventName - DOM event name to listen for.
+   * @param {EventListener} handler - Event listener callback.
    * @private
    */
   _bindIfExists(key, eventName, handler) {
@@ -403,20 +421,18 @@ var ImageEditor = class {
     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 });
     }
   }
-  /** 
-   * Image loading helpers
-   * 
-   * @param {File} file 
+  /**
+   * Reads an image File as a data URL and loads it into the Fabric canvas.
+   *
+   * @param {File} file - Image file selected by the user.
    * @private
    */
   _loadImageFile(file) {
-    if (!file || !file.type.startsWith("image/"))
-      return;
+    if (!file || !file.type.startsWith("image/")) return;
     const reader = new FileReader();
     reader.onload = (event) => this.loadImage(event.target.result);
     reader.onerror = (event) => {
@@ -425,19 +441,38 @@ var ImageEditor = class {
     reader.readAsDataURL(file);
   }
   /**
-  * Load a base64 encoded image string into fabric.
-  * @async
-   * @param {String} imageBase64
+   * Warns when more than one mutually exclusive image layout mode is enabled.
+   *
+   * @returns {void}
+   * @private
    */
-  async loadImage(imageBase64) {
-    if (!this._fabricLoaded)
-      return;
-    if (!this.canvas)
-      return;
-    if (!imageBase64 || typeof imageBase64 !== "string" || !imageBase64.startsWith("data:image/"))
-      return;
+  _warnOnImageLayoutOptionConflict() {
+    const activeModes = [
+      ["fitImageToCanvas", this.options.fitImageToCanvas],
+      ["coverImageToCanvas", this.options.coverImageToCanvas],
+      ["expandCanvasToImage", this.options.expandCanvasToImage]
+    ].filter(([, isEnabled]) => !!isEnabled).map(([name]) => name);
+    if (activeModes.length <= 1) return;
+    this._reportWarning(
+      `Only one image layout mode should be enabled. Active modes: ${activeModes.join(", ")}.`
+    );
+  }
+  /**
+   * Loads a base64 data URL into the Fabric canvas as the base image.
+   *
+   * @async
+   * @param {string} imageBase64 - Image data URL beginning with `data:image/`.
+   * @param {LoadImageOptions} [options={}] - Optional load behavior.
+   * @returns {Promise<void>} Resolves after the Fabric image is added to the canvas.
+   * @public
+   */
+  async loadImage(imageBase64, options = {}) {
+    if (!this._fabricLoaded) return;
+    if (!this.canvas) return;
+    if (!imageBase64 || typeof imageBase64 !== "string" || !imageBase64.startsWith("data:image/")) return;
+    this._warnOnImageLayoutOptionConflict();
     this._setPlaceholderVisible(false);
-    this._syncContainerOverflow();
+    this._syncContainerOverflow({ preserveScroll: options.preserveScroll === true });
     const imageElement = await this._createImageElement(imageBase64);
     let loadSource = imageBase64;
     if (this.options.downsampleOnLoad) {
@@ -455,8 +490,7 @@ var ImageEditor = class {
     return new Promise((resolve, reject) => {
       fabric.Image.fromURL(loadSource, (fabricImage) => {
         try {
-          if (!fabricImage)
-            throw new Error("Image could not be loaded");
+          if (!fabricImage) throw new Error("Image could not be loaded");
           this.canvas.discardActiveObject();
           this._hideAllMaskLabels();
           this.canvas.clear();
@@ -468,8 +502,8 @@ var ImageEditor = class {
           const minWidth = viewport.width;
           const minHeight = viewport.height;
           if (this.options.fitImageToCanvas) {
-            const canvasWidth = Math.max(1, Math.min(this.options.canvasWidth, minWidth) - 1);
-            const canvasHeight = Math.max(1, Math.min(this.options.canvasHeight, minHeight) - 1);
+            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 });
@@ -539,22 +573,34 @@ var ImageEditor = class {
    * Creates an HTMLImageElement from a given data URL.
    * 
    * @param {string} dataUrl - A data URL representing the image (e.g., "data:image/png;base64,...").
+   * @param {number} [timeoutMs=this.options.imageLoadTimeoutMs] - Maximum decode time before rejecting.
    * @returns {Promise<HTMLImageElement>} A promise that resolves to the created image element when loaded, or rejects on error.
    * @private
    */
-  _createImageElement(dataUrl) {
+  _createImageElement(dataUrl, timeoutMs = this.options.imageLoadTimeoutMs) {
     return new Promise((resolve, reject) => {
       const imageElement = new Image();
-      imageElement.onload = () => {
-        imageElement.onload = null;
-        imageElement.onerror = null;
-        resolve(imageElement);
-      };
-      imageElement.onerror = (error) => {
+      let isSettled = false;
+      const safeTimeoutMs = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0 ? Number(timeoutMs) : 3e4;
+      let timerId;
+      const settle = (callback) => {
+        if (isSettled) return;
+        isSettled = true;
+        clearTimeout(timerId);
         imageElement.onload = null;
         imageElement.onerror = null;
-        reject(error);
+        callback();
       };
+      timerId = setTimeout(() => {
+        settle(() => reject(new Error("Image load timed out")));
+        try {
+          imageElement.src = "";
+        } catch (error) {
+          void error;
+        }
+      }, safeTimeoutMs);
+      imageElement.onload = () => settle(() => resolve(imageElement));
+      imageElement.onerror = (error) => settle(() => reject(error));
       imageElement.src = dataUrl;
     });
   }
@@ -573,6 +619,7 @@ var ImageEditor = class {
     offscreenCanvas.width = targetWidth;
     offscreenCanvas.height = targetHeight;
     const context = offscreenCanvas.getContext("2d");
+    if (!context) throw new Error("2D canvas context is unavailable");
     context.drawImage(imageElement, 0, 0, imageElement.naturalWidth, imageElement.naturalHeight, 0, 0, targetWidth, targetHeight);
     return offscreenCanvas.toDataURL("image/jpeg", quality);
   }
@@ -580,28 +627,26 @@ var ImageEditor = class {
    * Sets canvas size to integer width and height values to prevent scrollbars due to sub-pixel rendering.
    * Also updates the corresponding style attributes.
    * 
-   * @param {number} w - Canvas width (in pixels).
-   * @param {number} h - Canvas height (in pixels).
+   * @param {number} width - Canvas width in pixels.
+   * @param {number} height - Canvas height in pixels.
    * @private
    */
-  _setCanvasSizeInt(w, h) {
-    const iw = Math.max(1, Math.round(Number(w) || 1));
-    const ih = Math.max(1, Math.round(Number(h) || 1));
-    this.canvas.setWidth(iw);
-    this.canvas.setHeight(ih);
-    if (typeof this.canvas.calcOffset === "function")
-      this.canvas.calcOffset();
+  _setCanvasSizeInt(width, height) {
+    const integerWidth = Math.max(1, Math.round(Number(width) || 1));
+    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 (this.canvasElement) {
-      this.canvasElement.style.width = iw + "px";
-      this.canvasElement.style.height = ih + "px";
+      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() {
@@ -611,22 +656,31 @@ var ImageEditor = class {
         height: Math.max(1, Math.floor(this.options.canvasHeight || 1))
       };
     }
+    let width = Math.max(1, Math.floor(this.containerElement.clientWidth || this.options.canvasWidth || 1));
+    let height = Math.max(1, Math.floor(this.containerElement.clientHeight || this.options.canvasHeight || 1));
     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 previousOverflow = this.containerElement.style.overflow;
-    this.containerElement.style.overflow = "hidden";
-    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));
-    this.containerElement.style.overflow = previousOverflow;
     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;
@@ -639,9 +693,20 @@ var ImageEditor = class {
       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) {
+      return { ...this._scrollbarSizeCache };
+    }
     if (typeof document === "undefined" || !document.createElement || !document.body) {
       return { width: 0, height: 0 };
     }
@@ -656,7 +721,8 @@ var ImageEditor = class {
     const width = Math.max(0, probe.offsetWidth - probe.clientWidth);
     const height = Math.max(0, probe.offsetHeight - probe.clientHeight);
     document.body.removeChild(probe);
-    return { width, height };
+    this._scrollbarSizeCache = { width, height };
+    return { ...this._scrollbarSizeCache };
   }
   _getScrollSafetyMargin() {
     return 2;
@@ -678,15 +744,14 @@ var ImageEditor = class {
     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;
     }
@@ -723,8 +788,8 @@ var ImageEditor = class {
     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));
@@ -733,8 +798,7 @@ var ImageEditor = class {
       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;
     }
@@ -773,41 +837,48 @@ var ImageEditor = class {
       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,
@@ -820,26 +891,57 @@ var ImageEditor = class {
       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.
+   *
+   * @returns {{version:number, baseImageScale:number, currentScale:number, currentRotation:number, maskCounter:number}} Serializable editor metadata.
+   * @private
+   */
+  _serializeEditorMetadata() {
+    const baseImageScale = Number(this.baseImageScale);
+    const currentScale = Number(this.currentScale);
+    const currentRotation = Number(this.currentRotation);
+    const maskCounter = Number(this.maskCounter);
+    return {
+      version: 1,
+      baseImageScale: Number.isFinite(baseImageScale) && baseImageScale > 0 ? baseImageScale : 1,
+      currentScale: Number.isFinite(currentScale) && currentScale > 0 ? currentScale : 1,
+      currentRotation: Number.isFinite(currentRotation) ? currentRotation : 0,
+      maskCounter: Number.isFinite(maskCounter) && maskCounter > 0 ? Math.floor(maskCounter) : 0
+    };
   }
   _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)) {
         jsonObject.objects = jsonObject.objects.filter((object) => !object.isCropRect && !object.maskLabel);
       }
+      jsonObject.imageEditorMetadata = this._serializeEditorMetadata();
       return JSON.stringify(jsonObject);
     });
   }
+  /**
+   * Normalizes a lossy image quality value to Fabric/canvas's 0..1 range.
+   *
+   * @param {number} quality - Requested image quality.
+   * @returns {number} A finite quality value between 0 and 1.
+   * @private
+   */
   _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));
   }
+  /**
+   * Normalizes public image format aliases to canvas export format names.
+   *
+   * @param {string} format - Requested image format or MIME type.
+   * @returns {'jpeg'|'png'|'webp'} Canvas-compatible image format.
+   * @private
+   */
   _normalizeImageFormat(format) {
     const typeMapping = {
       "jpeg": "jpeg",
@@ -852,6 +954,15 @@ var ImageEditor = class {
     };
     return typeMapping[String(format || "jpeg").toLowerCase()] || "jpeg";
   }
+  /**
+   * Converts a bounding rectangle into a canvas-safe integer source region.
+   *
+   * @param {{left:number, top:number, width:number, height:number}} bounds - Bounds in canvas coordinates.
+   * @param {Object} [options={}] - Region rounding options.
+   * @param {boolean} [options.includePartialPixels=true] - If false, excludes partially covered trailing pixels.
+   * @returns {{sourceX:number, sourceY:number, sourceWidth:number, sourceHeight:number}} Clamped source region.
+   * @private
+   */
   _getClampedCanvasRegion(bounds, options = {}) {
     const canvasWidth = Math.max(1, Math.round(this.canvas.getWidth()));
     const canvasHeight = Math.max(1, Math.round(this.canvas.getHeight()));
@@ -866,15 +977,49 @@ var ImageEditor = class {
     const endX = Math.min(canvasWidth, Math.max(sourceX + 1, roundEnd(left + width)));
     const endY = Math.min(canvasHeight, Math.max(sourceY + 1, roundEnd(top + height)));
     return {
-      sx: sourceX,
-      sy: sourceY,
-      sw: Math.max(1, endX - sourceX),
-      sh: Math.max(1, endY - sourceY)
+      sourceX,
+      sourceY,
+      sourceWidth: Math.max(1, endX - sourceX),
+      sourceHeight: Math.max(1, endY - sourceY)
     };
   }
+  /**
+   * Crops an image data URL to a source region using an offscreen canvas.
+   *
+   * @param {string} dataUrl - Source image data URL.
+   * @param {number} sourceX - Source region x coordinate.
+   * @param {number} sourceY - Source region y coordinate.
+   * @param {number} sourceWidth - Source region width.
+   * @param {number} sourceHeight - Source region height.
+   * @param {number} multiplier - Export multiplier already applied to the source data URL.
+   * @param {'jpeg'|'png'|'webp'} [format='jpeg'] - Output image format.
+   * @param {number} [quality=0.92] - Output image quality for lossy formats.
+   * @returns {Promise<string>} Resolves with the cropped image data URL.
+   * @private
+   */
   async _cropDataUrl(dataUrl, sourceX, sourceY, sourceWidth, sourceHeight, multiplier, format = "jpeg", quality = 0.92) {
     return new Promise((resolve, reject) => {
       const imageElement = new Image();
+      let isSettled = false;
+      const timeoutMs = Number(this.options.imageLoadTimeoutMs);
+      const safeTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 3e4;
+      let timerId;
+      const settle = (callback) => {
+        if (isSettled) return;
+        isSettled = true;
+        clearTimeout(timerId);
+        imageElement.onload = null;
+        imageElement.onerror = null;
+        callback();
+      };
+      timerId = setTimeout(() => {
+        settle(() => reject(new Error("Image crop load timed out")));
+        try {
+          imageElement.src = "";
+        } catch (error) {
+          void error;
+        }
+      }, safeTimeoutMs);
       imageElement.onload = () => {
         try {
           const safeMultiplier = Math.max(1, Number(multiplier) || 1);
@@ -886,24 +1031,39 @@ var ImageEditor = class {
           offscreenCanvas.width = scaledSourceWidth;
           offscreenCanvas.height = scaledSourceHeight;
           const context = offscreenCanvas.getContext("2d");
+          if (!context) throw new Error("2D canvas context is unavailable");
           context.drawImage(imageElement, scaledSourceX, scaledSourceY, scaledSourceWidth, scaledSourceHeight, 0, 0, scaledSourceWidth, scaledSourceHeight);
-          resolve(offscreenCanvas.toDataURL(`image/${format}`, quality));
+          settle(() => resolve(offscreenCanvas.toDataURL(`image/${format}`, quality)));
         } catch (error) {
-          reject(error);
+          settle(() => reject(error));
         }
       };
-      imageElement.onerror = reject;
+      imageElement.onerror = (error) => settle(() => reject(error));
       imageElement.src = dataUrl;
     });
   }
-  async _exportCanvasRegionToDataURL({ sx, sy, sw, sh, multiplier = 1, quality = 0.92, format = "jpeg" }) {
+  /**
+   * Exports the whole Fabric canvas, then crops the requested source region from that export.
+   *
+   * @param {Object} region - Canvas source region and export options.
+   * @param {number} region.sourceX - Source region x coordinate.
+   * @param {number} region.sourceY - Source region y coordinate.
+   * @param {number} region.sourceWidth - Source region width.
+   * @param {number} region.sourceHeight - Source region height.
+   * @param {number} [region.multiplier=1] - Export multiplier.
+   * @param {number} [region.quality=0.92] - Output image quality for lossy formats.
+   * @param {'jpeg'|'png'|'webp'} [region.format='jpeg'] - Output image format.
+   * @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" }) {
     const safeMultiplier = Math.max(1, Number(multiplier) || 1);
     const fullDataUrl = this.canvas.toDataURL({
       format,
       quality,
       multiplier: safeMultiplier
     });
-    return this._cropDataUrl(fullDataUrl, sx, sy, sw, sh, safeMultiplier, format, quality);
+    return this._cropDataUrl(fullDataUrl, sourceX, sourceY, sourceWidth, sourceHeight, safeMultiplier, format, quality);
   }
   /** 
    * Gets the top-left corner coordinates of the given object.
@@ -914,12 +1074,10 @@ var ImageEditor = class {
    * @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];
+    if (coords && coords.length) return coords[0];
     const boundingRect = fabricObject.getBoundingRect(true, true);
     return { x: boundingRect.left, y: boundingRect.top };
   }
@@ -933,8 +1091,7 @@ var ImageEditor = class {
    * @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();
@@ -946,8 +1103,7 @@ var ImageEditor = class {
    * @private
    */
   _alignObjectBoundingBoxToCanvasTopLeft(fabricObject) {
-    if (!fabricObject)
-      return;
+    if (!fabricObject) return;
     fabricObject.setCoords();
     const boundingRect = fabricObject.getBoundingRect(true, true);
     const deltaX = boundingRect.left;
@@ -962,30 +1118,63 @@ var ImageEditor = class {
    * @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);
     this._setCanvasSizeInt(size.width, size.height);
   }
-  _expandCanvasToFitObject(fabricObject, padding = 10) {
-    if (!this.canvas || !fabricObject || !this.options.expandCanvasToImage)
-      return;
+  /**
+   * Whether post-load edits should resize the canvas to keep transformed content visible.
+   *
+   * @returns {boolean} True when canvas bounds should follow edited image or mask bounds.
+   * @private
+   */
+  _shouldResizeCanvasToContentBounds() {
+    return !!(this.options.expandCanvasToImage || this.options.coverImageToCanvas || this.options.fitImageToCanvas);
+  }
+  /**
+   * Expands the canvas once so all provided objects remain visible after an edit.
+   *
+   * @param {Array<fabric.Object>} fabricObjects - Objects whose bounds should fit inside the canvas.
+   * @param {number} [padding=10] - Extra canvas space after the farthest object edge.
+   * @returns {void}
+   * @private
+   */
+  _expandCanvasToFitObjects(fabricObjects, padding = 10) {
+    if (!this.canvas || !Array.isArray(fabricObjects) || !fabricObjects.length || !this._shouldResizeCanvasToContentBounds()) return;
     try {
-      fabricObject.setCoords();
-      const boundingRect = fabricObject.getBoundingRect(true, true);
-      const requiredWidth = Math.ceil(boundingRect.left + boundingRect.width + padding);
-      const requiredHeight = Math.ceil(boundingRect.top + boundingRect.height + padding);
+      let requiredWidth = this.canvas.getWidth();
+      let requiredHeight = this.canvas.getHeight();
+      fabricObjects.forEach((fabricObject) => {
+        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);
-      this._setCanvasSizeInt(newWidth, newHeight);
+      if (newWidth !== this.canvas.getWidth() || newHeight !== this.canvas.getHeight()) {
+        this._setCanvasSizeInt(newWidth, newHeight);
+      }
     } catch (error) {
-      this._reportWarning("expandCanvasToFitObject: failed to expand canvas", error);
+      this._reportWarning("expandCanvasToFitObjects: failed to expand canvas", error);
     }
   }
+  /**
+   * Expands the canvas so one object remains visible after an edit.
+   *
+   * @param {fabric.Object} fabricObject - Object whose bounds should fit inside the canvas.
+   * @param {number} [padding=10] - Extra canvas space after the object edge.
+   * @returns {void}
+   * @private
+   */
+  _expandCanvasToFitObject(fabricObject, padding = 10) {
+    this._expandCanvasToFitObjects([fabricObject], padding);
+  }
   /** 
    * Scales the original image by a given factor, with animation.
    * Returns a promise that resolves when the scale animation is complete.
@@ -994,7 +1183,7 @@ var ImageEditor = class {
    * @public
    */
   scaleImage(factor, options = {}) {
-    return this.animQueue.add(() => this._scaleImageImpl(factor, options));
+    return this.animationQueue.add(() => this._scaleImageImpl(factor, options));
   }
   /** 
    * Scales the original image by a given factor, with animation.
@@ -1004,10 +1193,8 @@ var ImageEditor = class {
    * @private
    */
   _scaleImageImpl(factor, options = {}) {
-    if (!this.originalImage)
-      return Promise.resolve();
-    if (this.isAnimating)
-      return Promise.resolve();
+    if (!this.originalImage) return Promise.resolve();
+    if (this.isAnimating) return Promise.resolve();
     const saveHistory = options.saveHistory !== false;
     factor = Math.max(this.options.minScale, Math.min(this.options.maxScale, factor));
     this.currentScale = factor;
@@ -1033,19 +1220,17 @@ var ImageEditor = class {
     return Promise.all([scaleXAnimation, scaleYAnimation]).then(() => {
       this.originalImage.set({ scaleX: targetScale, scaleY: targetScale });
       this.originalImage.setCoords();
-      if (this.options.expandCanvasToImage || this.options.coverImageToCanvas) {
+      if (this._shouldResizeCanvasToContentBounds()) {
         this._updateCanvasSizeToImageBounds();
       }
       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();
+      if (saveHistory) this.saveState();
     }).catch(() => {
       this.isAnimating = false;
       this._updateUI();
@@ -1059,7 +1244,7 @@ var ImageEditor = class {
    * @public
    */
   rotateImage(degrees, options = {}) {
-    return this.animQueue.add(() => this._rotateImageImpl(degrees, options));
+    return this.animationQueue.add(() => this._rotateImageImpl(degrees, options));
   }
   /** 
    * Rotates the original image by a given number of degrees, with animation.
@@ -1069,12 +1254,9 @@ var ImageEditor = class {
    * @private
    */
   _rotateImageImpl(degrees, options = {}) {
-    if (!this.originalImage)
-      return Promise.resolve();
-    if (this.isAnimating)
-      return Promise.resolve();
-    if (isNaN(degrees))
-      return Promise.resolve();
+    if (!this.originalImage) return Promise.resolve();
+    if (this.isAnimating) return Promise.resolve();
+    if (isNaN(degrees)) return Promise.resolve();
     const saveHistory = options.saveHistory !== false;
     this.currentRotation = degrees;
     this.isAnimating = true;
@@ -1091,21 +1273,19 @@ var ImageEditor = class {
     return rotationAnimation.then(() => {
       this.originalImage.set("angle", degrees);
       this.originalImage.setCoords();
-      if (this.options.expandCanvasToImage || this.options.coverImageToCanvas) {
+      if (this._shouldResizeCanvasToContentBounds()) {
         this._updateCanvasSizeToImageBounds();
       }
       this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
       const newTopLeft = this._getObjectTopLeftPoint(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();
+      if (saveHistory) this.saveState();
     }).catch(() => {
       this.isAnimating = false;
       this._updateUI();
@@ -1113,38 +1293,45 @@ var ImageEditor = class {
   }
   /**
    * Resets the image transform: scales to 1 and rotates to 0 degrees.
-   * @returns {Promise<void>} Promise that resolves when reset is complete.
+   *
+   * @returns {Promise<void>} Resolves when the reset history transition has been recorded.
+   * @public
    */
   resetImageTransform() {
-    if (!this.originalImage)
-      return Promise.resolve();
-    return this.animQueue.add(async () => {
-      const before = this._serializeCanvasState();
+    if (!this.originalImage) return Promise.resolve();
+    return this.animationQueue.add(async () => {
+      const before = this._lastSnapshot || this._serializeCanvasState();
       await this._scaleImageImpl(1, { saveHistory: false });
       await this._rotateImageImpl(0, { saveHistory: false });
       const after = this._serializeCanvasState();
       this._pushStateTransition(before, after);
-    }).catch((err) => {
-      this._reportError("resetImageTransform() failed", err);
+    }).catch((error) => {
+      this._reportError("resetImageTransform() failed", error);
     });
   }
   /**
-   * @deprecated Use resetImageTransform() instead.
+   * Backward-compatible alias for {@link ImageEditor#resetImageTransform}.
+   *
+   * @deprecated Use resetImageTransform() instead. This alias will be removed in v2.0.0.
+   * @returns {Promise<void>} Resolves when the image transform reset is complete.
    */
   reset() {
     return this.resetImageTransform();
   }
   /**
-   * Restores a canvas state that was previously stored by saveState().
-   * @param {string} jsonString - the JSON string returned by fabric.toJSON().
+   * Restores a serialized canvas state and rebinds editor-specific mask/image metadata.
+   *
+   * @param {string|Object} serializedState - State returned by `_serializeCanvasState()` as a JSON string or object.
+   * @returns {Promise<void>} Resolves after Fabric has loaded the state and UI state has been refreshed.
+   * @public
    */
-  loadFromState(jsonString) {
-    if (!jsonString || !this.canvas)
-      return Promise.resolve();
+  loadFromState(serializedState) {
+    if (!serializedState || !this.canvas) return Promise.resolve();
     return new Promise((resolve) => {
       try {
-        const json = typeof jsonString === "string" ? JSON.parse(jsonString) : jsonString;
-        this.canvas.loadFromJSON(json, () => {
+        const state = typeof serializedState === "string" ? JSON.parse(serializedState) : serializedState;
+        const editorMetadata = state && state.imageEditorMetadata ? state.imageEditorMetadata : null;
+        this.canvas.loadFromJSON(state, () => {
           try {
             this._hideAllMaskLabels();
             const canvasObjects = this.canvas.getObjects();
@@ -1152,11 +1339,22 @@ var ImageEditor = class {
             if (this.originalImage) {
               this.originalImage.set({ originX: "left", originY: "top", selectable: false, evented: false, hasControls: false, hoverCursor: "default" });
               this.canvas.sendToBack(this.originalImage);
-              this.currentRotation = Number(this.originalImage.angle) || 0;
-              const baseScale = Number(this.baseImageScale) || 1;
-              const imageScale = Number(this.originalImage.scaleX) || baseScale;
-              this.currentScale = imageScale / baseScale;
+              const restoredBaseScale = Number(editorMetadata && editorMetadata.baseImageScale);
+              const restoredCurrentScale = Number(editorMetadata && editorMetadata.currentScale);
+              const restoredCurrentRotation = Number(editorMetadata && editorMetadata.currentRotation);
+              if (Number.isFinite(restoredBaseScale) && restoredBaseScale > 0) {
+                this.baseImageScale = restoredBaseScale;
+              }
+              if (Number.isFinite(restoredCurrentScale) && restoredCurrentScale > 0) {
+                this.currentScale = restoredCurrentScale;
+              } else {
+                const baseScale = Number(this.baseImageScale) || 1;
+                const imageScale = Number(this.originalImage.scaleX) || baseScale;
+                this.currentScale = imageScale / baseScale;
+              }
+              this.currentRotation = Number.isFinite(restoredCurrentRotation) ? restoredCurrentRotation : Number(this.originalImage.angle) || 0;
             } else {
+              this.baseImageScale = 1;
               this.currentScale = 1;
               this.currentRotation = 0;
             }
@@ -1166,7 +1364,9 @@ var ImageEditor = class {
               this._rebindMaskEvents(mask);
               mask.set(this._getMaskNormalStyle(mask));
             });
-            this.maskCounter = masks.reduce((max, mask) => Math.max(max, mask.maskId), 0);
+            const restoredMaskCounter = Number(editorMetadata && editorMetadata.maskCounter);
+            const maxMaskId = masks.reduce((max, mask) => Math.max(max, mask.maskId), 0);
+            this.maskCounter = Number.isFinite(restoredMaskCounter) && restoredMaskCounter >= maxMaskId ? Math.floor(restoredMaskCounter) : maxMaskId;
             this._lastMask = masks.length ? masks[masks.length - 1] : null;
             if (!this._lastMask) {
               this._lastMaskInitialLeft = null;
@@ -1193,18 +1393,21 @@ var ImageEditor = class {
     });
   }
   /**
-   * Saves the current state of the canvas to history, storing any mask/raster label information.
+   * Saves the current editable canvas state as an undoable history transition.
+   *
+   * Labels are hidden before serialization because labels are UI overlays, while mask metadata is kept on
+   * mask objects and restored by `loadFromState()`.
+   *
+   * @returns {void}
+   * @public
    */
   saveState() {
-    if (!this.canvas)
-      return;
+    if (!this.canvas) return;
     const activeObject = this.canvas.getActiveObject();
-    this._hideAllMaskLabels();
     try {
       const after = this._serializeCanvasState();
       const before = this._lastSnapshot || after;
-      if (after === before)
-        return;
+      if (after === before) return;
       let executedOnce = false;
       const command = new Command(
         () => {
@@ -1221,19 +1424,27 @@ var ImageEditor = class {
     } catch (error) {
       this._reportWarning("saveState: failed to save canvas snapshot", error);
     } finally {
-      if (activeObject && activeObject.maskId && this.canvas.getObjects().includes(activeObject)) {
+      if (activeObject && activeObject.maskId && !activeObject.__label && this.canvas.getObjects().includes(activeObject)) {
         this._handleSelectionChanged([activeObject]);
       }
       this._updateUI();
     }
   }
+  /**
+   * Pushes a precomputed before/after state transition into history.
+   *
+   * Use this for operations such as crop and merge that build their snapshots around asynchronous image
+   * loading, where the "after" state is already applied before the history command is recorded.
+   *
+   * @param {string} before - Serialized state before the operation.
+   * @param {string} after - Serialized state after the operation.
+   * @returns {void}
+   * @private
+   */
   _pushStateTransition(before, after) {
-    if (!before || !after)
-      return;
-    if (before === after)
-      return;
-    if (!this.historyManager)
-      this.historyManager = new HistoryManager(this.maxHistorySize || 50);
+    if (!before || !after) return;
+    if (before === after) return;
+    if (!this.historyManager) this.historyManager = new HistoryManager(this.maxHistorySize || 50);
     const command = new Command(
       () => this.loadFromState(after),
       () => this.loadFromState(before)
@@ -1244,6 +1455,9 @@ var ImageEditor = class {
   }
   /**
    * Undo the last state change, if possible.
+   *
+   * @returns {Promise<void>} Resolves after the history manager finishes the queued undo.
+   * @public
    */
   undo() {
     return this.historyManager.undo().then(() => {
@@ -1254,6 +1468,9 @@ var ImageEditor = class {
   }
   /**
    * Redo the next state change, if possible.
+   *
+   * @returns {Promise<void>} Resolves after the history manager finishes the queued redo.
+   * @public
    */
   redo() {
     return this.historyManager.redo().then(() => {
@@ -1263,26 +1480,24 @@ var ImageEditor = class {
     });
   }
   _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 (e) {
+      } 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);
+    if (Object.keys(metadata).length) mask.set(metadata);
     const normalStyle = {
       stroke: mask.originalStroke || "#ccc",
       strokeWidth: mask.originalStrokeWidth,
@@ -1295,40 +1510,46 @@ var ImageEditor = class {
     };
     const mouseover = () => {
       mask.set(hoverStyle);
-      if (mask.canvas)
-        mask.canvas.requestRenderAll();
+      if (mask.canvas) mask.canvas.requestRenderAll();
     };
     const mouseout = () => {
       mask.set(normalStyle);
-      if (mask.canvas)
-        mask.canvas.requestRenderAll();
+      if (mask.canvas) mask.canvas.requestRenderAll();
     };
     mask.on("mouseover", mouseover);
     mask.on("mouseout", mouseout);
     mask.__imageEditorMaskHandlers = { mouseover, mouseout };
   }
-  /** 
+  /**
    * Creates a mask and adds it to the canvas.
-   * Mask placement and properties are determined by the provided config and instance options.
-   * Canvas and list UI are updated accordingly.
-   * @param {Object} [config={}] - Optional mask configuration overrides:
-   *   @param {string} [config.shape='rect'] - 'rect', 'circle', 'ellipse', 'polygon', ...
-   *   @param {Object|Array} [config.points] - Required for polygon: [{x, y}, ...] or [[x, y], ...]
-   *   @param {number|function} [config.width/height/rx/ry/radius] - Can be number or function(canvas, options) 
-   *   @param {number|string|function} [config.left/top] - Absolute, %, or function
-   *   @param {number|string} [config.angle] - Rotation angle (degree)
-   *   @param {string} [config.color] - Fill color in CSS color format (default 'rgba(0,0,0,0.5)')
-   *   @param {number} [config.alpha] - Opacity, from 0 to 1 (default 0.5)
-   *   @param {boolean} [config.selectable=true]
-   *   @param {Object} [config.styles] - Custom styles (stroke, dashArray, etc)
-   *   @param {function} [config.onCreate] - Callback after mask created (receives Fabric object)
-   *   @param {function} [config.fabricGenerator] - (maskConfig) => new FabricObj
-   * @returns {fabric.Rect|null} The created mask object, or null if canvas is not available.
+   *
+   * Placement is based on explicit `left`/`top` values when provided; otherwise each new mask is placed
+   * after the previously created mask. Fabric object properties are applied through `set()` and `setCoords()`
+   * so controls and hit testing stay in sync with Fabric 5.x behavior.
+   *
+   * @param {Object} [config={}] - Optional mask configuration overrides.
+   * @param {string} [config.shape='rect'] - Mask shape: `rect`, `circle`, `ellipse`, `polygon`, or a custom shape handled by `fabricGenerator`.
+   * @param {Array<{x:number,y:number}>|Array<Array<number>>} [config.points] - Polygon points.
+   * @param {number|string|MaskValueResolver} [config.width] - Width in pixels, percentage string, or resolver callback.
+   * @param {number|string|MaskValueResolver} [config.height] - Height in pixels, percentage string, or resolver callback.
+   * @param {number|string|MaskValueResolver} [config.radius] - Circle radius in pixels, percentage string, or resolver callback.
+   * @param {number|string|MaskValueResolver} [config.rx] - Ellipse horizontal radius or rectangle corner radius.
+   * @param {number|string|MaskValueResolver} [config.ry] - Ellipse vertical radius or rectangle corner radius.
+   * @param {number|string|MaskValueResolver} [config.left] - Left position in pixels, percentage string, or resolver callback.
+   * @param {number|string|MaskValueResolver} [config.top] - Top position in pixels, percentage string, or resolver callback.
+   * @param {number} [config.angle=0] - Rotation angle in degrees.
+   * @param {string} [config.color='rgba(0,0,0,0.5)'] - Fill color.
+   * @param {number} [config.alpha=0.5] - Opacity from 0 to 1.
+   * @param {boolean} [config.selectable=true] - Whether the mask can be selected.
+   * @param {boolean} [config.hasControls=true] - Whether Fabric transform controls are shown.
+   * @param {Object} [config.styles] - Additional Fabric style properties, such as `stroke` or `strokeDashArray`.
+   * @param {MaskFabricGenerator} [config.fabricGenerator] - Factory callback that returns a custom Fabric object.
+   * @param {MaskCreateCallback} [config.onCreate] - Callback invoked after the mask is added to the canvas.
+   * @returns {fabric.Object|null} The created mask object, or null if the canvas is not initialized.
    * @public
    */
   createMask(config = {}) {
-    if (!this.canvas)
-      return null;
+    if (!this.canvas) return null;
     const shapeType = config.shape || "rect";
     const maskConfig = {
       shape: shapeType,
@@ -1344,14 +1565,22 @@ var ImageEditor = class {
       ...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;
     };
@@ -1366,11 +1595,13 @@ var ImageEditor = class {
       left = Math.round(previousMaskRight + maskConfig.gap);
       top = previousMask.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;
     if (typeof maskConfig.fabricGenerator === "function") {
       mask = maskConfig.fabricGenerator(maskConfig, this.canvas, this.options);
@@ -1380,7 +1611,7 @@ var ImageEditor = class {
           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,
@@ -1391,8 +1622,8 @@ var ImageEditor = class {
           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,
@@ -1401,8 +1632,8 @@ var ImageEditor = class {
           break;
         case "polygon": {
           let polygonPoints = maskConfig.points || [];
-          if (Array.isArray(polygonPoints) && polygonPoints.length && typeof polygonPoints[0] === "object") {
-            polygonPoints = polygonPoints.map((point) => ({ x: Number(point.x), y: Number(point.y) }));
+          if (Array.isArray(polygonPoints) && polygonPoints.length) {
+            polygonPoints = polygonPoints.map((point) => Array.isArray(point) ? { x: Number(point[0]), y: Number(point[1]) } : { x: Number(point.x), y: Number(point.y) });
           }
           mask = new fabric.Polygon(polygonPoints, {
             left,
@@ -1419,13 +1650,12 @@ var ImageEditor = class {
           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,
             rx: maskConfig.rx,
-            // Rounded Corners
             ry: maskConfig.ry,
             ...maskConfig.styles
           });
@@ -1443,14 +1673,14 @@ var ImageEditor = class {
       transparentCorners: "transparentCorners" in maskConfig ? maskConfig.transparentCorners : false,
       stroke: hasStyle("stroke") ? styles.stroke : "#ccc",
       strokeWidth: hasStyle("strokeWidth") ? styles.strokeWidth : 1,
+      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({
-      originalAlpha: maskConfig.alpha,
+      originalAlpha: Number.isFinite(Number(mask.opacity)) ? Number(mask.opacity) : maskConfig.alpha,
       originalStroke: mask.stroke || "#ccc",
       originalStrokeWidth: Number.isFinite(Number(mask.strokeWidth)) ? Number(mask.strokeWidth) : 1
     });
@@ -1458,7 +1688,7 @@ var ImageEditor = class {
     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,
@@ -1467,19 +1697,21 @@ var ImageEditor = class {
     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;
   }
   /**
-   * @deprecated Use createMask() instead.
+   * Backward-compatible alias for {@link ImageEditor#createMask}.
+   *
+   * @deprecated Use createMask() instead. This alias will be removed in v2.0.0.
+   * @param {Object} [config={}] - Mask configuration passed to createMask().
+   * @returns {fabric.Object|null} The created mask object, or null if the canvas is not initialized.
    */
   addMask(config = {}) {
     return this.createMask(config);
@@ -1491,8 +1723,7 @@ var ImageEditor = class {
   removeSelectedMask() {
     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);
@@ -1527,8 +1758,7 @@ var ImageEditor = class {
     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.
@@ -1537,8 +1767,7 @@ var ImageEditor = class {
    * @private
    */
   _removeLabelForMask(mask) {
-    if (!mask || !this.canvas)
-      return;
+    if (!mask || !this.canvas) return;
     if (mask.__label) {
       try {
         const canvasObjects = this.canvas.getObjects();
@@ -1546,13 +1775,31 @@ var ImageEditor = class {
           this.canvas.remove(mask.__label);
         }
       } catch (error) {
+        void error;
       }
       try {
         delete mask.__label;
       } catch (error) {
+        void error;
       }
     }
   }
+  /**
+   * Returns a stable zero-based creation index for label callbacks.
+   *
+   * Mask ids are one-based and are not renumbered after deletion, so this value remains stable for the
+   * lifetime of a mask.
+   *
+   * @param {fabric.Object} mask - Mask object.
+   * @returns {number} Stable zero-based creation index.
+   * @private
+   */
+  _getMaskCreationIndex(mask) {
+    const maskId = Number(mask && mask.maskId);
+    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));
+  }
   /**
    * Creates and adds a custom label (fabric.Text or fabric.IText) for the mask.
    * The label is default bound to the top-left of the mask and managed as a non-interactive overlay.
@@ -1561,8 +1808,7 @@ var ImageEditor = class {
    * @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") {
@@ -1584,9 +1830,7 @@ var ImageEditor = class {
       };
       if (this.options.label) {
         if (typeof this.options.label.getText === "function") {
-          const masks = this.canvas ? this.canvas.getObjects().filter((object) => object.maskId) : [];
-          const maskIndex = Math.max(0, masks.indexOf(mask));
-          labelText = this.options.label.getText(mask, maskIndex);
+          labelText = this.options.label.getText(mask, this._getMaskCreationIndex(mask));
         }
         if (this.options.label.textOptions) {
           Object.assign(textOptions, this.options.label.textOptions);
@@ -1606,15 +1850,14 @@ var ImageEditor = class {
    * @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) => {
@@ -1622,6 +1865,7 @@ var ImageEditor = class {
         try {
           delete object.__label;
         } catch (error) {
+          void error;
         }
       }
     });
@@ -1633,15 +1877,11 @@ var ImageEditor = class {
    * @private
    */
   _syncMaskLabel(mask) {
-    if (!mask)
-      return;
-    if (!this.options.maskLabelOnSelect)
-      return;
-    if (!mask.__label)
-      return;
+    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;
+    if (!coords || coords.length < 4) return;
     const tl = coords[0];
     const center = mask.getCenterPoint();
     const vx = center.x - tl.x;
@@ -1674,12 +1914,9 @@ var ImageEditor = class {
    * @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);
   }
@@ -1699,6 +1936,7 @@ var ImageEditor = class {
           try {
             this.canvas.remove(mask.__label);
           } catch (error) {
+            void error;
           }
           delete mask.__label;
         }
@@ -1711,8 +1949,7 @@ var ImageEditor = class {
         mask.set({ stroke: "#ff0000", strokeWidth: 1 });
       }
     });
-    if (selectedMask)
-      this._showLabelForMask(selectedMask);
+    if (selectedMask) this._showLabelForMask(selectedMask);
     this._updateMaskListSelection(selectedMask);
     this.canvas.renderAll();
     this._updateUI();
@@ -1724,8 +1961,7 @@ var ImageEditor = class {
    */
   _updateMaskList() {
     const maskListElement = document.getElementById(this.elements.maskList);
-    if (!maskListElement)
-      return;
+    if (!maskListElement) return;
     maskListElement.innerHTML = "";
     const masks = this.canvas.getObjects().filter((object) => object.maskId);
     masks.forEach((mask) => {
@@ -1747,8 +1983,7 @@ var ImageEditor = class {
    */
   _updateMaskListSelection(selectedMask) {
     const maskListElement = document.getElementById(this.elements.maskList);
-    if (!maskListElement)
-      return;
+    if (!maskListElement) return;
     const maskItems = maskListElement.querySelectorAll(".mask-item");
     maskItems.forEach((item) => {
       const isSelected = !!selectedMask && item.textContent === selectedMask.maskName;
@@ -1756,70 +1991,79 @@ var ImageEditor = class {
     });
   }
   /**
-   * Merges current masks into the image: exports a masked/cropped image, removes all masks, and re-imports the merged image.
-   * Will not run if no original image or no masks exist.
+   * Flattens the current masks into the base image and reloads the flattened image.
+   *
+   * This removes editable mask objects after export and records the operation as one undoable history transition.
+   * It does nothing when no base image or no masks exist.
+   *
    * @async
-   * @returns {Promise<void>} Resolves when merge and load are complete.
+   * @returns {Promise<void>} Resolves when the flattened image has been loaded.
+   * @public
    */
   async mergeMasks() {
-    if (!this.originalImage)
-      return;
+    if (!this.originalImage) return;
     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);
+      await this.loadImage(merged, { preserveScroll: true });
       const afterJson = this._serializeCanvasState();
       this._pushStateTransition(beforeJson, afterJson);
-    } catch (err) {
-      this._reportError("merge error", err);
+    } catch (error) {
+      this._reportError("merge error", error);
     }
   }
   /**
-   * @deprecated Use mergeMasks() instead.
+   * Backward-compatible alias for {@link ImageEditor#mergeMasks}.
+   *
+   * @deprecated Use mergeMasks() instead. This alias will be removed in v2.0.0.
+   * @returns {Promise<void>} Resolves when mask flattening is complete.
    */
   async merge() {
     return this.mergeMasks();
   }
   /**
-   * Triggers a JPEG image download of the current canvas (image plus masks if configured).
+   * Triggers a JPEG image download of the current canvas.
+   *
    * The image area and multiplier are controlled by options.
    * @param {string} [fileName=this.options.defaultDownloadFileName] - Desired download file name.
+   * @returns {void}
+   * @public
    */
   downloadImage(fileName = this.options.defaultDownloadFileName) {
-    if (!this.originalImage)
-      return;
+    if (!this.originalImage) return;
     const exportImageArea = this.options.exportImageAreaByDefault;
-    this.exportImageBase64({ exportImageArea, multiplier: this.options.exportMultiplier }).then((base64) => {
+    this.exportImageBase64({ exportImageArea, multiplier: this.options.exportMultiplier }).then((imageBase64) => {
       const link = document.createElement("a");
       link.download = fileName;
-      link.href = base64;
+      link.href = imageBase64;
       document.body.appendChild(link);
       link.click();
       document.body.removeChild(link);
-    }).catch((err) => this._reportError("download error", err));
+    }).catch((error) => this._reportError("download error", error));
   }
   /**
-   * Exports the image as a Base64-encoded image data URL.
-   * Can export either the original, or the current view including masks (clipped/cropped).
-   * Will restore masks' state after temporary modifications for export.
+   * Exports the current image as a Base64-encoded data URL.
+   *
+   * When `exportImageArea` is false, the export omits masks and labels. When it is true, masks are
+   * temporarily rendered as opaque export shapes and then restored, so editable mask state is not mutated.
+   *
    * @async
    * @param {Object} [options={}] - Export options.
    * @param {boolean} [options.exportImageArea] - If true, exports only the image bounding area with masks cropped and blended.
    * @param {number} [options.multiplier=1] - Scaling multiplier for output (resolution).
    * @param {number} [options.quality=0.92] - Image quality between 0 and 1 for lossy formats.
    * @param {string} [options.fileType='jpeg'] - Output file type ('jpeg' | 'png' | 'webp').
-   * @returns {Promise<string>} Promise resolving to an image data URL.
+   * @returns {Promise<string>} Resolves with an image data URL.
    * @throws {Error} If there is no image loaded.
+   * @public
    */
   async exportImageBase64(options = {}) {
-    if (!this.originalImage)
-      throw new Error("No image loaded");
+    if (!this.originalImage) throw new Error("No image loaded");
     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);
@@ -1835,12 +2079,9 @@ var ImageEditor = class {
         this.canvas.renderAll();
         this.originalImage.setCoords();
         const imageBounds = this.originalImage.getBoundingRect(true, true);
-        const { sx, sy, sw, sh } = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+        const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
         return await this._exportCanvasRegionToDataURL({
-          sx,
-          sy,
-          sw,
-          sh,
+          ...exportRegion,
           multiplier,
           quality,
           format
@@ -1850,6 +2091,7 @@ var ImageEditor = class {
           try {
             backup.object.set({ visible: backup.visible });
           } catch (error) {
+            void error;
           }
         });
         this.canvas.renderAll();
@@ -1877,12 +2119,9 @@ var ImageEditor = class {
       this.canvas.renderAll();
       this.originalImage.setCoords();
       const imageBounds = this.originalImage.getBoundingRect(true, true);
-      const { sx, sy, sw, sh } = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+      const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
       finalBase64 = await this._exportCanvasRegionToDataURL({
-        sx,
-        sy,
-        sw,
-        sh,
+        ...exportRegion,
         multiplier,
         quality,
         format
@@ -1900,6 +2139,7 @@ var ImageEditor = class {
           });
           backup.object.setCoords();
         } catch (error) {
+          void error;
         }
       });
       this.canvas.renderAll();
@@ -1907,14 +2147,20 @@ var ImageEditor = class {
     return finalBase64;
   }
   /**
-   * @deprecated Use exportImageBase64() instead.
+   * Backward-compatible alias for {@link ImageEditor#exportImageBase64}.
+   *
+   * @deprecated Use exportImageBase64() instead. This alias will be removed in v2.0.0.
+   * @param {Object} [options={}] - Export options passed to exportImageBase64().
+   * @returns {Promise<string>} Resolves with an image data URL.
    */
   async getImageBase64(options = {}) {
     return this.exportImageBase64(options);
   }
   /**
-   * Exports the current canvas (with or without masks) as a File object.
-   * Allows you to choose whether to merge masks and specify file type (jpeg/png/webp).
+   * Exports the current image as a File object.
+   *
+   * The export can include flattened masks (`mergeMask: true`) or only the plain base image (`mergeMask: false`).
+   * Supported output formats are JPEG, PNG, and WebP.
    * 
    * @async
    * @param {Object} [options={}] - Export options.
@@ -1929,8 +2175,7 @@ var ImageEditor = class {
    *   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");
     const {
       mergeMask = true,
       fileType = "jpeg",
@@ -1939,23 +2184,23 @@ var ImageEditor = class {
       fileName = this.options.defaultDownloadFileName ?? "exported_image.jpg"
     } = options;
     const safeFileType = this._normalizeImageFormat(fileType);
-    let base64;
+    let imageBase64;
     if (mergeMask) {
-      base64 = await this.exportImageBase64({
+      imageBase64 = await this.exportImageBase64({
         exportImageArea: true,
         multiplier,
         quality,
         fileType: safeFileType
       });
     } else {
-      base64 = await this.exportImageBase64({
+      imageBase64 = await this.exportImageBase64({
         exportImageArea: false,
         multiplier,
         quality,
         fileType: safeFileType
       });
     }
-    let imageDataUrl = base64;
+    let imageDataUrl = imageBase64;
     if (!imageDataUrl.startsWith(`data:image/${safeFileType}`)) {
       imageDataUrl = await new Promise((resolve, reject) => {
         const imageElement = new window.Image();
@@ -1974,7 +2219,7 @@ var ImageEditor = class {
           }
         };
         imageElement.onerror = reject;
-        imageElement.src = base64;
+        imageElement.src = imageBase64;
       });
     }
     const binaryString = atob(imageDataUrl.split(",")[1]);
@@ -1994,8 +2239,7 @@ var ImageEditor = class {
   }
   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) {
@@ -2010,8 +2254,7 @@ var ImageEditor = class {
       }
     }
     this._updateUI();
-    if (this.canvas)
-      this.canvas.renderAll();
+    if (this.canvas) this.canvas.renderAll();
   }
   _restoreCropObjectState() {
     if (Array.isArray(this._cropPrevEvented)) {
@@ -2023,14 +2266,14 @@ var ImageEditor = class {
             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) => {
@@ -2040,23 +2283,28 @@ var ImageEditor = class {
         });
       }
     } catch (error) {
+      void error;
     }
     try {
       this.canvas.remove(this._cropRect);
     } catch (error) {
+      void error;
     }
     this._cropRect = null;
     this._cropHandlers = [];
   }
   /**
-   * Enter crop mode: create a resizable/movable selection rect on top of the image.
+   * Enters crop mode by creating a resizable crop rectangle above the base image.
+   *
+   * Other canvas objects are made non-interactive while crop mode is active. Masks can be hidden during
+   * cropping when `crop.hideMasksDuringCrop` is enabled.
+   *
+   * @returns {void}
    * @public
    */
   enterCropMode() {
-    if (!this.canvas || !this.originalImage || this._cropMode)
-      return;
-    if (!this.isImageLoaded())
-      return;
+    if (!this.canvas || !this.originalImage || this._cropMode) return;
+    if (!this.isImageLoaded()) return;
     this._cropMode = true;
     this._prevSelectionSetting = this.canvas.selection;
     this.canvas.selection = false;
@@ -2066,8 +2314,14 @@ var ImageEditor = class {
     const padding = this.options.crop && this.options.crop.padding ? this.options.crop.padding : 10;
     const left = Math.max(0, Math.floor(imageBounds.left + padding));
     const top = Math.max(0, Math.floor(imageBounds.top + padding));
-    const width = Math.min(this.options.crop.minWidth || 50, Math.floor(imageBounds.width - padding * 2));
-    const height = Math.min(this.options.crop.minHeight || 50, Math.floor(imageBounds.height - padding * 2));
+    const maxCropWidth = Math.max(1, Math.floor(imageBounds.width - padding * 2));
+    const maxCropHeight = Math.max(1, Math.floor(imageBounds.height - padding * 2));
+    const configuredMinWidth = Math.max(1, Number(this.options.crop.minWidth) || 50);
+    const configuredMinHeight = Math.max(1, Number(this.options.crop.minHeight) || 50);
+    const minCropWidth = Math.min(configuredMinWidth, maxCropWidth);
+    const minCropHeight = Math.min(configuredMinHeight, maxCropHeight);
+    const width = minCropWidth;
+    const height = minCropHeight;
     const cropRect = new fabric.Rect({
       left,
       top,
@@ -2084,7 +2338,8 @@ var ImageEditor = class {
       cornerSize: 8,
       objectCaching: false,
       originX: "left",
-      originY: "top"
+      originY: "top",
+      lockScalingFlip: true
     });
     this.canvas.add(cropRect);
     cropRect.isCropRect = true;
@@ -2101,18 +2356,24 @@ var ImageEditor = class {
             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;
         }
       }
     });
     const handleCropRectModified = () => {
       try {
+        const cropWidth = Math.max(1, Number(cropRect.width) || 1);
+        const cropHeight = Math.max(1, Number(cropRect.height) || 1);
+        const nextScaleX = Math.min(maxCropWidth / cropWidth, Math.max(minCropWidth / cropWidth, Number(cropRect.scaleX) || 1));
+        const nextScaleY = Math.min(maxCropHeight / cropHeight, Math.max(minCropHeight / cropHeight, Number(cropRect.scaleY) || 1));
+        cropRect.set({ scaleX: nextScaleX, scaleY: nextScaleY });
         cropRect.setCoords();
         this.canvas.requestRenderAll();
       } catch (error) {
+        void error;
       }
     };
     cropRect.on("modified", handleCropRectModified);
@@ -2130,12 +2391,13 @@ var ImageEditor = class {
     this.canvas.renderAll();
   }
   /**
-   * Cancel crop mode and remove the temporary selection rect.
+   * Cancels crop mode and removes the temporary crop rectangle.
+   *
+   * @returns {void}
    * @public
    */
   cancelCrop() {
-    if (!this.canvas || !this._cropMode)
-      return;
+    if (!this.canvas || !this._cropMode) return;
     this._removeCropRect();
     this._restoreCropObjectState();
     this._cropMode = false;
@@ -2146,19 +2408,24 @@ var ImageEditor = class {
     this.canvas.renderAll();
   }
   /**
-   * Apply the current crop rectangle.
-   * remove all masks and export canvas snapshot and crop via offscreen canvas
+   * Applies the current crop rectangle to the base image.
+   *
+   * Masks are removed by default. When `crop.preserveMasksAfterCrop` is true, masks that intersect the crop
+   * region are shifted into the cropped coordinate space and remain editable. The operation is recorded as a
+   * single undoable history transition.
+   *
+   * @async
+   * @returns {Promise<void>} Resolves after the cropped image has been loaded and history is updated.
    * @public
    */
   async applyCrop() {
-    if (!this.canvas || !this._cropMode || !this._cropRect)
-      return;
+    if (!this.canvas || !this._cropMode || !this._cropRect) return;
     this._cropRect.setCoords();
     const rectBounds = this._cropRect.getBoundingRect(true, true);
-    const { sx, sy, sw, sh } = 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) {
@@ -2173,13 +2440,13 @@ var ImageEditor = class {
           try {
             mask.setCoords();
             const maskBounds = mask.getBoundingRect(true, true);
-            const intersectsCrop = maskBounds.left < sx + sw && maskBounds.left + maskBounds.width > sx && maskBounds.top < sy + sh && maskBounds.top + maskBounds.height > sy;
+            const intersectsCrop = maskBounds.left < cropRegion.sourceX + cropRegion.sourceWidth && maskBounds.left + maskBounds.width > cropRegion.sourceX && maskBounds.top < cropRegion.sourceY + cropRegion.sourceHeight && maskBounds.top + maskBounds.height > cropRegion.sourceY;
             this._removeLabelForMask(mask);
             this.canvas.remove(mask);
             if (shouldPreserveMasks && intersectsCrop) {
               mask.set({
-                left: (mask.left || 0) - sx,
-                top: (mask.top || 0) - sy,
+                left: (mask.left || 0) - cropRegion.sourceX,
+                top: (mask.top || 0) - cropRegion.sourceY,
                 visible: true
               });
               mask.setCoords();
@@ -2203,10 +2470,7 @@ var ImageEditor = class {
     let croppedBase64;
     try {
       croppedBase64 = await this._exportCanvasRegionToDataURL({
-        sx,
-        sy,
-        sw,
-        sh,
+        ...cropRegion,
         multiplier: 1,
         quality: this._normalizeQuality(this.options.downsampleQuality),
         format: "jpeg"
@@ -2228,21 +2492,21 @@ var ImageEditor = class {
         this._updateMaskList();
         this.canvas.renderAll();
       }
-    } catch (e) {
-      await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: loadImage(croppedBase64) failed", e);
+    } catch (error) {
+      await this._restoreStateAfterCropFailure(beforeJson, "applyCrop: loadImage(croppedBase64) failed", error);
       return;
     }
-    let afterJson = null;
+    let afterJson;
     try {
       afterJson = this._serializeCanvasState();
-    } catch (e) {
-      this._reportWarning("applyCrop: failed to serialize after state", e);
+    } catch (error) {
+      this._reportWarning("applyCrop: failed to serialize after state", error);
       afterJson = null;
     }
     try {
       this._pushStateTransition(beforeJson, afterJson);
-    } catch (e) {
-      this._reportWarning("applyCrop: failed to push history command", e);
+    } catch (error) {
+      this._reportWarning("applyCrop: failed to push history command", error);
     }
     this._updateUI();
     this.canvas.renderAll();
@@ -2255,8 +2519,7 @@ var ImageEditor = class {
    */
   _updateInputs() {
     const scaleInputElement = document.getElementById(this.elements.scaleRate);
-    if (scaleInputElement)
-      scaleInputElement.value = Math.round(this.currentScale * 100);
+    if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
   }
   /**
    * Updates the enabled/disabled state of various UI controls (buttons)
@@ -2276,8 +2539,7 @@ var ImageEditor = class {
     if (isInCropMode) {
       for (const key of Object.keys(this.elements || {})) {
         const element = document.getElementById(this.elements[key]);
-        if (!element)
-          continue;
+        if (!element) continue;
         if (key === "applyCropBtn" || key === "cancelCropBtn") {
           this._setDisabled(key, false);
         } else {
@@ -2313,8 +2575,7 @@ var ImageEditor = class {
    */
   _setDisabled(key, disabled) {
     const element = document.getElementById(this.elements[key]);
-    if (!element)
-      return;
+    if (!element) return;
     if ("disabled" in element) {
       element.disabled = !!disabled;
       return;
@@ -2328,38 +2589,42 @@ var ImageEditor = class {
     }
   }
   _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";
   }
   /**
-   * Automatically display and hide placeholders and containers based on the current image content
+   * Updates placeholder and canvas container visibility based on whether an image is loaded.
    * @private
    */
   _updatePlaceholderStatus() {
-    if (!this.options.showPlaceholder)
-      return;
+    if (!this.options.showPlaceholder) return;
     this._setPlaceholderVisible(!this.originalImage);
   }
   /**
-   * Controls the display/hiding of the Placeholder and Canvas container.
-   * @param {boolean} show - true displays the placeholder, false displays the canvas container
+   * Shows or hides the placeholder and canvas container.
+   *
+   * @param {boolean} show - If true, displays the placeholder; otherwise displays the canvas container.
    * @private
    */
   _setPlaceholderVisible(show) {
-    if (!this.placeholderElement)
-      return;
-    if (show) {
-      this.placeholderElement.classList.remove("d-none");
-      this.placeholderElement.classList.add("d-flex");
-      this.containerElement.classList.add("d-none");
-    } else {
-      this.placeholderElement.classList.remove("d-flex");
-      this.placeholderElement.classList.add("d-none");
-      this.containerElement.classList.remove("d-none");
-    }
+    if (!this.placeholderElement || !this.containerElement) return;
+    this._setElementVisible(this.placeholderElement, show);
+    this._setElementVisible(this.containerElement, !show);
+  }
+  /**
+   * 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;
+    element.hidden = !isVisible;
+    element.setAttribute("aria-hidden", isVisible ? "false" : "true");
+    if (isVisible && element.classList) element.classList.remove("d-none");
   }
   /**
    * Cleans up and disposes of the canvas and related references.
@@ -2371,34 +2636,38 @@ var ImageEditor = class {
       for (const key in this._handlersByElementKey || {}) {
         const handlers = this._handlersByElementKey[key] || [];
         const element = document.getElementById(this.elements[key]);
-        if (!element)
-          continue;
+        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 (e) {
+      } catch (error) {
+        void error;
       }
       this._cropRect = null;
     }
     if (this.containerElement && this._containerOriginalOverflow !== void 0) {
       try {
         this.containerElement.style.overflow = this._containerOriginalOverflow;
-      } catch (e) {
+      } catch (error) {
+        void error;
       }
     }
     if (this.canvas) {
       try {
         this.canvas.dispose();
-      } catch (e) {
+      } catch (error) {
+        void error;
       }
       this.canvas = null;
       this.canvasElement = null;
@@ -2409,54 +2678,52 @@ var ImageEditor = class {
 };
 var AnimationQueue = class {
   /**
-   * Creates a new AnimationQueue.
-   *
-   * @constructor
+   * Creates an empty animation queue.
    */
   constructor() {
-    this.queue = [];
-    this.running = false;
+    this.animationTasks = [];
+    this.isRunning = false;
   }
   /**
    * Adds an animation function to the queue.
    *
-   * @param   {Function} animationFn  A function that returns a Promise or any await-able.
-   * @returns {Promise<*>}            A Promise that resolves/rejects with the animation result.
+   * @param {AnimationTaskCallback} animationFn - Function that returns a value, Promise, or awaitable animation result.
+   * @returns {Promise<unknown>} Resolves or rejects with the queued animation result.
    */
   async add(animationFn) {
     return new Promise((resolve, reject) => {
-      this.queue.push({ fn: animationFn, resolve, reject });
-      if (!this.running) {
-        this.processQueue();
+      this.animationTasks.push({ animationFn, resolve, reject });
+      if (!this.isRunning) {
+        this._drainQueue();
       }
     });
   }
   /**
-   * Internal helper that processes the animation queue sequentially until it is empty.
+   * Runs queued animation tasks sequentially until the queue is empty.
    *
    * @private
    * @returns {Promise<void>}
    */
-  async processQueue() {
-    if (this.queue.length === 0) {
-      this.running = false;
+  async _drainQueue() {
+    if (this.animationTasks.length === 0) {
+      this.isRunning = false;
       return;
     }
-    this.running = true;
-    const { fn, resolve, reject } = this.queue.shift();
+    this.isRunning = true;
+    const { animationFn, resolve, reject } = this.animationTasks.shift();
     try {
-      const result = await fn();
+      const result = await animationFn();
       resolve(result);
     } catch (error) {
       reject(error);
     }
-    this.processQueue();
+    await this._drainQueue();
   }
 };
 var Command = class {
   /**
-   * @param {Function} execute  The function that performs the action.
-   * @param {Function} undo     The function that reverts the action.
+   * @param {HistoryTaskCallback} execute - Function that performs the action.
+   * @param {HistoryTaskCallback} undo - Function that reverts the action.
    */
   constructor(execute, undo) {
     this.execute = execute;
@@ -2465,7 +2732,7 @@ var Command = class {
 };
 var HistoryManager = class {
   /**
-   * @param {number} [maxSize=50]  Maximum number of commands to keep in history.
+   * @param {number} [maxSize=50] - Maximum number of commands to keep in history.
    */
   constructor(maxSize = 50) {
     this.history = [];
@@ -2473,11 +2740,24 @@ var HistoryManager = class {
     this.maxSize = maxSize;
     this.pending = Promise.resolve();
   }
+  /**
+   * Queues a history task after the previously queued undo/redo task completes.
+   *
+   * @param {HistoryTaskCallback} task - Task to run after earlier history work settles.
+   * @returns {Promise<void>} Resolves or rejects with the queued task result.
+   * @private
+   */
   enqueue(task) {
-    const run = this.pending.then(task, task);
-    this.pending = run.catch(() => {
-    });
-    return run;
+    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;
+    return nextTask;
   }
   /**
    * Executes a new command and pushes it onto the history stack.
@@ -2527,7 +2807,7 @@ var HistoryManager = class {
   /**
    * Undoes the last executed command if possible.
    *
-   * @returns {void}
+   * @returns {Promise<void>} Resolves after the undo task completes.
    */
   undo() {
     return this.enqueue(async () => {
@@ -2541,7 +2821,7 @@ var HistoryManager = class {
   /**
    * Redoes the next command in history if possible.
    *
-   * @returns {void}
+   * @returns {Promise<void>} Resolves after the redo task completes.
    */
   redo() {
     return this.enqueue(async () => {