@bensitu/image-editor 1.2.1 → 1.3.0

package/src/image-editor.js

@@ -1,19 +1,20 @@
 /**
  * @file image-editor.js
  * @module image-editor
- * @version 1.2.1
+ * @version 1.3.0
  * @author Ben Situ
  * @license MIT
  * @description Lightweight canvas-based image editor with masking/transform/export support.
- *
- * This source file is free software, available under the MIT license.
- * It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
- * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- * See the license files for details.
  */
 
 let fabric = null;
 
+/**
+ * Returns the ambient global scope used to discover a globally loaded Fabric.js namespace.
+ *
+ * @returns {typeof globalThis|null} The global scope, or null when no standard scope is available.
+ * @private
+ */
 function getGlobalScope() {
     if (typeof globalThis !== 'undefined') return globalThis;
     if (typeof self !== 'undefined') return self;
@@ -21,37 +22,96 @@ function getGlobalScope() {
     return null;
 }
 
+/**
+ * Returns the globally registered Fabric.js namespace when one is available.
+ *
+ * @returns {Object|null} The Fabric.js namespace, or null when Fabric is not registered globally.
+ * @private
+ */
 function getGlobalFabric() {
     const scope = getGlobalScope();
     return scope && scope.fabric ? scope.fabric : null;
 }
 
+/**
+ * Registers the Fabric.js namespace used by ImageEditor instances.
+ *
+ * This helper is exported for the package entry wrappers, not as part of the documented package API.
+ *
+ * @param {Object} [fabricInstance] - Fabric.js namespace object. When omitted, the global `fabric` namespace is used.
+ * @returns {Object|null} The active Fabric.js namespace.
+ * @private
+ */
 export function setFabric(fabricInstance) {
     fabric = fabricInstance || getGlobalFabric();
     return fabric;
 }
 
+/**
+ * Resolves the active Fabric.js namespace, trying the global namespace as a fallback.
+ *
+ * @returns {Object|null} The active Fabric.js namespace.
+ * @private
+ */
 function ensureFabric() {
     if (!fabric) setFabric();
     return fabric;
 }
 
+/**
+ * @callback ImageLoadedCallback
+ * @returns {void}
+ */
+
+/**
+ * @callback EditorErrorCallback
+ * @param {*} error - Recoverable error or warning value, when available.
+ * @param {string} message - Human-readable context for the error or warning.
+ * @returns {void}
+ */
+
+/**
+ * @callback MaskValueResolver
+ * @param {fabric.Canvas} canvas - Active Fabric canvas.
+ * @param {Object} options - Editor options.
+ * @returns {number} Resolved numeric mask value.
+ */
+
+/**
+ * @callback MaskFabricGenerator
+ * @param {Object} config - Normalized mask configuration.
+ * @param {fabric.Canvas} canvas - Active Fabric canvas.
+ * @param {Object} options - Editor options.
+ * @returns {fabric.Object} Custom Fabric object to use as the mask.
+ */
+
+/**
+ * @callback MaskCreateCallback
+ * @param {fabric.Object} mask - Created mask object.
+ * @param {fabric.Canvas} canvas - Active Fabric canvas.
+ * @returns {void}
+ */
+
+/**
+ * @callback MaskLabelTextCallback
+ * @param {fabric.Object} mask - Mask object whose label is being created.
+ * @param {number} creationIndex - Stable zero-based creation index derived from the mask id.
+ * @returns {string} Label text.
+ */
+
+/**
+ * @typedef {Object} LoadImageOptions
+ * @property {boolean} [preserveScroll=false] - If true, keeps the current scroll position while reloading.
+ */
+
     /**
-     * ImageEditor
-     * 
-     * A lightweight wrapper around fabric.js providing masking, scaling, rotation,
-     * merging/export helpers, and UI integrations for image editing.
+     * Fabric.js-based image editor with masking, transform, crop, history, and export helpers.
      *
-     * <b>Note:</b> Requires fabric.js (v5.x) to be loaded on the page before use.
+     * Requires Fabric.js v5.x through the ESM package entry or a globally available `fabric` namespace.
      *
-     * <pre>
-     * Example usage:
+     * @example
      * const editor = new ImageEditor({ canvasWidth: 1024, canvasHeight: 768 });
      * editor.init();
-     * </pre>
-     *
-     * @class ImageEditor
-     * @classdesc Fabric.js-based image editor with simple mask, transform, export and UI features.
      *
      * @param {Object} [options={}] - Customization options to override defaults.
      * @param {number} [options.canvasWidth=800] - The initial canvas width in pixels.
@@ -62,33 +122,36 @@ function ensureFabric() {
      * @param {number} [options.maxScale=5.0] - Maximum image scaling factor.
      * @param {number} [options.scaleStep=0.05] - Scale increment/decrement per step.
      * @param {number} [options.rotationStep=90] - Rotation step in degrees.
-     * @param {boolean} [options.expandCanvasToImage=true] - If true, expands the canvas to fit image/mask.
+     * @param {boolean} [options.expandCanvasToImage=true] - If true, expands the canvas to fit the loaded image.
      * @param {boolean} [options.fitImageToCanvas=false] - If true, fits loaded image inside canvas.
-     * @param {boolean} [options.coverImageToCanvas=false] - If true, scales image to cover canvas (at least one side fits, allowing overflow).
+     * @param {boolean} [options.coverImageToCanvas=false] - If true, scales image to cover the visible canvas viewport.
      * @param {boolean} [options.downsampleOnLoad=true] - Whether to downsample very large images on load.
      * @param {number} [options.downsampleMaxWidth=4000] - Max width for downsampling.
      * @param {number} [options.downsampleMaxHeight=3000] - Max height for downsampling.
      * @param {number} [options.downsampleQuality=0.92] - JPEG quality for downsampling/export.
+     * @param {number} [options.imageLoadTimeoutMs=30000] - Timeout for image decode operations.
      * @param {number} [options.exportMultiplier=1] - Scale output image by this multiplier on export.
      * @param {boolean} [options.exportImageAreaByDefault=true] - Export only the image area (clipped to masks).
-     * @param {number} [options.defaultMaskWidth=50] - Default width of new mask rectangles.
+     * @param {number} [options.defaultMaskWidth=50] - Default width of new masks.
      * @param {number} [options.defaultMaskHeight=80] - Default height of new masks.
      * @param {boolean} [options.maskRotatable=false] - If true, masks can be rotated.
      * @param {boolean} [options.maskLabelOnSelect=true] - Show label on selected mask.
      * @param {number} [options.maskLabelOffset=3] - Offset for mask labels from top-left corner.
      * @param {string} [options.maskName='mask'] - Prefix for mask names/labels.
+     * @param {boolean} [options.groupSelection=false] - If true, Fabric can select multiple masks as an ActiveSelection.
      * @param {boolean} [options.showPlaceholder=true] - If true, shows placeholder when no image is loaded.
      * @param {string|null} [options.initialImageBase64=null] - Base64 string to auto-load as initial image, if any.
      * @param {string} [options.defaultDownloadFileName='edited_image.jpg'] - Default file name for downloads.
-     * @param {function} [options.onImageLoaded] - Optional callback to invoke after an image loads.
-     * @param {function} [options.onError] - Optional callback for recoverable internal errors.
-     * @param {function} [options.onWarning] - Optional callback for recoverable internal warnings.
-     * 
-     * @constructor
+     * @param {Object} [options.label] - Mask label customization options.
+     * @param {MaskLabelTextCallback} [options.label.getText] - Callback for label text; receives a stable zero-based creation index.
+     * @param {Object} [options.crop] - Crop mode customization options.
+     * @param {ImageLoadedCallback} [options.onImageLoaded] - Callback invoked after an image load completes.
+     * @param {EditorErrorCallback} [options.onError] - Callback invoked for recoverable internal errors.
+     * @param {EditorErrorCallback} [options.onWarning] - Callback invoked for recoverable internal warnings.
      */
     class ImageEditor {
         constructor(options = {}) {
-            // Default options (can be overridden via ctor param)
+            // Default options that callers can override with constructor options.
             const defaultLabel = {
                 getText: (mask) => mask.maskName,
                 textOptions: {
@@ -133,6 +196,7 @@ function ensureFabric() {
                 downsampleMaxWidth: 4000,
                 downsampleMaxHeight: 3000,
                 downsampleQuality: 0.92,
+                imageLoadTimeoutMs: 30000,
 
                 exportMultiplier: 1,
                 exportImageAreaByDefault: true,
@@ -168,19 +232,19 @@ function ensureFabric() {
                 }
             };
 
-            // Verify that fabric.js is present
+            // Verify that Fabric.js is present before any canvas work starts.
             this._fabricLoaded = !!ensureFabric();
             if (!this._fabricLoaded) {
                 this._reportError('fabric.js is not loaded. Please include fabric.js first. Initialization will be aborted.');
             }
 
-            // Runtime state
+            // Runtime state owned by this editor instance.
             this.canvas = null;
-            this.canvasEl = null;
-            this.containerEl = null;
-            this.placeholderEl = null;
+            this.canvasElement = null;
+            this.containerElement = null;
+            this.placeholderElement = null;
 
-            this.originalImage = null; // fabric.Image
+            this.originalImage = null;
             this.baseImageScale = 1;
             this.currentScale = 1;
             this.currentRotation = 0;
@@ -190,32 +254,80 @@ function ensureFabric() {
             this.isImageLoadedToCanvas = false;
             this.maxHistorySize = 50;
 
-            this._boundHandlers = {};
+            this._handlersByElementKey = {};
 
             this._lastMask = null;
             this._lastMaskInitialLeft = null;
             this._lastMaskInitialTop = null;
             this._lastMaskInitialWidth = null;
+            this._lastSnapshot = null;
 
             this._cropMode = false;
             this._cropRect = null;
             this._cropHandlers = [];
+            this._cropPrevEvented = null;
+            this._prevSelectionSetting = undefined;
+            this._containerOriginalOverflow = undefined;
+            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);
         }
 
+        /**
+         * 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;
+        }
+
+        set canvasEl(value) {
+            this.canvasElement = value;
+        }
+
+        /**
+         * 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;
+        }
+
+        set containerEl(value) {
+            this.containerElement = value;
+        }
+
+        /**
+         * 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;
+        }
+
+        set placeholderEl(value) {
+            this.placeholderElement = value;
+        }
+
         /**
          * Initializes the editor, binds to DOM elements, sets up event handlers,
          * and (optionally) loads an initial image.
          * 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}
          *
@@ -295,52 +407,123 @@ function ensureFabric() {
         }
 
         /**
-         * Canvas setup helpers
+         * Initializes the Fabric canvas, viewport elements, and selection event handlers.
+         *
+         * @returns {void}
          * @private
          */
         _initCanvas() {
-            const canvasEl = document.getElementById(this.elements.canvas);
-            if (!canvasEl) throw new Error('Canvas is not found: ' + this.elements.canvas);
-            this.canvasEl = canvasEl;
+            const canvasElement = document.getElementById(this.elements.canvas);
+            if (!canvasElement) throw new Error('Canvas is not found: ' + this.elements.canvas);
+            this.canvasElement = canvasElement;
 
-            // Decide which element acts as "viewport" (for width/height fallback)
+            // Decide which element acts as the viewport for size fallback and scrolling.
             if (this.elements.canvasContainer) {
-                const ce = document.getElementById(this.elements.canvasContainer);
-                this.containerEl = ce || canvasEl.parentElement;
+                const containerElement = document.getElementById(this.elements.canvasContainer);
+                this.containerElement = containerElement || canvasElement.parentElement;
             } else {
-                this.containerEl = canvasEl.parentElement;
+                this.containerElement = canvasElement.parentElement;
             }
 
-            this.placeholderEl = document.getElementById(this.elements.imgPlaceholder) || null;
-
-            // Initial size — take container size if available
-            let initialW = this.options.canvasWidth;
-            let initialH = this.options.canvasHeight;
-            if (this.containerEl) {
-                const cw = Math.floor(this.containerEl.clientWidth);
-                const ch = Math.floor(this.containerEl.clientHeight);
-                if (cw > 0 && ch > 0) { initialW = cw; initialH = ch; }
+            this.placeholderElement = document.getElementById(this.elements.imgPlaceholder) || null;
+
+            // Prefer a measured container size when it is available.
+            let initialWidth = this.options.canvasWidth;
+            let initialHeight = this.options.canvasHeight;
+            if (this.containerElement) {
+                const containerWidth = Math.floor(this.containerElement.clientWidth);
+                const containerHeight = Math.floor(this.containerElement.clientHeight);
+                if (containerWidth > 0 && containerHeight > 0) {
+                    initialWidth = containerWidth;
+                    initialHeight = containerHeight;
+                }
             }
 
-            this.canvas = new fabric.Canvas(canvasEl, {
-                width: initialW,
-                height: initialH,
+            this.canvas = new fabric.Canvas(canvasElement, {
+                width: initialWidth,
+                height: initialHeight,
                 backgroundColor: this.options.backgroundColor,
                 selection: this.options.groupSelection,
                 preserveObjectStacking: true
             });
 
-            // Fabric event wiring
-            this.canvas.on('selection:created', (e) => this._onSelectionChanged(e.selected));
-            this.canvas.on('selection:updated', (e) => this._onSelectionChanged(e.selected));
-            this.canvas.on('selection:cleared', () => this._onSelectionChanged([]));
-            this.canvas.on('object:moving', (e) => { if (e.target && e.target.maskId) this._syncMaskLabel(e.target); });
-            this.canvas.on('object:scaling', (e) => { if (e.target && e.target.maskId) this._syncMaskLabel(e.target); });
-            this.canvas.on('object:rotating', (e) => { if (e.target && e.target.maskId) this._syncMaskLabel(e.target); });
-            this.canvas.on('object:modified', (e) => { if (e.target && e.target.maskId) this._syncMaskLabel(e.target); });
+            // Fabric event wiring keeps selection, mask labels, and history in sync.
+            this.canvas.on('selection:created', (event) => this._handleSelectionChanged(event.selected));
+            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); });
+            this.canvas.on('object:scaling', (event) => { 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); });
+            this.canvas.on('object:modified', (event) => this._handleObjectModified(event.target));
+
+            // Avoid inline-element whitespace artifacts around the canvas.
+            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;
+            masks.forEach(mask => {
+                if (typeof mask.setCoords === 'function') mask.setCoords();
+                this._syncMaskLabel(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];
+
+            const objects = typeof target.getObjects === 'function' ? target.getObjects() : [];
 
-            // Avoid inline-element whitespace artefacts
-            this.canvasEl.style.display = 'block';
+            return Array.isArray(objects) ? objects.filter(object => object && object.maskId) : [];
+        }
+
+        /**
+         * 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 === undefined) {
+                this._containerOriginalOverflow = this.containerElement.style.overflow || '';
+            }
+
+            const shouldPreserveScroll = options.preserveScroll === true;
+            if (this.options.coverImageToCanvas) {
+                this.containerElement.style.overflow = 'scroll';
+                if (!shouldPreserveScroll) {
+                    this.containerElement.scrollLeft = 0;
+                    this.containerElement.scrollTop = 0;
+                }
+            } else if (this.options.fitImageToCanvas) {
+                this.containerElement.style.overflow = 'auto';
+                if (!shouldPreserveScroll) {
+                    this.containerElement.scrollLeft = 0;
+                    this.containerElement.scrollTop = 0;
+                }
+            } else {
+                this.containerElement.style.overflow = this._containerOriginalOverflow;
+            }
         }
 
         /** 
@@ -349,173 +532,201 @@ function ensureFabric() {
          */
         _bindEvents() {
             // Click anywhere on the upload area opens the native file dialog
-            this._bindIfExists('uploadArea', 'click', () => document.getElementById(this.elements.imageInput)?.click());
+            this._bindIfExists('uploadArea', 'click', () => {
+                const uploadAreaElement = document.getElementById(this.elements.uploadArea);
+                if (this._isElementDisabled(uploadAreaElement)) return;
+                document.getElementById(this.elements.imageInput)?.click();
+            });
             // File-input change
-            const inputEl = document.getElementById(this.elements.imageInput);
-            if (inputEl) {
-                inputEl.addEventListener('change', (e) => {
-                    const f = e.target.files && e.target.files[0];
-                    if (f) this._loadImageFile(f);
-                });
-            }
+            this._bindIfExists('imageInput', 'change', (event) => {
+                const file = event.target.files && event.target.files[0];
+                if (file) this._loadImageFile(file);
+            });
             // Zoom & reset
             this._bindIfExists('zoomInBtn', 'click', () => this.scaleImage(this.currentScale + this.options.scaleStep));
             this._bindIfExists('zoomOutBtn', 'click', () => this.scaleImage(this.currentScale - this.options.scaleStep));
-            this._bindIfExists('resetBtn', 'click', () => { this.reset(); });
+            this._bindIfExists('resetBtn', 'click', () => { this.resetImageTransform(); });
             // Mask management
-            this._bindIfExists('addMaskBtn', 'click', () => this.addMask());
+            this._bindIfExists('addMaskBtn', 'click', () => this.createMask());
             this._bindIfExists('removeMaskBtn', 'click', () => this.removeSelectedMask());
             this._bindIfExists('removeAllMasksBtn', 'click', () => this.removeAllMasks());
             // Merge + download
-            this._bindIfExists('mergeBtn', 'click', () => this.merge());
+            this._bindIfExists('mergeBtn', 'click', () => this.mergeMasks());
             this._bindIfExists('downloadBtn', 'click', () => this.downloadImage());
             // Undo + Redo
             this._bindIfExists('undoBtn', 'click', () => this.undo());
             this._bindIfExists('redoBtn', 'click', () => this.redo());
 
             // Rotation buttons (step can be overridden by two input fields)
-            const rotLeftBtn = document.getElementById(this.elements.rotateLeftBtn);
-            const rotRightBtn = document.getElementById(this.elements.rotateRightBtn);
-            if (rotLeftBtn) rotLeftBtn.addEventListener('click', () => {
-                const el = document.getElementById(this.elements.rotationLeftInput);
+            this._bindIfExists('rotateLeftBtn', 'click', () => {
+                const rotationInputElement = document.getElementById(this.elements.rotationLeftInput);
                 let step = this.options.rotationStep;
-                if (el) { const p = parseFloat(el.value); if (!isNaN(p)) step = p; }
+                if (rotationInputElement) {
+                    const parsedStep = parseFloat(rotationInputElement.value);
+                    if (!isNaN(parsedStep)) step = parsedStep;
+                }
                 this.rotateImage(this.currentRotation - step);
             });
-            if (rotRightBtn) rotRightBtn.addEventListener('click', () => {
-                const el = document.getElementById(this.elements.rotationRightInput);
+            this._bindIfExists('rotateRightBtn', 'click', () => {
+                const rotationInputElement = document.getElementById(this.elements.rotationRightInput);
                 let step = this.options.rotationStep;
-                if (el) { const p = parseFloat(el.value); if (!isNaN(p)) step = p; }
+                if (rotationInputElement) {
+                    const parsedStep = parseFloat(rotationInputElement.value);
+                    if (!isNaN(parsedStep)) step = parsedStep;
+                }
                 this.rotateImage(this.currentRotation + step);
             });
 
             // Crop bindings (optional: bound only if element IDs exist in elements)
             this._bindIfExists('cropBtn', 'click', () => this.enterCropMode());
-            this._bindIfExists('applyCropBtn', 'click', () => { this.applyCrop().catch(e => this._reportError('applyCrop failed', e)); });
+            this._bindIfExists('applyCropBtn', 'click', () => { this.applyCrop().catch(error => this._reportError('applyCrop failed', error)); });
             this._bindIfExists('cancelCropBtn', 'click', () => this.cancelCrop());
         }
 
-        /** 
-         * Event binding element check
-         * 
-         * @param {*} event 
-         * @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, event, handler) {
-            const el = document.getElementById(this.elements[key]);
-            if (el) {
-                el.addEventListener(event, handler);
-                this._boundHandlers = this._boundHandlers || {};
-                if (!this._boundHandlers[key]) this._boundHandlers[key] = [];
-                this._boundHandlers[key].push({ event, handler });
+        _bindIfExists(key, eventName, handler) {
+            const element = document.getElementById(this.elements[key]);
+            if (element) {
+                element.addEventListener(eventName, handler);
+                this._handlersByElementKey = this._handlersByElementKey || {};
+                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;
             const reader = new FileReader();
-            reader.onload = (e) => this.loadImage(e.target.result);
-            reader.onerror = (e) => { this._reportError('Image file could not be read', e); };
+            reader.onload = (event) => this.loadImage(event.target.result);
+            reader.onerror = (event) => { this._reportError('Image file could not be read', event); };
             reader.readAsDataURL(file);
         }
 
         /**
-        * Load a base64 encoded image string into fabric.
-        * @async
-        * @param {String} base64 
-        */
-        async loadImage(base64) {
+         * Warns when more than one mutually exclusive image layout mode is enabled.
+         *
+         * @returns {void}
+         * @private
+         */
+        _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 (!base64 || typeof base64 !== 'string' || !base64.startsWith('data:image/')) return;
+            if (!imageBase64 || typeof imageBase64 !== 'string' || !imageBase64.startsWith('data:image/')) return;
 
+            this._warnOnImageLayoutOptionConflict();
             this._setPlaceholderVisible(false);
+            this._syncContainerOverflow({ preserveScroll: options.preserveScroll === true });
 
-            const imgEl = await this._createImageElement(base64);
+            const imageElement = await this._createImageElement(imageBase64);
 
-            let loadSrc = base64;
+            let loadSource = imageBase64;
             if (this.options.downsampleOnLoad) {
-                const needResize =
-                    imgEl.naturalWidth > this.options.downsampleMaxWidth ||
-                    imgEl.naturalHeight > this.options.downsampleMaxHeight;
-                if (needResize) {
+                const shouldResize =
+                    imageElement.naturalWidth > this.options.downsampleMaxWidth ||
+                    imageElement.naturalHeight > this.options.downsampleMaxHeight;
+                if (shouldResize) {
                     const ratio = Math.min(
-                        this.options.downsampleMaxWidth / imgEl.naturalWidth,
-                        this.options.downsampleMaxHeight / imgEl.naturalHeight
+                        this.options.downsampleMaxWidth / imageElement.naturalWidth,
+                        this.options.downsampleMaxHeight / imageElement.naturalHeight
                     );
-                    const tw = Math.round(imgEl.naturalWidth * ratio);
-                    const th = Math.round(imgEl.naturalHeight * ratio);
-                    loadSrc = this._resampleImageToDataURL(imgEl, tw, th, this.options.downsampleQuality);
+                    const targetWidth = Math.round(imageElement.naturalWidth * ratio);
+                    const targetHeight = Math.round(imageElement.naturalHeight * ratio);
+                    loadSource = this._resampleImageToDataURL(imageElement, targetWidth, targetHeight, this.options.downsampleQuality);
                 }
             }
 
             // Create fabric.Image from URL
             return new Promise((resolve, reject) => {
-                fabric.Image.fromURL(loadSrc, (fimg) => {
+                fabric.Image.fromURL(loadSource, (fabricImage) => {
                     try {
-                        if (!fimg) 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();
                         this.canvas.setBackgroundColor(this.options.backgroundColor, this.canvas.renderAll.bind(this.canvas));
 
-                        fimg.set({ originX: 'left', originY: 'top', selectable: false, evented: false });
+                        fabricImage.set({ originX: 'left', originY: 'top', selectable: false, evented: false });
 
-                        const imgW = fimg.width;
-                        const imgH = fimg.height;
+                        const imageWidth = fabricImage.width;
+                        const imageHeight = fabricImage.height;
 
-                        const minW = this.containerEl ? Math.floor(this.containerEl.clientWidth || this.options.canvasWidth) : this.options.canvasWidth;
-                        const minH = this.containerEl ? Math.floor(this.containerEl.clientHeight || this.options.canvasHeight) : this.options.canvasHeight;
+                        const viewport = this._getContainerViewportSize();
+                        const minWidth = viewport.width;
+                        const minHeight = viewport.height;
 
                         if (this.options.fitImageToCanvas) {
-                            // Fit into current canvas (shrink only) and ensure canvas does not exceed container
-                            const cw = Math.max(1, Math.min(this.options.canvasWidth, minW) - 1)
-                            const ch = Math.max(1, Math.min(this.options.canvasHeight, minH) - 1);
-                            this._setCanvasSizeInt(cw, ch);
-                            const fitScale = Math.min(cw / imgW, ch / imgH, 1);
-                            fimg.set({ left: 0, top: 0 });
-                            fimg.scale(fitScale);
-                            this.baseImageScale = fimg.scaleX || 1;
+                            // Fit into the visible viewport, shrinking only when the image is larger.
+                            const canvasWidth = Math.max(1, minWidth - 1);
+                            const canvasHeight = Math.max(1, minHeight - 1);
+                            this._setCanvasSizeInt(canvasWidth, canvasHeight);
+                            const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
+                            fabricImage.set({ left: 0, top: 0 });
+                            fabricImage.scale(fitScale);
+                            this.baseImageScale = fabricImage.scaleX || 1;
                         } else if (this.options.coverImageToCanvas) {
-                            // Cover canvas: scale to cover, allowing overflow (at least one side fits)
-                            const cw = Math.max(this.options.canvasWidth, minW);
-                            const ch = Math.max(this.options.canvasHeight, minH);
-                            this._setCanvasSizeInt(cw, ch);
-                            const coverScale = Math.min(1, Math.max(cw / imgW, ch / imgH));
-                            fimg.set({ left: 0, top: 0 });
-                            fimg.scale(coverScale);
-                            this.baseImageScale = fimg.scaleX || 1;
+                            const layout = this._calculateCoverCanvasLayout(imageWidth, imageHeight);
+                            this._setCanvasSizeInt(layout.canvasWidth, layout.canvasHeight);
+                            fabricImage.set({ left: 0, top: 0 });
+                            fabricImage.scale(layout.scale);
+                            this.baseImageScale = fabricImage.scaleX || 1;
                         } else if (this.options.expandCanvasToImage) {
                             // Expand canvas so that it fully contains the image
-                            const cw = Math.max(minW, Math.floor(imgW));
-                            const ch = Math.max(minH, Math.floor(imgH));
-                            this._setCanvasSizeInt(cw, ch);
-                            fimg.set({ left: 0, top: 0 });
-                            fimg.scale(1);
+                            const canvasWidth = Math.max(minWidth, Math.floor(imageWidth));
+                            const canvasHeight = Math.max(minHeight, Math.floor(imageHeight));
+                            this._setCanvasSizeInt(canvasWidth, canvasHeight);
+                            fabricImage.set({ left: 0, top: 0 });
+                            fabricImage.scale(1);
                             this.baseImageScale = 1;
                         } else {
                             // Keep existing canvas size and center the image
-                            const cw = Math.max(this.options.canvasWidth, minW);
-                            const ch = Math.max(this.options.canvasHeight, minH);
-                            this._setCanvasSizeInt(cw, ch);
-                            const fitScale = Math.min(cw / imgW, ch / imgH, 1);
-                            fimg.set({ left: 0, top: 0 });
-                            fimg.scale(fitScale);
-                            this.baseImageScale = fimg.scaleX || 1;
+                            const canvasWidth = Math.max(this.options.canvasWidth, minWidth);
+                            const canvasHeight = Math.max(this.options.canvasHeight, minHeight);
+                            this._setCanvasSizeInt(canvasWidth, canvasHeight);
+                            const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
+                            fabricImage.set({ left: 0, top: 0 });
+                            fabricImage.scale(fitScale);
+                            this.baseImageScale = fabricImage.scaleX || 1;
                         }
                         // Put the image onto the canvas
-                        this.originalImage = fimg;
-                        this.canvas.add(fimg);
-                        this.canvas.sendToBack(fimg);
+                        this.originalImage = fabricImage;
+                        this.canvas.add(fabricImage);
+                        this.canvas.sendToBack(fabricImage);
 
                         // Reset mask placement memory
                         this._lastMask = null;
@@ -532,14 +743,19 @@ function ensureFabric() {
                         this.isImageLoadedToCanvas = true;
                         this._updateUI();
                         this.canvas.renderAll();
+                        try {
+                            this._lastSnapshot = this._serializeCanvasState();
+                        } catch (error) {
+                            this._reportWarning('loadImage: failed to capture initial canvas snapshot', error);
+                        }
 
                         if (typeof this.onImageLoaded === 'function') {
                             this.onImageLoaded();
                         }
 
                         resolve();
-                    } catch (err) {
-                        reject(err);
+                    } catch (error) {
+                        reject(error);
                     }
                 }, { crossOrigin: 'anonymous' });
             });
@@ -563,116 +779,558 @@ function ensureFabric() {
         /**
          * Creates an HTMLImageElement from a given data URL.
          * 
-         * @param {string} dataURL - A data URL representing the image (e.g., "data:image/png;base64,...").
+         * @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) {
-            return new Promise((res, rej) => {
-                const img = new Image();
-                img.onload = () => {
-                    img.onload = null;
-                    img.onerror = null;
-                    res(img);
-                };
-                img.onerror = (e) => {
-                    img.onload = null;
-                    img.onerror = null;
-                    rej(e);
+        _createImageElement(dataUrl, timeoutMs = this.options.imageLoadTimeoutMs) {
+            return new Promise((resolve, reject) => {
+                const imageElement = new Image();
+                let isSettled = false;
+                const safeTimeoutMs = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0
+                    ? Number(timeoutMs)
+                    : 30000;
+                let timerId;
+                const settle = (callback) => {
+                    if (isSettled) return;
+                    isSettled = true;
+                    clearTimeout(timerId);
+                    imageElement.onload = null;
+                    imageElement.onerror = null;
+                    callback();
                 };
-                img.src = dataURL;
+                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;
             });
         }
 
         /**
          * Resamples the given image element to a new width and height and returns the result as a JPEG data URL.
          * 
-         * @param {HTMLImageElement} imgEl - The image element to resample.
-         * @param {number} w - Target width (in pixels) for the resampled image.
-         * @param {number} h - Target height (in pixels) for the resampled image.
+         * @param {HTMLImageElement} imageElement - The image element to resample.
+         * @param {number} targetWidth - Target width (in pixels) for the resampled image.
+         * @param {number} targetHeight - Target height (in pixels) for the resampled image.
          * @param {number} [quality=0.92] - JPEG image quality between 0 and 1 (optional, default 0.92).
          * @returns {string} A data URL representing the resampled image as JPEG.
          * @private
          */
-        _resampleImageToDataURL(imgEl, w, h, quality = 0.92) {
-            const oc = document.createElement('canvas');
-            oc.width = w;
-            oc.height = h;
-            const ctx = oc.getContext('2d');
-            ctx.drawImage(imgEl, 0, 0, imgEl.naturalWidth, imgEl.naturalHeight, 0, 0, w, h);
-            return oc.toDataURL('image/jpeg', quality);
+        _resampleImageToDataURL(imageElement, targetWidth, targetHeight, quality = 0.92) {
+            const offscreenCanvas = document.createElement('canvas');
+            offscreenCanvas.width = targetWidth;
+            offscreenCanvas.height = targetHeight;
+            const context = offscreenCanvas.getContext('2d');
+            if (!context) throw new Error('2D canvas context is unavailable');
+            context.drawImage(imageElement, 0, 0, imageElement.naturalWidth, imageElement.naturalHeight, 0, 0, targetWidth, targetHeight);
+            return offscreenCanvas.toDataURL('image/jpeg', quality);
         }
 
         /** 
          * 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));
+        _setCanvasSizeInt(width, height) {
+            const integerWidth = Math.max(1, Math.round(Number(width) || 1));
+            const integerHeight = Math.max(1, Math.round(Number(height) || 1));
             // Set fabric internal and also style attributes to keep DOM consistent
-            this.canvas.setWidth(iw);
-            this.canvas.setHeight(ih);
+            this.canvas.setWidth(integerWidth);
+            this.canvas.setHeight(integerHeight);
             if (typeof this.canvas.calcOffset === 'function') this.canvas.calcOffset();
             // Keep DOM element in sync (avoid fractional CSS pixels)
-            if (this.canvasEl) {
-                this.canvasEl.style.width = iw + 'px';
-                this.canvasEl.style.height = ih + 'px';
-                this.canvasEl.style.maxWidth = 'none';
+            if (this.canvasElement) {
+                this.canvasElement.style.width = integerWidth + 'px';
+                this.canvasElement.style.height = integerHeight + 'px';
+                this.canvasElement.style.maxWidth = 'none';
+            }
+        }
+
+        _ceilCanvasDimension(value) {
+            const numericValue = Number(value) || 0;
+            const roundedValue = Math.round(numericValue);
+            if (Math.abs(numericValue - roundedValue) < 0.01) return roundedValue;
+            return Math.ceil(numericValue);
+        }
+
+        _getContainerViewportSize() {
+            if (!this.containerElement) {
+                return {
+                    width: Math.max(1, Math.floor(this.options.canvasWidth || 1)),
+                    height: Math.max(1, Math.floor(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))
+                };
+            }
+
+            const width = Math.max(1, Math.floor(this.containerElement.clientWidth || this.options.canvasWidth || 1));
+            const height = Math.max(1, Math.floor(this.containerElement.clientHeight || this.options.canvasHeight || 1));
+
+            return { width, height };
+        }
+
+        _hasFixedContainerScrollbars() {
+            if (!this.containerElement) return false;
+            const inlineOverflow = this.containerElement.style.overflow;
+            const inlineOverflowX = this.containerElement.style.overflowX;
+            const inlineOverflowY = this.containerElement.style.overflowY;
+            let computedOverflow = '';
+            let computedOverflowX = '';
+            let computedOverflowY = '';
+
+            if (typeof window !== 'undefined' && typeof window.getComputedStyle === 'function') {
+                const style = window.getComputedStyle(this.containerElement);
+                computedOverflow = style.overflow;
+                computedOverflowX = style.overflowX;
+                computedOverflowY = style.overflowY;
+            }
+
+            return [inlineOverflow, inlineOverflowX, inlineOverflowY, computedOverflow, computedOverflowX, computedOverflowY]
+                .some(value => value === 'scroll');
+        }
+
+        _getScrollbarSize() {
+            if (this._scrollbarSizeCache) {
+                return { ...this._scrollbarSizeCache };
             }
+            if (typeof document === 'undefined' || !document.createElement || !document.body) {
+                return { width: 0, height: 0 };
+            }
+
+            const probe = document.createElement('div');
+            probe.style.position = 'absolute';
+            probe.style.visibility = 'hidden';
+            probe.style.overflow = 'scroll';
+            probe.style.width = '100px';
+            probe.style.height = '100px';
+            probe.style.top = '-9999px';
+            document.body.appendChild(probe);
+
+            const width = Math.max(0, probe.offsetWidth - probe.clientWidth);
+            const height = Math.max(0, probe.offsetHeight - probe.clientHeight);
+            document.body.removeChild(probe);
+
+            this._scrollbarSizeCache = { width, height };
+            return { ...this._scrollbarSizeCache };
+        }
+
+        _getScrollSafetyMargin() {
+            return 2;
+        }
+
+        _getScrollableCanvasSize(contentWidth, contentHeight, viewport = this._getContainerViewportSize()) {
+            if (this._hasFixedContainerScrollbars()) {
+                const safetyMargin = this._getScrollSafetyMargin();
+                const safeWidth = Math.max(1, viewport.width - safetyMargin);
+                const safeHeight = Math.max(1, viewport.height - safetyMargin);
+                return {
+                    width: contentWidth > viewport.width + 0.5 ? this._ceilCanvasDimension(contentWidth) : safeWidth,
+                    height: contentHeight > viewport.height + 0.5 ? this._ceilCanvasDimension(contentHeight) : safeHeight,
+                    viewportWidth: viewport.width,
+                    viewportHeight: viewport.height,
+                    hasHorizontal: true,
+                    hasVertical: true
+                };
+            }
+
+            const scrollbar = this._getScrollbarSize();
+            let hasVertical = false;
+            let hasHorizontal = false;
+            let effectiveWidth = viewport.width;
+            let effectiveHeight = viewport.height;
+
+            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;
+                hasVertical = nextHasVertical;
+                hasHorizontal = nextHasHorizontal;
+            }
+
+            effectiveWidth = Math.max(1, viewport.width - (hasVertical ? scrollbar.width : 0));
+            effectiveHeight = Math.max(1, viewport.height - (hasHorizontal ? scrollbar.height : 0));
+
+            return {
+                width: hasHorizontal ? this._ceilCanvasDimension(contentWidth) : effectiveWidth,
+                height: hasVertical ? this._ceilCanvasDimension(contentHeight) : effectiveHeight,
+                viewportWidth: effectiveWidth,
+                viewportHeight: effectiveHeight,
+                hasHorizontal,
+                hasVertical
+            };
+        }
+
+        _calculateCoverCanvasLayout(imageWidth, imageHeight) {
+            const viewport = this._getContainerViewportSize();
+
+            if (this._hasFixedContainerScrollbars()) {
+                const safetyMargin = this._getScrollSafetyMargin();
+                const targetWidth = Math.max(1, viewport.width - safetyMargin);
+                const targetHeight = Math.max(1, viewport.height - safetyMargin);
+                const scale = Math.min(1, Math.max(targetWidth / imageWidth, targetHeight / imageHeight));
+                const contentWidth = imageWidth * scale;
+                const contentHeight = imageHeight * scale;
+                const canvasSize = this._getScrollableCanvasSize(contentWidth, contentHeight, viewport);
+                return {
+                    scale,
+                    canvasWidth: canvasSize.width,
+                    canvasHeight: canvasSize.height
+                };
+            }
+
+            const scrollbar = this._getScrollbarSize();
+            let hasVertical = false;
+            let hasHorizontal = false;
+            let scale = 1;
+            let contentWidth = imageWidth;
+            let contentHeight = imageHeight;
+            let effectiveWidth = viewport.width;
+            let effectiveHeight = viewport.height;
+
+            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));
+                scale = Math.min(1, Math.max(effectiveWidth / imageWidth, effectiveHeight / imageHeight));
+                contentWidth = imageWidth * scale;
+                contentHeight = imageHeight * scale;
+
+                const nextHasVertical = contentHeight > effectiveHeight + 0.5;
+                const nextHasHorizontal = contentWidth > effectiveWidth + 0.5;
+
+                if (nextHasVertical === hasVertical && nextHasHorizontal === hasHorizontal) break;
+                hasVertical = nextHasVertical;
+                hasHorizontal = nextHasHorizontal;
+            }
+
+            const canvasSize = this._getScrollableCanvasSize(contentWidth, contentHeight, viewport);
+            return {
+                scale,
+                canvasWidth: canvasSize.width,
+                canvasHeight: canvasSize.height
+            };
+        }
+
+        _getStateProperties() {
+            return [
+                'maskId',
+                'maskName',
+                'maskLabel',
+                'isCropRect',
+                'originalAlpha',
+                'originalStroke',
+                'originalStrokeWidth',
+                'selectable',
+                'evented',
+                'hasControls',
+                'lockRotation',
+                'borderColor',
+                'cornerColor',
+                'cornerSize',
+                'transparentCorners',
+                'strokeUniform',
+                'strokeDashArray'
+            ];
+        }
+
+        _getMaskNormalStyle(mask) {
+            const strokeWidth = Number(mask && mask.originalStrokeWidth);
+            const opacity = Number(mask && mask.originalAlpha);
+            const style = {
+                stroke: (mask && mask.originalStroke) || '#ccc',
+                strokeWidth: Number.isFinite(strokeWidth) ? strokeWidth : 1
+            };
+            if (Number.isFinite(opacity)) style.opacity = opacity;
+            return style;
+        }
+
+        _withNormalizedMaskStyles(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
+            }));
+
+            try {
+                masks.forEach(mask => {
+                    mask.set(this._getMaskNormalStyle(mask));
+                });
+                return callback();
+            } finally {
+                maskStyleBackups.forEach(backup => {
+                    try {
+                        backup.object.set({
+                            stroke: backup.stroke,
+                            strokeWidth: backup.strokeWidth,
+                            opacity: backup.opacity
+                        });
+                    } catch (error) { void error; }
+                });
+            }
+        }
+
+        _restoreMaskControls(mask) {
+            if (!mask) return;
+
+            const cornerSize = Number(mask.cornerSize);
+            mask.set({
+                selectable: mask.selectable !== false,
+                evented: mask.evented !== false,
+                hasControls: mask.hasControls !== false,
+                lockRotation: typeof mask.lockRotation === 'boolean' ? mask.lockRotation : !this.options.maskRotatable,
+                borderColor: mask.borderColor || 'red',
+                cornerColor: mask.cornerColor || 'black',
+                cornerSize: Number.isFinite(cornerSize) ? cornerSize : 8,
+                transparentCorners: mask.transparentCorners === true,
+                strokeUniform: mask.strokeUniform !== false
+            });
+            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;
+            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;
+            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',
+                'jpg': 'jpeg',
+                'image/jpeg': 'jpeg',
+                'png': 'png',
+                'image/png': 'png',
+                'webp': 'webp',
+                'image/webp': 'webp'
+            };
+            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()));
+            const left = Number(bounds.left) || 0;
+            const top = Number(bounds.top) || 0;
+            const width = Math.max(0, Number(bounds.width) || 0);
+            const height = Math.max(0, Number(bounds.height) || 0);
+            const includePartialPixels = options.includePartialPixels !== false;
+            const roundEnd = includePartialPixels ? Math.ceil : Math.floor;
+            const sourceX = Math.min(canvasWidth - 1, Math.max(0, Math.floor(left)));
+            const sourceY = Math.min(canvasHeight - 1, Math.max(0, Math.floor(top)));
+            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 {
+                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 : 30000;
+                let timerId;
+                const settle = (callback) => {
+                    if (isSettled) return;
+                    isSettled = true;
+                    clearTimeout(timerId);
+                    imageElement.onload = null;
+                    imageElement.onerror = null;
+                    callback();
+                };
+                timerId = setTimeout(() => {
+                    settle(() => reject(new Error('Image crop load timed out')));
+                    try { imageElement.src = ''; } catch (error) { void error; }
+                }, safeTimeoutMs);
+                imageElement.onload = () => {
+                    try {
+                        const safeMultiplier = Math.max(1, Number(multiplier) || 1);
+                        const scaledSourceX = Math.round(sourceX * safeMultiplier);
+                        const scaledSourceY = Math.round(sourceY * safeMultiplier);
+                        const scaledSourceWidth = Math.max(1, Math.round(sourceWidth * safeMultiplier));
+                        const scaledSourceHeight = Math.max(1, Math.round(sourceHeight * safeMultiplier));
+                        const offscreenCanvas = document.createElement('canvas');
+                        offscreenCanvas.width = scaledSourceWidth;
+                        offscreenCanvas.height = scaledSourceHeight;
+                        const context = offscreenCanvas.getContext('2d');
+                        if (!context) throw new Error('2D canvas context is unavailable');
+
+                        context.drawImage(imageElement, scaledSourceX, scaledSourceY, scaledSourceWidth, scaledSourceHeight, 0, 0, scaledSourceWidth, scaledSourceHeight);
+                        settle(() => resolve(offscreenCanvas.toDataURL(`image/${format}`, quality)));
+                    } catch (error) {
+                        settle(() => reject(error));
+                    }
+                };
+                imageElement.onerror = (error) => settle(() => reject(error));
+                imageElement.src = dataUrl;
+            });
+        }
+
+        /**
+         * 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, sourceX, sourceY, sourceWidth, sourceHeight, safeMultiplier, format, quality);
         }
 
         /** 
          * Gets the top-left corner coordinates of the given object.
          * Used for geometry calculations (e.g., scale, rotate).
          * 
-         * @param {Object} obj - The object for which to get the top-left coordinates. Should support setCoords and getCoords/getBoundingRect methods.
+         * @param {Object} fabricObject - The object for which to get the top-left coordinates. Should support setCoords and getCoords/getBoundingRect methods.
          * @returns {{x: number, y: number}} The top-left corner point as an object with x and y properties.
          * @private
          */
-        _getObjectTopLeftPoint(obj) {
-            if (!obj) return { x: 0, y: 0 };
-            obj.setCoords();
-            const coords = typeof obj.getCoords === 'function' ? obj.getCoords() : null;
+        _getObjectTopLeftPoint(fabricObject) {
+            if (!fabricObject) return { x: 0, y: 0 };
+            fabricObject.setCoords();
+            const coords = typeof fabricObject.getCoords === 'function' ? fabricObject.getCoords() : null;
             if (coords && coords.length) return coords[0];
-            const br = obj.getBoundingRect(true, true);
-            return { x: br.left, y: br.top };
+            const boundingRect = fabricObject.getBoundingRect(true, true);
+            return { x: boundingRect.left, y: boundingRect.top };
         }
 
         /**
          * Sets the object's origin at the specified origin point, keeping a reference point fixed in position.
          * 
-         * @param {Object} obj - The object to modify. Should support set, setPositionByOrigin, and setCoords.
+         * @param {Object} fabricObject - The object to modify. Should support set, setPositionByOrigin, and setCoords.
          * @param {string} originX - The new originX ("left", "center", "right", etc.).
          * @param {string} originY - The new originY ("top", "center", "bottom", etc.).
          * @param {{x: number, y: number}} refPoint - The point to keep fixed while setting the new origins.
          * @private
          */
-        _setObjectOriginKeepingPosition(obj, originX, originY, refPoint) {
-            if (!obj || !refPoint || !obj.setPositionByOrigin) return;
-            obj.set({ originX, originY });
-            obj.setPositionByOrigin(refPoint, originX, originY);
-            obj.setCoords();
+        _setObjectOriginKeepingPosition(fabricObject, originX, originY, refPoint) {
+            if (!fabricObject || !refPoint || !fabricObject.setPositionByOrigin) return;
+            fabricObject.set({ originX, originY });
+            fabricObject.setPositionByOrigin(refPoint, originX, originY);
+            fabricObject.setCoords();
         }
 
         /**
          * Moves the object so its bounding box aligns with the canvas's top-left corner (0, 0).
          * 
-         * @param {Object} obj - The object to align.
+         * @param {Object} fabricObject - The object to align.
          * @private
          */
-        _alignObjectBoundingBoxToCanvasTopLeft(obj) {
-            if (!obj) return;
-            obj.setCoords();
-            const br = obj.getBoundingRect(true, true);
-            const dx = br.left;
-            const dy = br.top;
-            obj.set({ left: (obj.left || 0) - dx, top: (obj.top || 0) - dy });
-            obj.setCoords();
+        _alignObjectBoundingBoxToCanvasTopLeft(fabricObject) {
+            if (!fabricObject) return;
+            fabricObject.setCoords();
+            const boundingRect = fabricObject.getBoundingRect(true, true);
+            const deltaX = boundingRect.left;
+            const deltaY = boundingRect.top;
+            fabricObject.set({ left: (fabricObject.left || 0) - deltaX, top: (fabricObject.top || 0) - deltaY });
+            fabricObject.setCoords();
             this.canvas.renderAll();
         }
 
@@ -684,22 +1342,64 @@ function ensureFabric() {
         _updateCanvasSizeToImageBounds() {
             if (!this.originalImage) return;
             this.originalImage.setCoords();
-            const br = this.originalImage.getBoundingRect(true, true);
+            const imageBounds = this.originalImage.getBoundingRect(true, true);
 
-            // Container integer sizes
-            const containerW = this.containerEl ? Math.ceil(this.containerEl.clientWidth || 0) : 0;
-            const containerH = this.containerEl ? Math.ceil(this.containerEl.clientHeight || 0) : 0;
+            const size = this._getScrollableCanvasSize(imageBounds.width, imageBounds.height);
+            this._setCanvasSizeInt(size.width, size.height);
+        }
 
-            // If image smaller or equal than container in BOTH dims => keep canvas equal to container
-            if (containerW > 0 && containerH > 0 && br.width <= containerW && br.height <= containerH) {
-                this._setCanvasSizeInt(containerW, containerH);
-                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 {
+                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);
+                if (newWidth !== this.canvas.getWidth() || newHeight !== this.canvas.getHeight()) {
+                    this._setCanvasSizeInt(newWidth, newHeight);
+                }
+            } catch (error) {
+                this._reportWarning('expandCanvasToFitObjects: failed to expand canvas', error);
             }
+        }
 
-            // Else canvas follows image bounding box but not smaller than container dims individually
-            const newW = Math.max(containerW || 0, Math.floor(br.width));
-            const newH = Math.max(containerH || 0, Math.floor(br.height));
-            this._setCanvasSizeInt(newW, newH);
+        /**
+         * 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);
         }
 
         /** 
@@ -709,8 +1409,8 @@ function ensureFabric() {
          * @returns {Promise<void>} Promise that resolves once the scaling animation finishes.
          * @public
          */
-        scaleImage(factor) {
-            return this.animQueue.add(() => this._scaleImageImpl(factor));
+        scaleImage(factor, options = {}) {
+            return this.animationQueue.add(() => this._scaleImageImpl(factor, options));
         }
 
         /** 
@@ -720,50 +1420,53 @@ function ensureFabric() {
          * @returns {Promise<void>} Promise that resolves once the scaling animation finishes.
          * @private
          */
-        _scaleImageImpl(factor) {
+        _scaleImageImpl(factor, options = {}) {
             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;
             this.isAnimating = true;
             this._updateUI();
 
-            const targetAbs = this.baseImageScale * factor;
+            const targetScale = this.baseImageScale * factor;
 
             // Scale around current top-left (recompute)
             const topLeft = this._getObjectTopLeftPoint(this.originalImage);
             this._setObjectOriginKeepingPosition(this.originalImage, 'left', 'top', topLeft);
 
-            const p1 = new Promise((res) => {
-                this.originalImage.animate('scaleX', targetAbs, {
+            const scaleXAnimation = new Promise((resolve) => {
+                this.originalImage.animate('scaleX', targetScale, {
                     duration: this.options.animationDuration,
                     onChange: this.canvas.renderAll.bind(this.canvas),
-                    onComplete: res
+                    onComplete: resolve
                 });
             });
-            const p2 = new Promise((res) => {
-                this.originalImage.animate('scaleY', targetAbs, {
+            const scaleYAnimation = new Promise((resolve) => {
+                this.originalImage.animate('scaleY', targetScale, {
                     duration: this.options.animationDuration,
                     onChange: this.canvas.renderAll.bind(this.canvas),
-                    onComplete: res
+                    onComplete: resolve
                 });
             });
 
-            return Promise.all([p1, p2]).then(() => {
-                this.originalImage.set({ scaleX: targetAbs, scaleY: targetAbs });
+            return Promise.all([scaleXAnimation, scaleYAnimation]).then(() => {
+                this.originalImage.set({ scaleX: targetScale, scaleY: targetScale });
                 this.originalImage.setCoords();
 
-                if (this.options.expandCanvasToImage) this._updateCanvasSizeToImageBounds();
+                if (this._shouldResizeCanvasToContentBounds()) {
+                    this._updateCanvasSizeToImageBounds();
+                }
 
                 this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
 
                 // Sync mask labels
-                this.canvas.getObjects().forEach(o => { if (o.maskId) this._syncMaskLabel(o); });
+                this.canvas.getObjects().forEach(object => { if (object.maskId) this._syncMaskLabel(object); });
 
                 this.isAnimating = false;
                 this._updateInputs();
                 this._updateUI();
-                this.saveState();
+                if (saveHistory) this.saveState();
             }).catch(() => {
                 this.isAnimating = false;
                 this._updateUI();
@@ -777,8 +1480,8 @@ function ensureFabric() {
          * @returns {Promise<void>} Promise that resolves once the rotation animation finishes.
          * @public
          */
-        rotateImage(deg) {
-            return this.animQueue.add(() => this._rotateImageImpl(deg));
+        rotateImage(degrees, options = {}) {
+            return this.animationQueue.add(() => this._rotateImageImpl(degrees, options));
         }
 
         /** 
@@ -788,10 +1491,11 @@ function ensureFabric() {
          * @returns {Promise<void>} Promise that resolves once the rotation animation finishes.
          * @private
          */
-        _rotateImageImpl(degrees) {
+        _rotateImageImpl(degrees, options = {}) {
             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;
             this._updateUI();
@@ -799,19 +1503,21 @@ function ensureFabric() {
             const center = this.originalImage.getCenterPoint();
             this._setObjectOriginKeepingPosition(this.originalImage, 'center', 'center', center);
 
-            const p = new Promise((res) => {
+            const rotationAnimation = new Promise((resolve) => {
                 this.originalImage.animate('angle', degrees, {
                     duration: this.options.animationDuration,
                     onChange: this.canvas.renderAll.bind(this.canvas),
-                    onComplete: res
+                    onComplete: resolve
                 });
             });
 
-            return p.then(() => {
+            return rotationAnimation.then(() => {
                 this.originalImage.set('angle', degrees);
                 this.originalImage.setCoords();
 
-                if (this.options.expandCanvasToImage) this._updateCanvasSizeToImageBounds();
+                if (this._shouldResizeCanvasToContentBounds()) {
+                    this._updateCanvasSizeToImageBounds();
+                }
 
                 this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
 
@@ -819,12 +1525,12 @@ function ensureFabric() {
                 this._setObjectOriginKeepingPosition(this.originalImage, 'left', 'top', newTopLeft);
 
                 // Sync mask labels
-                this.canvas.getObjects().forEach(o => { if (o.maskId) this._syncMaskLabel(o); });
+                this.canvas.getObjects().forEach(object => { if (object.maskId) this._syncMaskLabel(object); });
 
                 this.isAnimating = false;
                 this._updateInputs();
                 this._updateUI();
-                this.saveState();
+                if (saveHistory) this.saveState();
             }).catch(() => {
                 this.isAnimating = false;
                 this._updateUI();
@@ -832,150 +1538,294 @@ function ensureFabric() {
         }
 
         /**
-         * Resets the image: scales to 1 and rotates to 0 degrees.
-         * @returns {Promise<void>} Promise that resolves when reset is complete.
+         * Resets the image transform: scales to 1 and rotates to 0 degrees.
+         *
+         * @returns {Promise<void>} Resolves when the reset history transition has been recorded.
+         * @public
          */
-        reset() {
+        resetImageTransform() {
             if (!this.originalImage) return Promise.resolve();
 
-            return this.scaleImage(1)
-                .then(() => this.rotateImage(0))
-                .then(() => {
-                    this.saveState();
-                })
-                .catch(err => {
-                    this._reportError('reset() failed', err);
-                });
+            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(error => {
+                this._reportError('resetImageTransform() failed', error);
+            });
         }
 
         /**
-         * Restores a canvas state that was previously stored by saveState().
-         * @param {string} jsonString - the JSON string returned by fabric.toJSON().
+         * 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.
          */
-        loadFromState(jsonString) {
-            if (!jsonString || !this.canvas) return;
-
-            try {
-                const json = (typeof jsonString === 'string')
-                    ? JSON.parse(jsonString)
-                    : jsonString;
+        reset() {
+            return this.resetImageTransform();
+        }
 
-                this.canvas.loadFromJSON(json, () => {
-                    try {
-                        this._hideAllMaskLabels();
-                        const objs = this.canvas.getObjects();
-                        this.originalImage = objs.find(o => o.type === 'image' && !o.maskId) || null;
+        /**
+         * 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(serializedState) {
+            if (!serializedState || !this.canvas) return Promise.resolve();
 
-                        if (this.originalImage) {
-                            this.originalImage.set({ originX: 'left', originY: 'top', selectable: false, evented: false, hasControls: false, hoverCursor: 'default' });
-                            this.canvas.sendToBack(this.originalImage);
-                        }
+            return new Promise((resolve) => {
+                try {
+                    const state = (typeof serializedState === 'string')
+                        ? JSON.parse(serializedState)
+                        : serializedState;
+                    const editorMetadata = state && state.imageEditorMetadata ? state.imageEditorMetadata : null;
 
-                        const masks = objs.filter(o => o.maskId);
-                        this.maskCounter = masks.reduce((max, m) =>
-                            Math.max(max, m.maskId), 0);
-                        this._lastMask = masks.length ? masks[masks.length - 1] : null;
-                        if (!this._lastMask) {
-                            this._lastMaskInitialLeft = null;
-                            this._lastMaskInitialTop = null;
-                            this._lastMaskInitialWidth = null;
+                    this.canvas.loadFromJSON(state, () => {
+                        try {
+                            this._hideAllMaskLabels();
+                            const canvasObjects = this.canvas.getObjects();
+                            this.originalImage = canvasObjects.find(object => object.type === 'image' && !object.maskId) || null;
+
+                            if (this.originalImage) {
+                                this.originalImage.set({ originX: 'left', originY: 'top', selectable: false, evented: false, hasControls: false, hoverCursor: 'default' });
+                                this.canvas.sendToBack(this.originalImage);
+                                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;
+                            }
+
+                            const masks = canvasObjects.filter(object => object.maskId);
+                            masks.forEach(mask => {
+                                this._restoreMaskControls(mask);
+                                this._rebindMaskEvents(mask);
+                                mask.set(this._getMaskNormalStyle(mask));
+                            });
+                            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;
+                                this._lastMaskInitialTop = null;
+                                this._lastMaskInitialWidth = null;
+                            }
+                            this.isImageLoadedToCanvas = !!this.originalImage;
+
+                            this.canvas.renderAll();
+                            this._updateInputs();
+                            this._updateMaskList();
+                            this._updatePlaceholderStatus();
+                            this._lastSnapshot = this._serializeCanvasState();
+                            this._updateUI();
+                        } catch (callbackError) {
+                            this._reportError('loadFromState() failed', callbackError);
+                        } finally {
+                            resolve();
                         }
-                        this.isImageLoadedToCanvas = !!this.originalImage;
-
-                        this.canvas.renderAll();
-                        this._updateMaskList();
-                        this._updatePlaceholderStatus();
-                        this._updateUI();
-                    } catch (callbackError) {
-                        this._reportError('loadFromState() failed', callbackError);
-                    }
-                });
+                    });
 
-            } catch (e) {
-                this._reportError('loadFromState() failed', e);
-            }
+                } catch (error) {
+                    this._reportError('loadFromState() failed', error);
+                    resolve();
+                }
+            });
         }
 
         /**
-         * 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;
-            const activeObj = this.canvas.getActiveObject();
-            this._hideAllMaskLabels();
+            const activeObject = this.canvas.getActiveObject();
 
             try {
-                // request JSON including the custom flag 'isCropRect' so we can filter it out
-                const jsonObj = this.canvas.toJSON(['maskId', 'maskName', 'isCropRect']);
-                if (Array.isArray(jsonObj.objects)) {
-                    // filter out crop-rect objects before stringifying
-                    jsonObj.objects = jsonObj.objects.filter(o => !o.isCropRect);
-                }
-                const after = JSON.stringify(jsonObj);
+                const after = this._serializeCanvasState();
                 const before = this._lastSnapshot || after;
+                if (after === before) return;
                 let executedOnce = false;
 
-                const cmd = new Command(
+                const command = new Command(
                     () => {
                         if (executedOnce) {
-                            this.loadFromState(after);
+                            return this.loadFromState(after);
                         }
                         executedOnce = true;
+                        return undefined;
                     },
-                    () => {
-                        this.loadFromState(before);
-                    }
+                    () => this.loadFromState(before)
                 );
 
-                this.historyManager.execute(cmd);
+                this.historyManager.execute(command);
                 this._lastSnapshot = after;
-                if (activeObj && activeObj.maskId) {
-                    this._showLabelForMask(activeObj);
+            } catch (error) {
+                this._reportWarning('saveState: failed to save canvas snapshot', error);
+            } finally {
+                if (activeObject && activeObject.maskId && !activeObject.__label && this.canvas.getObjects().includes(activeObject)) {
+                    this._handleSelectionChanged([activeObject]);
                 }
                 this._updateUI();
-            } catch (err) {
-                this._reportWarning('saveState: failed to save canvas snapshot', err);
             }
         }
 
+        /**
+         * 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);
+
+            const command = new Command(
+                () => this.loadFromState(after),
+                () => this.loadFromState(before)
+            );
+            this.historyManager.push(command);
+            this._lastSnapshot = after;
+            this._updateUI();
+        }
+
         /**
          * Undo the last state change, if possible.
+         *
+         * @returns {Promise<void>} Resolves after the history manager finishes the queued undo.
+         * @public
          */
         undo() {
-            this.historyManager.undo();
+            return this.historyManager.undo()
+                .then(() => { this._updateUI(); })
+                .catch(error => { this._reportError('undo failed', error); });
         }
 
         /**
          * Redo the next state change, if possible.
+         *
+         * @returns {Promise<void>} Resolves after the history manager finishes the queued redo.
+         * @public
          */
         redo() {
-            this.historyManager.redo();
+            return this.historyManager.redo()
+                .then(() => { this._updateUI(); })
+                .catch(error => { this._reportError('redo failed', error); });
         }
 
-        /** 
-         * Adds a rectangular mask 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] - (cfg) => new FabricObj
-         * @returns {fabric.Rect|null} The created mask object, or null if canvas is not available.
+        _rebindMaskEvents(mask) {
+            if (!mask) return;
+            if (mask.__imageEditorMaskHandlers) {
+                try {
+                    mask.off('mouseover', mask.__imageEditorMaskHandlers.mouseover);
+                    mask.off('mouseout', mask.__imageEditorMaskHandlers.mouseout);
+                } catch (error) { void error; }
+            }
+
+            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 (!Number.isFinite(Number(mask.originalStrokeWidth))) {
+                metadata.originalStrokeWidth = Number.isFinite(Number(mask.strokeWidth)) ? Number(mask.strokeWidth) : 1;
+            }
+            if (Object.keys(metadata).length) mask.set(metadata);
+
+            const normalStyle = {
+                stroke: mask.originalStroke || '#ccc',
+                strokeWidth: mask.originalStrokeWidth,
+                opacity: mask.originalAlpha
+            };
+            const hoverStyle = {
+                stroke: '#ff5500',
+                strokeWidth: 2,
+                opacity: Math.min(mask.originalAlpha + 0.2, 1)
+            };
+
+            const mouseover = () => {
+                mask.set(hoverStyle);
+                if (mask.canvas) mask.canvas.requestRenderAll();
+            };
+            const mouseout = () => {
+                mask.set(normalStyle);
+                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.
+         *
+         * 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
          */
-        addMask(config = {}) {
+        createMask(config = {}) {
             if (!this.canvas) return null;
             const shapeType = config.shape || 'rect';
-            // Default config
-            const cfg = {
+            // Normalize mask defaults before applying caller-provided overrides.
+            const maskConfig = {
                 shape: shapeType,
                 width: this.options.defaultMaskWidth,
                 height: this.options.defaultMaskHeight,
@@ -994,84 +1844,77 @@ function ensureFabric() {
             let left = firstOffset;
             let top = firstOffset;
 
-            const resolveValue = (val, fallback) => {
-                if (typeof val === 'function')
-                    return val(this.canvas, this.options); // This context is this of addMask
-                if (typeof val === 'string' && val.endsWith('%')) {
-                    const percent = parseFloat(val) / 100;
+            const resolveValue = (value, fallback) => {
+                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);
                 }
-                return val != null ? val : fallback;
+                return value != null ? value : fallback;
             }
 
-            if (cfg.left === undefined && this._lastMask) {
-                const prev = this._lastMask;
-                let prevRight = prev.left;
+            if (maskConfig.left === undefined && this._lastMask) {
+                const previousMask = this._lastMask;
+                let previousMaskRight = previousMask.left;
 
-                if (prev.getScaledWidth) {
-                    prevRight += prev.getScaledWidth();
-                } else if (prev.width) {
-                    prevRight += prev.width * (prev.scaleX ?? 1);
+                if (previousMask.getScaledWidth) {
+                    previousMaskRight += previousMask.getScaledWidth();
+                } else if (previousMask.width) {
+                    previousMaskRight += previousMask.width * (previousMask.scaleX ?? 1);
                 }
-                left = Math.round(prevRight + cfg.gap);
-                top = prev.top ?? firstOffset;
+                left = Math.round(previousMaskRight + maskConfig.gap);
+                top = previousMask.top ?? firstOffset;
             } else {
-                left = resolveValue(cfg.left, firstOffset);
-                top = resolveValue(cfg.top, firstOffset);
+                left = resolveValue(maskConfig.left, firstOffset);
+                top = resolveValue(maskConfig.top, firstOffset);
             }
 
-            cfg.width = resolveValue(cfg.width, this.options.defaultMaskWidth);
-            cfg.height = resolveValue(cfg.height, this.options.defaultMaskHeight);
-
-            // If expandCanvasToImage mode, ensure canvas large enough to hold mask initial placement
-            if (this.options.expandCanvasToImage && shapeType === 'rect') {
-                const requiredW = Math.ceil(left + cfg.width + 10);
-                const requiredH = Math.ceil(top + cfg.height + 10);
-                const minW = this.containerEl ? Math.floor(this.containerEl.clientWidth || 0) : 0;
-                const minH = this.containerEl ? Math.floor(this.containerEl.clientHeight || 0) : 0;
-                const newW = Math.max(this.canvas.getWidth(), minW, requiredW);
-                const newH = Math.max(this.canvas.getHeight(), minH, requiredH);
-                this._setCanvasSizeInt(newW, newH);
-            }
+            maskConfig.width = resolveValue(maskConfig.width, this.options.defaultMaskWidth);
+            maskConfig.height = resolveValue(maskConfig.height, this.options.defaultMaskHeight);
+            maskConfig.left = left;
+            maskConfig.top = top;
 
             let mask;
-            if (typeof cfg.fabricGenerator === 'function') {
-                mask = cfg.fabricGenerator(cfg, this.canvas, this.options);
+            if (typeof maskConfig.fabricGenerator === 'function') {
+                mask = maskConfig.fabricGenerator(maskConfig, this.canvas, this.options);
             } else {
                 switch (shapeType) {
                     case 'circle':
                         mask = new fabric.Circle({
                             left, top,
-                            radius: resolveValue(cfg.radius, Math.min(cfg.width, cfg.height) / 2),
-                            fill: cfg.color,
-                            opacity: cfg.alpha,
-                            angle: cfg.angle,
-                            ...cfg.styles
+                            radius: resolveValue(maskConfig.radius, Math.min(maskConfig.width, maskConfig.height) / 2),
+                            fill: maskConfig.color,
+                            opacity: maskConfig.alpha,
+                            angle: maskConfig.angle,
+                            ...maskConfig.styles
                         });
                         break;
                     case 'ellipse':
                         mask = new fabric.Ellipse({
                             left, top,
-                            rx: resolveValue(cfg.rx, cfg.width / 2),
-                            ry: resolveValue(cfg.ry, cfg.height / 2),
-                            fill: cfg.color,
-                            opacity: cfg.alpha,
-                            angle: cfg.angle,
-                            ...cfg.styles
+                            rx: resolveValue(maskConfig.rx, maskConfig.width / 2),
+                            ry: resolveValue(maskConfig.ry, maskConfig.height / 2),
+                            fill: maskConfig.color,
+                            opacity: maskConfig.alpha,
+                            angle: maskConfig.angle,
+                            ...maskConfig.styles
                         });
                         break;
                     case 'polygon': {
-                        let polyPoints = cfg.points || [];
-                        if (Array.isArray(polyPoints) && polyPoints.length && typeof polyPoints[0] === 'object') {
-                            // Ensure numeric {x,y} objects for fabric.Polygon
-                            polyPoints = polyPoints.map(pt => ({ x: Number(pt.x), y: Number(pt.y) }));
+                        let polygonPoints = maskConfig.points || [];
+                        if (Array.isArray(polygonPoints) && polygonPoints.length) {
+                            // Ensure numeric {x,y} objects for fabric.Polygon.
+                            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(polyPoints, {
+                        mask = new fabric.Polygon(polygonPoints, {
                             left, top,
-                            fill: cfg.color,
-                            opacity: cfg.alpha,
-                            angle: cfg.angle,
-                            ...cfg.styles
+                            fill: maskConfig.color,
+                            opacity: maskConfig.alpha,
+                            angle: maskConfig.angle,
+                            ...maskConfig.styles
                         });
                         break;
                     }
@@ -1079,85 +1922,103 @@ function ensureFabric() {
                     default:
                         mask = new fabric.Rect({
                             left, top,
-                            width: resolveValue(cfg.width, this.options.defaultMaskWidth),
-                            height: resolveValue(cfg.height, this.options.defaultMaskHeight),
-                            fill: cfg.color,
-                            opacity: cfg.alpha,
-                            angle: cfg.angle,
-                            rx: cfg.rx, // Rounded Corners
-                            ry: cfg.ry,
-                            ...cfg.styles
+                            width: resolveValue(maskConfig.width, this.options.defaultMaskWidth),
+                            height: resolveValue(maskConfig.height, this.options.defaultMaskHeight),
+                            fill: maskConfig.color,
+                            opacity: maskConfig.alpha,
+                            angle: maskConfig.angle,
+                            rx: maskConfig.rx,
+                            ry: maskConfig.ry,
+                            ...maskConfig.styles
                         });
                 }
             }
 
-            mask.selectable = cfg.selectable !== false;
-            mask.hasControls = ('hasControls' in cfg) ? cfg.hasControls : true;
-            mask.lockRotation = !this.options.maskRotatable;
-            mask.borderColor = cfg.borderColor || 'red';
-            mask.cornerColor = cfg.cornerColor || 'black';
-            mask.cornerSize = cfg.cornerSize || 8;
-            mask.transparentCorners = ('transparentCorners' in cfg) ? cfg.transparentCorners : false;
-            mask.stroke = (cfg.styles && cfg.styles.stroke) || '#ccc';
-            mask.strokeWidth = (cfg.styles && cfg.styles.strokeWidth) || 1;
-            mask.strokeUniform = ('strokeUniform' in cfg) ? cfg.strokeUniform : true;
-            if (cfg.styles && cfg.styles.strokeDashArray) mask.strokeDashArray = cfg.styles.strokeDashArray;
-
-            mask.originalAlpha = cfg.alpha;
-            const normalStyle = { stroke: mask.stroke, strokeWidth: mask.strokeWidth, opacity: mask.originalAlpha };
-            const hoverStyle = { stroke: '#ff5500', strokeWidth: 2, opacity: Math.min(mask.originalAlpha + 0.2, 1) };
-
-            mask.on('mouseover', () => {
-                mask.set(hoverStyle);
-                mask.canvas.requestRenderAll();
-            });
-
-            mask.on('mouseout', () => {
-                mask.set(normalStyle);
-                mask.canvas.requestRenderAll();
+            const styles = maskConfig.styles || {};
+            const hasStyle = property => Object.prototype.hasOwnProperty.call(styles, property);
+            const maskSettings = {
+                selectable: maskConfig.selectable !== false,
+                hasControls: ('hasControls' in maskConfig) ? maskConfig.hasControls : true,
+                lockRotation: !this.options.maskRotatable,
+                borderColor: ('borderColor' in maskConfig) ? maskConfig.borderColor : 'red',
+                cornerColor: ('cornerColor' in maskConfig) ? maskConfig.cornerColor : 'black',
+                cornerSize: ('cornerSize' in maskConfig) ? maskConfig.cornerSize : 8,
+                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;
+            mask.set(maskSettings);
+            mask.setCoords();
+
+            mask.set({
+                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
             });
+            this._rebindMaskEvents(mask);
+            this._expandCanvasToFitObject(mask);
 
-            // Remember initial for next one
+            // Store placement values so the next mask can be positioned beside this one.
             this._lastMaskInitialLeft = left;
             this._lastMaskInitialTop = top;
-            this._lastMaskInitialWidth = resolveValue(cfg.width, this.options.defaultMaskWidth);
+            this._lastMaskInitialWidth = resolveValue(maskConfig.width, this.options.defaultMaskWidth);
 
-            mask.maskId = ++this.maskCounter;
-            mask.maskName = `${this.options.maskName}${mask.maskId}`;
+            const maskId = ++this.maskCounter;
+            mask.set({
+                maskId,
+                maskName: `${this.options.maskName}${maskId}`
+            });
             this._lastMask = mask;
 
             this.canvas.add(mask);
             this.canvas.bringToFront(mask);
-            if (cfg.selectable) this.canvas.setActiveObject(mask);
-            this._onSelectionChanged([mask]);
+            if (maskConfig.selectable) this.canvas.setActiveObject(mask);
+            this._handleSelectionChanged([mask]);
             this._updateMaskList();
             this._updateUI();
             this.canvas.renderAll();
             this.saveState();
 
-            if (typeof cfg.onCreate === 'function') cfg.onCreate(mask, this.canvas);
+            if (typeof maskConfig.onCreate === 'function') maskConfig.onCreate(mask, this.canvas);
             return mask;
         }
 
+        /**
+         * 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);
+        }
+
         /**
          * Removes the currently selected mask from the canvas, if any.
          * The associated label is also removed. UI and mask list are updated.
          */
         removeSelectedMask() {
-            const active = this.canvas.getActiveObject();
-            if (!active || !active.maskId) return;
-            this._removeLabelForMask(active);
-            this.canvas.remove(active);
-            if (this._lastMask === active) {
-                const masks = this.canvas.getObjects().filter(o => o.maskId);
-                this._lastMask = masks.length ? masks[masks.length - 1] : null;
-                if (!this._lastMask) {
-                    this._lastMaskInitialLeft = null;
-                    this._lastMaskInitialTop = null;
-                    this._lastMaskInitialWidth = null;
-                }
-            }
+            const activeObject = this.canvas.getActiveObject();
+            const selectedMasks = this._getModifiedMasks(activeObject);
+            if (!selectedMasks.length) return;
+
             this.canvas.discardActiveObject();
+            selectedMasks.forEach(mask => {
+                this._removeLabelForMask(mask);
+                this.canvas.remove(mask);
+            });
+
+            const masks = this.canvas.getObjects().filter(object => object.maskId);
+            this._lastMask = masks.length ? masks[masks.length - 1] : null;
+            if (!this._lastMask) {
+                this._lastMaskInitialLeft = null;
+                this._lastMaskInitialTop = null;
+                this._lastMaskInitialWidth = null;
+            }
             this._updateMaskList();
             this._updateUI();
             this.canvas.renderAll();
@@ -1168,10 +2029,11 @@ function ensureFabric() {
          * Removes all masks from the canvas, including their labels.
          * UI and internal mask placement memory are reset.
          */
-        removeAllMasks() {
-            const masks = this.canvas.getObjects().filter(o => o.maskId);
-            masks.forEach(m => this._removeLabelForMask(m));
-            masks.forEach(m => this.canvas.remove(m));
+        removeAllMasks(options = {}) {
+            const saveHistory = options.saveHistory !== false;
+            const masks = this.canvas.getObjects().filter(object => object.maskId);
+            masks.forEach(mask => this._removeLabelForMask(mask));
+            masks.forEach(mask => this.canvas.remove(mask));
             this.canvas.discardActiveObject();
             this._lastMask = null;
             this._lastMaskInitialLeft = null;
@@ -1180,7 +2042,7 @@ function ensureFabric() {
             this._updateMaskList();
             this._updateUI();
             this.canvas.renderAll();
-            this.saveState();
+            if (saveHistory) this.saveState();
         }
 
         /**
@@ -1193,15 +2055,33 @@ function ensureFabric() {
             if (!mask || !this.canvas) return;
             if (mask.__label) {
                 try {
-                    const objs = this.canvas.getObjects();
-                    if (objs.includes(mask.__label)) {
+                    const canvasObjects = this.canvas.getObjects();
+                    if (canvasObjects.includes(mask.__label)) {
                         this.canvas.remove(mask.__label);
                     }
-                } catch (e) { void e; }
-                try { delete mask.__label; } catch (e) { void e; }
+                } 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.
@@ -1212,12 +2092,12 @@ function ensureFabric() {
         _createLabelForMask(mask) {
             if (!mask || !this.options.maskLabelOnSelect) return;
             this._removeLabelForMask(mask);
-            let textObj = null;
+            let textObject = null;
             if (this.options.label && typeof this.options.label.create === 'function') {
-                textObj = this.options.label.create(mask, fabric);
+                textObject = this.options.label.create(mask, fabric);
             }
-            if (!textObj) {
-                let txt = mask.maskName; // Default
+            if (!textObject) {
+                let labelText = mask.maskName;
                 let textOptions = {
                     left: 0,
                     top: 0,
@@ -1232,20 +2112,20 @@ function ensureFabric() {
                 };
                 if (this.options.label) {
                     if (typeof this.options.label.getText === 'function') {
-                        txt = this.options.label.getText(mask, this.maskCounter);
+                        labelText = this.options.label.getText(mask, this._getMaskCreationIndex(mask));
                     }
                     // Merge external styles
                     if (this.options.label.textOptions) {
                         Object.assign(textOptions, this.options.label.textOptions);
                     }
                 }
-                textObj = new fabric.Text(txt, textOptions);
+                textObject = new fabric.Text(labelText, textOptions);
             }
 
-            textObj.maskLabel = true;
-            mask.__label = textObj;
-            this.canvas.add(textObj);
-            this.canvas.bringToFront(textObj);
+            textObject.maskLabel = true;
+            mask.__label = textObject;
+            this.canvas.add(textObject);
+            this.canvas.bringToFront(textObject);
             this._syncMaskLabel(mask);
         }
 
@@ -1256,14 +2136,18 @@ function ensureFabric() {
          */
         _hideAllMaskLabels() {
             if (!this.canvas) return;
-            const objs = this.canvas.getObjects();
-            const labels = objs.filter(o => o.maskLabel);
-            labels.forEach(l => {
+            const canvasObjects = this.canvas.getObjects();
+            const labels = canvasObjects.filter(object => object.maskLabel);
+            labels.forEach(label => {
                 try {
-                    if (objs.includes(l)) this.canvas.remove(l);
-                } catch (e) { void e; }
+                    if (canvasObjects.includes(label)) this.canvas.remove(label);
+                } catch (error) { void error; }
+            });
+            canvasObjects.forEach(object => {
+                if (object.maskId && object.__label) {
+                    try { delete object.__label; } catch (error) { void error; }
+                }
             });
-            objs.forEach(o => { if (o.maskId && o.__label) { try { delete o.__label; } catch (e) { void e; } } });
         }
 
         /**
@@ -1303,7 +2187,11 @@ function ensureFabric() {
                 visible: true
             });
             mask.__label.setCoords();
-            this.canvas.renderAll();
+            if (typeof this.canvas.requestRenderAll === 'function') {
+                this.canvas.requestRenderAll();
+            } else {
+                this.canvas.renderAll();
+            }
         }
 
         /**
@@ -1316,7 +2204,7 @@ function ensureFabric() {
             if (!mask) return;
             if (!this.options.maskLabelOnSelect) return;
             if (!mask.__label) this._createLabelForMask(mask);
-            mask.__label.visible = true;
+            mask.__label.set({ visible: true });
             this._syncMaskLabel(mask);
         }
 
@@ -1327,18 +2215,22 @@ function ensureFabric() {
          * @param {Array<Object>} selected - The currently selected objects (e.g. [mask] or []).
          * @private
          */
-        _onSelectionChanged(selected) {
-            const selectedMask = (selected || []).find(o => o.maskId);
-            const masks = this.canvas.getObjects().filter(o => o.maskId);
-            masks.forEach(m => {
-                if (m !== selectedMask) {
-                    if (m.__label) {
-                        try { this.canvas.remove(m.__label); } catch (e) { void e; }
-                        delete m.__label;
+        _handleSelectionChanged(selected) {
+            const selectedMask = (selected || []).find(object => object.maskId);
+            const masks = this.canvas.getObjects().filter(object => object.maskId);
+            masks.forEach(mask => {
+                if (mask !== selectedMask) {
+                    if (mask.__label) {
+                        try { this.canvas.remove(mask.__label); } catch (error) { void error; }
+                        delete mask.__label;
                     }
-                    m.set({ stroke: '#ccc', strokeWidth: 1 });
+                    const originalStrokeWidth = Number(mask.originalStrokeWidth);
+                    mask.set({
+                        stroke: mask.originalStroke || '#ccc',
+                        strokeWidth: Number.isFinite(originalStrokeWidth) ? originalStrokeWidth : 1
+                    });
                 } else {
-                    m.set({ stroke: '#ff0000', strokeWidth: 1 });
+                    mask.set({ stroke: '#ff0000', strokeWidth: 1 });
                 }
             });
 
@@ -1355,16 +2247,16 @@ function ensureFabric() {
          * @private
          */
         _updateMaskList() {
-            const listEl = document.getElementById(this.elements.maskList);
-            if (!listEl) return;
-            listEl.innerHTML = '';
-            const masks = this.canvas.getObjects().filter(o => o.maskId);
+            const maskListElement = document.getElementById(this.elements.maskList);
+            if (!maskListElement) return;
+            maskListElement.innerHTML = '';
+            const masks = this.canvas.getObjects().filter(object => object.maskId);
             masks.forEach(mask => {
-                const li = document.createElement('li');
-                li.className = 'list-group-item mask-item';
-                li.textContent = mask.maskName;
-                li.onclick = () => { this.canvas.setActiveObject(mask); this._onSelectionChanged([mask]); };
-                listEl.appendChild(li);
+                const listItemElement = document.createElement('li');
+                listItemElement.className = 'list-group-item mask-item';
+                listItemElement.textContent = mask.maskName;
+                listItemElement.onclick = () => { this.canvas.setActiveObject(mask); this._handleSelectionChanged([mask]); };
+                maskListElement.appendChild(listItemElement);
             });
         }
 
@@ -1375,168 +2267,178 @@ function ensureFabric() {
          * @private
          */
         _updateMaskListSelection(selectedMask) {
-            const listEl = document.getElementById(this.elements.maskList);
-            if (!listEl) return;
-            const items = listEl.querySelectorAll('.mask-item');
-            items.forEach(item => {
+            const maskListElement = document.getElementById(this.elements.maskList);
+            if (!maskListElement) return;
+            const maskItems = maskListElement.querySelectorAll('.mask-item');
+            maskItems.forEach(item => {
                 const isSelected = !!selectedMask && item.textContent === selectedMask.maskName;
                 item.classList.toggle('active', isSelected);
             });
         }
 
         /**
-         * 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 merge() {
+        async mergeMasks() {
             if (!this.originalImage) return;
-            const masks = this.canvas.getObjects().filter(o => o.maskId);
+            const masks = this.canvas.getObjects().filter(object => object.maskId);
             if (!masks.length) return;
 
             this.canvas.discardActiveObject();
             this.canvas.renderAll();
 
             try {
-                const merged = await this.getImageBase64({ exportImageArea: true, multiplier: this.options.exportMultiplier });
-                this.removeAllMasks();
-                await this.loadImage(merged);
-                this.saveState();
-            } catch (err) {
-                this._reportError('merge error', err);
-                if (this.canvasEl) this.canvasEl.style.visibility = '';
+                const beforeJson = this._serializeCanvasState();
+                const merged = await this.exportImageBase64({ exportImageArea: true, multiplier: this.options.exportMultiplier });
+                this.removeAllMasks({ saveHistory: false });
+                await this.loadImage(merged, { preserveScroll: true });
+                const afterJson = this._serializeCanvasState();
+                this._pushStateTransition(beforeJson, afterJson);
+            } catch (error) {
+                this._reportError('merge error', error);
             }
         }
 
         /**
-         * Triggers a JPEG image download of the current canvas (image plus masks if configured).
+         * 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.
+         *
          * 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;
             const exportImageArea = this.options.exportImageAreaByDefault;
-            this.getImageBase64({ 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 JPEG.
-         * 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} [opts={}] - Export options.
-         * @param {boolean} [opts.exportImageArea] - If true, exports only the image bounding area with masks cropped and blended.
-         * @param {number} [opts.multiplier=1] - Scaling multiplier for output (resolution).
-         * @returns {Promise<string>} Promise resolving to a JPEG image data URL.
+         * @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>} Resolves with an image data URL.
          * @throws {Error} If there is no image loaded.
+         * @public
          */
-        async getImageBase64(opts = {}) {
+        async exportImageBase64(options = {}) {
             if (!this.originalImage) throw new Error('No image loaded');
-            const exportImageArea = typeof opts.exportImageArea === 'boolean' ? opts.exportImageArea : this.options.exportImageAreaByDefault;
-            const multiplier = opts.multiplier || this.options.exportMultiplier || 1;
+            const exportImageArea = typeof options.exportImageArea === 'boolean' ? options.exportImageArea : this.options.exportImageAreaByDefault;
+            const multiplier = options.multiplier || this.options.exportMultiplier || 1;
+            const quality = this._normalizeQuality(options.quality ?? this.options.downsampleQuality);
+            const format = this._normalizeImageFormat(options.fileType || options.format);
 
             if (!exportImageArea) {
-                // Export original image pixels
-                const imgEl = this.originalImage.getElement ? this.originalImage.getElement() : (this.originalImage._element || null);
-                if (!imgEl) return this.canvas.toDataURL({ format: 'jpeg', quality: this.options.downsampleQuality, multiplier });
-                const w = this.originalImage.width;
-                const h = this.originalImage.height;
-                const oc = document.createElement('canvas');
-                oc.width = w;
-                oc.height = h;
-                const ctx = oc.getContext('2d');
-                ctx.drawImage(imgEl, 0, 0, w, h);
-                return oc.toDataURL('image/jpeg', this.options.downsampleQuality);
+                const masks = this.canvas.getObjects().filter(object => object.maskId || object.maskLabel);
+                const maskVisibilityBackups = masks.map(mask => ({ object: mask, visible: mask.visible }));
+
+                try {
+                    masks.forEach(mask => { mask.set({ visible: false }); });
+                    this.canvas.discardActiveObject();
+                    this.canvas.renderAll();
+
+                    this.originalImage.setCoords();
+                    const imageBounds = this.originalImage.getBoundingRect(true, true);
+                    const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+                    return await this._exportCanvasRegionToDataURL({
+                        ...exportRegion,
+                        multiplier,
+                        quality,
+                        format
+                    });
+                } finally {
+                    maskVisibilityBackups.forEach(backup => {
+                        try { backup.object.set({ visible: backup.visible }); } catch (error) { void error; }
+                    });
+                    this.canvas.renderAll();
+                }
             }
 
-            // Export current scaled image area (masks clipped)
-            const masks = this.canvas.getObjects().filter(o => o.maskId);
-            const masksBackup = masks.map(m => ({
-                obj: m,
-                opacity: m.opacity,
-                fill: m.fill,
-                strokeWidth: m.strokeWidth,
-                stroke: m.stroke,
-                selectable: m.selectable,
-                lockRotation: m.lockRotation
+            // Render masks as export shapes without mutating their editable styles.
+            const masks = this.canvas.getObjects().filter(object => object.maskId);
+            const maskStyleBackups = masks.map(mask => ({
+                object: mask,
+                opacity: mask.opacity,
+                fill: mask.fill,
+                strokeWidth: mask.strokeWidth,
+                stroke: mask.stroke,
+                selectable: mask.selectable,
+                lockRotation: mask.lockRotation
             }));
 
             let finalBase64;
             try {
-                // Remove labels, deselect
-                masks.forEach(m => this._removeLabelForMask(m));
+                // Labels are UI overlays and should not be part of the flattened export.
+                masks.forEach(mask => this._removeLabelForMask(mask));
                 this.canvas.discardActiveObject();
                 this.canvas.renderAll();
 
-                // Set masks to opaque black no border
-                masks.forEach(m => {
-                    m.set({ opacity: 1, fill: '#000000', strokeWidth: 0, stroke: null, selectable: false });
-                    m.setCoords();
+                // The export treats masks as opaque shapes with no editable border.
+                masks.forEach(mask => {
+                    mask.set({ opacity: 1, fill: '#000000', strokeWidth: 0, stroke: null, selectable: false });
+                    mask.setCoords();
                 });
                 this.canvas.renderAll();
 
-                // Compute integer bounding box for image
+                // Compute an integer canvas region for the base image.
                 this.originalImage.setCoords();
-                const imgBr = this.originalImage.getBoundingRect(true, true);
-                const sx = Math.max(0, Math.round(imgBr.left));
-                const sy = Math.max(0, Math.round(imgBr.top));
-                const sw = Math.max(1, Math.round(imgBr.width));
-                const sh = Math.max(1, Math.round(imgBr.height));
+                const imageBounds = this.originalImage.getBoundingRect(true, true);
+                const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
 
                 // Crop precisely in offscreen canvas
-                finalBase64 = await new Promise((resolve, reject) => {
-                    try {
-                        const fullDataUrl = this.canvas.toDataURL({
-                            format: 'jpeg',
-                            quality: this.options.downsampleQuality,
-                            multiplier: multiplier
-                        });
-
-                        const img = new Image();
-                        img.onload = () => {
-                            try {
-                                const sxM = Math.round(sx * multiplier);
-                                const syM = Math.round(sy * multiplier);
-                                const swM = Math.round(sw * multiplier);
-                                const shM = Math.round(sh * multiplier);
-
-                                const oc = document.createElement('canvas');
-                                oc.width = swM;
-                                oc.height = shM;
-                                const ctx = oc.getContext('2d');
-
-                                ctx.drawImage(img, sxM, syM, swM, shM, 0, 0, swM, shM);
-                                const out = oc.toDataURL('image/jpeg', this.options.downsampleQuality);
-                                resolve(out);
-                            } catch (e) { reject(e); }
-                        };
-                        img.onerror = reject;
-                        img.src = fullDataUrl;
-                    } catch (e) { reject(e); }
+                finalBase64 = await this._exportCanvasRegionToDataURL({
+                    ...exportRegion,
+                    multiplier,
+                    quality,
+                    format
                 });
             } finally {
-                masksBackup.forEach(b => {
+                maskStyleBackups.forEach(backup => {
                     try {
-                        b.obj.set({
-                            opacity: b.opacity,
-                            fill: b.fill,
-                            strokeWidth: b.strokeWidth,
-                            stroke: b.stroke,
-                            selectable: b.selectable,
-                            lockRotation: b.lockRotation
+                        backup.object.set({
+                            opacity: backup.opacity,
+                            fill: backup.fill,
+                            strokeWidth: backup.strokeWidth,
+                            stroke: backup.stroke,
+                            selectable: backup.selectable,
+                            lockRotation: backup.lockRotation
                         });
-                        b.obj.setCoords();
-                    } catch (e) { void e; }
+                        backup.object.setCoords();
+                    } catch (error) { void error; }
                 });
 
                 this.canvas.renderAll();
@@ -1546,22 +2448,35 @@ function ensureFabric() {
         }
 
         /**
-         * 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).
+         * 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 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} [opts={}] - Export options.
-         * @param {boolean} [opts.mergeMask=true] - If true, export image area with masks merged; if false, export the plain image without masks.
-         * @param {string} [opts.fileType='jpeg'] - Output file type ('jpeg' | 'png' | 'webp'). Defaults to 'jpeg' on invalid input.
-         * @param {number} [opts.quality=0.92] - Image quality for lossy types (0-1, default based on options.downsampleQuality).
-         * @param {number} [opts.multiplier=1] - Output resolution multiplier.
-         * @param {string} [opts.fileName] - Optional file name (only used for download).
+         * @param {Object} [options={}] - Export options.
+         * @param {boolean} [options.mergeMask=true] - If true, export image area with masks merged; if false, export the plain image without masks.
+         * @param {string} [options.fileType='jpeg'] - Output file type ('jpeg' | 'png' | 'webp'). Defaults to 'jpeg' on invalid input.
+         * @param {number} [options.quality=0.92] - Image quality for lossy types (0-1, default based on options.downsampleQuality).
+         * @param {number} [options.multiplier=1] - Output resolution multiplier.
+         * @param {string} [options.fileName] - Optional file name (only used for download).
          * @returns {Promise<File>} Resolves with the exported image as a File object.
          * 
          * @example
          *   const file = await this.exportImageFile({ mergeMask: false, fileType: 'png' });
          */
-        async exportImageFile(opts = {}) {
+        async exportImageFile(options = {}) {
             if (!this.originalImage) throw new Error('No image loaded');
             const {
                 mergeMask = true,
@@ -1569,70 +2484,131 @@ function ensureFabric() {
                 quality = this.options.downsampleQuality ?? 0.92,
                 multiplier = this.options.exportMultiplier ?? 1,
                 fileName = this.options.defaultDownloadFileName ?? 'exported_image.jpg'
-            } = opts;
+            } = options;
 
-            const typeMapping = {
-                'jpeg': 'jpeg',
-                'jpg': 'jpeg',
-                'image/jpeg': 'jpeg',
-                'png': 'png',
-                'image/png': 'png',
-                'webp': 'webp',
-                'image/webp': 'webp'
-            };
-            const safeFileType = typeMapping[String(fileType).toLowerCase()] || 'jpeg';
+            const safeFileType = this._normalizeImageFormat(fileType);
 
-            // Get Base64
-            let base64;
+            // Generate the data URL in the requested export mode.
+            let imageBase64;
             if (mergeMask) {
-                base64 = await this.getImageBase64({
+                imageBase64 = await this.exportImageBase64({
                     exportImageArea: true,
                     multiplier,
+                    quality,
+                    fileType: safeFileType
                 });
             } else {
-                base64 = await this.getImageBase64({
+                imageBase64 = await this.exportImageBase64({
                     exportImageArea: false,
                     multiplier,
+                    quality,
+                    fileType: safeFileType
                 });
             }
 
             // Convert to the required image format
-            let imageDataUrl = base64;
+            let imageDataUrl = imageBase64;
             if (!imageDataUrl.startsWith(`data:image/${safeFileType}`)) {
-                // Redraw if not required format
+                // Redraw the exported data URL when the browser returned a different image format.
                 imageDataUrl = await new Promise((resolve, reject) => {
-                    const img = new window.Image();
-                    img.crossOrigin = "Anonymous";
-                    img.onload = () => {
+                    const imageElement = new window.Image();
+                    imageElement.crossOrigin = "Anonymous";
+                    imageElement.onload = () => {
                         try {
-                            const oc = document.createElement('canvas');
-                            oc.width = img.width;
-                            oc.height = img.height;
-                            const ctx = oc.getContext('2d');
-                            ctx.drawImage(img, 0, 0);
-                            const durl = oc.toDataURL(`image/${safeFileType}`, quality);
-                            resolve(durl);
-                        } catch (e) { reject(e); }
+                            const offscreenCanvas = document.createElement('canvas');
+                            offscreenCanvas.width = imageElement.width;
+                            offscreenCanvas.height = imageElement.height;
+                            const context = offscreenCanvas.getContext('2d');
+                            context.drawImage(imageElement, 0, 0);
+                            const convertedDataUrl = offscreenCanvas.toDataURL(`image/${safeFileType}`, quality);
+                            resolve(convertedDataUrl);
+                        } catch (error) { reject(error); }
                     };
-                    img.onerror = reject;
-                    img.src = base64;
+                    imageElement.onerror = reject;
+                    imageElement.src = imageBase64;
                 });
             }
 
-            // Convert DataURL to Blob and then to File
-            const bstr = atob(imageDataUrl.split(',')[1]);
+            // Convert the final data URL to a File with the requested MIME type.
+            const binaryString = atob(imageDataUrl.split(',')[1]);
             const mime = `image/${safeFileType}`;
-            let n = bstr.length;
-            const u8arr = new Uint8Array(n);
-            while (n--) {
-                u8arr[n] = bstr.charCodeAt(n);
+            let byteIndex = binaryString.length;
+            const bytes = new Uint8Array(byteIndex);
+            while (byteIndex--) {
+                bytes[byteIndex] = binaryString.charCodeAt(byteIndex);
+            }
+            return new File([bytes], fileName, { type: mime });
+        }
+
+        _clearMaskPlacementMemory() {
+            this._lastMask = null;
+            this._lastMaskInitialLeft = null;
+            this._lastMaskInitialTop = null;
+            this._lastMaskInitialWidth = null;
+        }
+
+        async _restoreStateAfterCropFailure(beforeJson, message, error) {
+            this._reportError(message, error);
+
+            if (this._cropRect && this.canvas) this._removeCropRect();
+            this._cropRect = null;
+            this._cropMode = false;
+            if (this.canvas && this._prevSelectionSetting !== undefined) {
+                this.canvas.selection = !!this._prevSelectionSetting;
+            }
+            this._prevSelectionSetting = undefined;
+
+            if (beforeJson) {
+                try {
+                    await this.loadFromState(beforeJson);
+                } catch (restoreError) {
+                    this._reportError('applyCrop: rollback failed', restoreError);
+                }
+            }
+
+            this._updateUI();
+            if (this.canvas) this.canvas.renderAll();
+        }
+
+        _restoreCropObjectState() {
+            if (Array.isArray(this._cropPrevEvented)) {
+                this._cropPrevEvented.forEach(state => {
+                    try {
+                        state.object.set({
+                            evented: state.evented,
+                            selectable: state.selectable,
+                            visible: state.visible
+                        });
+                    } catch (error) { void error; }
+                });
             }
-            const file = new File([u8arr], fileName, { type: mime });
-            return file;
+            this._cropPrevEvented = null;
+        }
+
+        _removeCropRect() {
+            if (!this._cropRect) return;
+            try {
+                if (this._cropHandlers && this._cropHandlers.length) {
+                    this._cropHandlers.forEach(targetHandlers => {
+                        targetHandlers.handlers.forEach(handlerRecord => {
+                            targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
+                        });
+                    });
+                }
+            } 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() {
@@ -1640,24 +2616,30 @@ function ensureFabric() {
             if (!this.isImageLoaded()) return;
             this._cropMode = true;
 
-            // Disable canvas group selection to avoid accidental group selection while cropping
+            // Disable group selection so only the crop rectangle can be manipulated.
             this._prevSelectionSetting = this.canvas.selection;
             this.canvas.selection = false;
 
-            // Make sure no active object
+            // Clear the current selection before activating the crop rectangle.
             this.canvas.discardActiveObject();
 
-            // Create initial crop rect centered on the image bounding box
+            // Create the initial crop rectangle inside the image bounds.
             this.originalImage.setCoords();
-            const imgBr = this.originalImage.getBoundingRect(true, true);
-            // Provide small inset so user can see a margin
+            const imageBounds = this.originalImage.getBoundingRect(true, true);
+            // Use a small inset so the user can see the crop boundary.
             const padding = (this.options.crop && this.options.crop.padding) ? this.options.crop.padding : 10;
-            const left = Math.max(0, Math.floor(imgBr.left + padding));
-            const top = Math.max(0, Math.floor(imgBr.top + padding));
-            const width = Math.min(this.options.crop.minWidth || 50, Math.floor(imgBr.width - padding * 2));
-            const height = Math.min(this.options.crop.minHeight || 50, Math.floor(imgBr.height - padding * 2));
-
-            // Visual style: translucent fill + dashed stroke
+            const left = Math.max(0, Math.floor(imageBounds.left + padding));
+            const top = Math.max(0, Math.floor(imageBounds.top + padding));
+            const maxCropWidth = Math.max(1, Math.floor(imageBounds.width - padding * 2));
+            const maxCropHeight = Math.max(1, Math.floor(imageBounds.height - padding * 2));
+            const 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;
+
+            // Visual style for the temporary crop rectangle.
             const cropRect = new fabric.Rect({
                 left, top,
                 width, height,
@@ -1672,7 +2654,8 @@ function ensureFabric() {
                 cornerSize: 8,
                 objectCaching: false,
                 originX: 'left',
-                originY: 'top'
+                originY: 'top',
+                lockScalingFlip: true
             });
 
             // Ensure the crop rect is above everything
@@ -1681,61 +2664,68 @@ function ensureFabric() {
             this.canvas.bringToFront(cropRect);
             this.canvas.setActiveObject(cropRect);
 
-            // Keep reference
+            // Store the crop rectangle so apply/cancel can clean it up.
             this._cropRect = cropRect;
 
-            // While in crop mode: we want only the cropRect to be interactive
-            // but still allow moving/scaling it. To be safe, set other objects evented=false temporarily.
+            // Keep only the crop rectangle interactive while preserving each object's previous state.
             this._cropPrevEvented = [];
-            this.canvas.getObjects().forEach(o => {
-                if (o !== cropRect) {
-                    this._cropPrevEvented.push({ obj: o, evented: o.evented, selectable: o.selectable });
-                    try { o.evented = false; o.selectable = false; } catch (e) { void e; }
+            const shouldHideMasks = !!(this.options.crop && this.options.crop.hideMasksDuringCrop);
+            this.canvas.getObjects().forEach(object => {
+                if (object !== cropRect) {
+                    this._cropPrevEvented.push({ object, evented: object.evented, selectable: object.selectable, visible: object.visible });
+                    try {
+                        const updates = {
+                            evented: false,
+                            selectable: false
+                        };
+                        if (shouldHideMasks && (object.maskId || object.maskLabel)) updates.visible = false;
+                        object.set(updates);
+                    } catch (error) { void error; }
                 }
             });
 
-            // When the crop rect changes, re-render
-            const onModified = () => { try { cropRect.setCoords(); this.canvas.requestRenderAll(); } catch (e) { void e; } };
-            cropRect.on('modified', onModified);
-            cropRect.on('moving', onModified);
-            cropRect.on('scaling', onModified);
-
-            // Keep handlers to remove later
-            this._cropHandlers.push({ target: cropRect, handlers: [{ evt: 'modified', fn: onModified }, { evt: 'moving', fn: onModified }, { evt: 'scaling', fn: onModified }] });
+            // Keep Fabric controls and configured size limits in sync as the crop rectangle changes.
+            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);
+            cropRect.on('moving', handleCropRectModified);
+            cropRect.on('scaling', handleCropRectModified);
+
+            // Store handlers so cancel/apply/dispose can unbind them.
+            this._cropHandlers.push({
+                target: cropRect,
+                handlers: [
+                    { eventName: 'modified', handler: handleCropRectModified },
+                    { eventName: 'moving', handler: handleCropRectModified },
+                    { eventName: 'scaling', handler: handleCropRectModified }
+                ]
+            });
 
             this._updateUI();
             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;
-            // Remove handlers if any and remove object
-            if (this._cropRect) {
-                try {
-                    if (this._cropHandlers && this._cropHandlers.length) {
-                        this._cropHandlers.forEach(h => {
-                            h.handlers.forEach(rec => h.target.off(rec.evt, rec.fn));
-                        });
-                    }
-                } catch (e) { void e; }
-
-                try { this.canvas.remove(this._cropRect); } catch (e) { void e; }
-                this._cropRect = null;
-            }
-            // restore evented/selectable flags
-            if (Array.isArray(this._cropPrevEvented)) {
-                this._cropPrevEvented.forEach(i => {
-                    try { i.obj.evented = i.evented; i.obj.selectable = i.selectable; } catch (e) { void e; }
-                });
-            }
-            this._cropPrevEvented = null;
-            this._cropHandlers = [];
+            this._removeCropRect();
+            this._restoreCropObjectState();
             this._cropMode = false;
-            // restore selection setting
+            // Restore the canvas selection setting that was active before crop mode.
             this.canvas.selection = !!this._prevSelectionSetting;
             this._prevSelectionSetting = undefined;
 
@@ -1745,159 +2735,129 @@ function ensureFabric() {
         }
 
         /**
-         * 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;
 
-            // Ensure crop rect coords are fresh
+            // Fabric does not update control coordinates automatically after programmatic transforms.
             this._cropRect.setCoords();
             const rectBounds = this._cropRect.getBoundingRect(true, true);
 
-            // Compute integer crop region clamped to canvas
-            const sx = Math.max(0, Math.round(rectBounds.left));
-            const sy = Math.max(0, Math.round(rectBounds.top));
-            const sw = Math.max(1, Math.round(Math.min(rectBounds.width, this.canvas.getWidth() - sx)));
-            const sh = Math.max(1, Math.round(Math.min(rectBounds.height, this.canvas.getHeight() - sy)));
+            const cropRegion = this._getClampedCanvasRegion(rectBounds);
+            const shouldPreserveMasks = !!(this.options.crop && this.options.crop.preserveMasksAfterCrop);
+
+            this._restoreCropObjectState();
 
-            // Include isCropRect in toJSON whitelist so we can detect and filter them out.
             let beforeJson = null;
             try {
-                const jsonObj = this.canvas.toJSON(['maskId', 'maskName', 'isCropRect']);
-                if (Array.isArray(jsonObj.objects)) {
-                    jsonObj.objects = jsonObj.objects.filter(o => !o.isCropRect);
-                }
-                beforeJson = JSON.stringify(jsonObj);
-            } catch (e) {
-                this._reportWarning('applyCrop: could not serialize before state', e);
+                beforeJson = this._serializeCanvasState();
+            } catch (error) {
+                this._reportWarning('applyCrop: could not serialize before state', error);
                 beforeJson = null;
             }
 
+            const preservedMasks = [];
 
-            // Remove ALL un-merged masks so they won't be baked into exported pixels
             try {
-                const masks = this.canvas.getObjects().filter(o => o.maskId);
+                const masks = this.canvas.getObjects().filter(object => object.maskId);
                 if (masks && masks.length) {
-                    masks.forEach(m => {
+                    masks.forEach(mask => {
                         try {
-                            this._removeLabelForMask(m);
-                            this.canvas.remove(m);
-                        } catch (err) {
-                            this._reportWarning('applyCrop: failed to remove mask', err);
+                            mask.setCoords();
+                            const maskBounds = mask.getBoundingRect(true, true);
+                            const intersectsCrop =
+                                maskBounds.left < cropRegion.sourceX + cropRegion.sourceWidth &&
+                                maskBounds.left + maskBounds.width > cropRegion.sourceX &&
+                                maskBounds.top < cropRegion.sourceY + cropRegion.sourceHeight &&
+                                maskBounds.top + maskBounds.height > cropRegion.sourceY;
+                            this._removeLabelForMask(mask);
+                            this.canvas.remove(mask);
+                            if (shouldPreserveMasks && intersectsCrop) {
+                                mask.set({
+                                    left: (mask.left || 0) - cropRegion.sourceX,
+                                    top: (mask.top || 0) - cropRegion.sourceY,
+                                    visible: true
+                                });
+                                mask.setCoords();
+                                preservedMasks.push(mask);
+                            }
+                        } catch (error) {
+                            this._reportWarning('applyCrop: failed to remove mask', error);
                         }
                     });
-                    this._lastMask = null;
-                    this._lastMaskInitialLeft = null;
-                    this._lastMaskInitialTop = null;
-                    this._lastMaskInitialWidth = null;
+                    this._clearMaskPlacementMemory();
                     this.canvas.discardActiveObject();
                     this.canvas.renderAll();
                 }
-            } catch (e) {
-                this._reportWarning('applyCrop: error while removing masks', e);
+            } catch (error) {
+                this._reportWarning('applyCrop: error while removing masks', error);
             }
 
-            try {
-                if (this._cropRect) {
-                    try {
-                        if (this._cropHandlers && this._cropHandlers.length) {
-                            this._cropHandlers.forEach(h => {
-                                h.handlers.forEach(rec => h.target.off(rec.evt, rec.fn));
-                            });
-                        }
-                    } catch (e) { void e; }
-                    try { this.canvas.remove(this._cropRect); } catch (e) { void e; }
-                    this._cropRect = null;
-                }
-            } catch (e) { void e; }
+            this._removeCropRect();
 
-            // End crop mode
+            // End crop mode before loading the cropped image.
             this._cropMode = false;
             this.canvas.selection = !!this._prevSelectionSetting;
             this._prevSelectionSetting = undefined;
 
-            // Export full canvas and crop on offscreen canvas
+            // Export the crop region from the current canvas.
             let croppedBase64;
             try {
-                const fullDataUrl = this.canvas.toDataURL({
-                    format: 'jpeg',
-                    quality: this.options.downsampleQuality || 0.92,
-                    multiplier: 1
-                });
-
-                croppedBase64 = await new Promise((resolve, reject) => {
-                    const img = new Image();
-                    img.onload = () => {
-                        try {
-                            const oc = document.createElement('canvas');
-                            oc.width = sw;
-                            oc.height = sh;
-                            const ctx = oc.getContext('2d');
-                            ctx.drawImage(img, sx, sy, sw, sh, 0, 0, sw, sh);
-                            const out = oc.toDataURL('image/jpeg', this.options.downsampleQuality || 0.92);
-                            resolve(out);
-                        } catch (err) {
-                            reject(err);
-                        }
-                    };
-                    img.onerror = (e) => reject(e);
-                    img.src = fullDataUrl;
+                croppedBase64 = await this._exportCanvasRegionToDataURL({
+                    ...cropRegion,
+                    multiplier: 1,
+                    quality: this._normalizeQuality(this.options.downsampleQuality),
+                    format: 'jpeg'
                 });
-            } catch (e) {
-                this._reportError('applyCrop: failed to create cropped image', e);
-                this._updateUI();
+            } catch (error) {
+                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: failed to create cropped image', error);
                 return;
             }
 
-            // Load the cropped image as the new base image
+            // Load the cropped image as the new base image.
             try {
                 await this.loadImage(croppedBase64);
-            } catch (e) {
-                this._reportError('applyCrop: loadImage(croppedBase64) failed', e);
-                this._updateUI();
+                if (preservedMasks.length) {
+                    preservedMasks.forEach(mask => {
+                        this._rebindMaskEvents(mask);
+                        this.canvas.add(mask);
+                        this.canvas.bringToFront(mask);
+                    });
+                    this._lastMask = preservedMasks[preservedMasks.length - 1];
+                    this.maskCounter = preservedMasks.reduce((max, mask) => Math.max(max, mask.maskId || 0), this.maskCounter);
+                    this._updateMaskList();
+                    this.canvas.renderAll();
+                }
+            } catch (error) {
+                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: loadImage(croppedBase64) failed', error);
                 return;
             }
 
-            // Create "after" snapshot (also exclude crop rect if any) and push history command
+            // Create an after snapshot and push one history command for the crop operation.
             let afterJson = null;
             try {
-                const jsonObj2 = this.canvas.toJSON(['maskId', 'maskName', 'isCropRect']);
-                if (Array.isArray(jsonObj2.objects)) {
-                    jsonObj2.objects = jsonObj2.objects.filter(o => !o.isCropRect);
-                }
-                afterJson = JSON.stringify(jsonObj2);
-            } catch (e) {
-                this._reportWarning('applyCrop: failed to serialize after state', e);
+                afterJson = this._serializeCanvasState();
+            } catch (error) {
+                this._reportWarning('applyCrop: failed to serialize after state', error);
                 afterJson = null;
             }
 
             try {
-                const self = this;
-                const cmd = new Command(
-                    () => { if (afterJson) self.loadFromState(afterJson); },
-                    () => { if (beforeJson) self.loadFromState(beforeJson); }
-                );
-
-                if (!this.historyManager) this.historyManager = new HistoryManager(this.maxHistorySize || 50);
-
-                // trim future redo history
-                if (this.historyManager.currentIndex < this.historyManager.history.length - 1) {
-                    this.historyManager.history = this.historyManager.history.slice(0, this.historyManager.currentIndex + 1);
-                }
-
-                this.historyManager.history.push(cmd);
-                if (this.historyManager.history.length > this.historyManager.maxSize) {
-                    this.historyManager.history.shift();
-                } else {
-                    this.historyManager.currentIndex++;
-                }
-            } catch (e) {
-                this._reportWarning('applyCrop: failed to push history command', e);
+                this._pushStateTransition(beforeJson, afterJson);
+            } catch (error) {
+                this._reportWarning('applyCrop: failed to push history command', error);
             }
 
-            // Final UI update
+            // Refresh UI state after crop completion.
             this._updateUI();
             this.canvas.renderAll();
         }
@@ -1911,8 +2871,8 @@ function ensureFabric() {
          * @private
          */
         _updateInputs() {
-            const scaleEl = document.getElementById(this.elements.scaleRate);
-            if (scaleEl) scaleEl.value = Math.round(this.currentScale * 100);
+            const scaleInputElement = document.getElementById(this.elements.scaleRate);
+            if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
         }
 
         /**
@@ -1921,45 +2881,47 @@ function ensureFabric() {
          * @private
          */
         _updateUI() {
-            const hasImg = !!this.originalImage;
-            const masks = hasImg ? this.canvas.getObjects().filter(o => o.maskId) : [];
+            const hasImage = !!this.originalImage;
+            const masks = hasImage ? this.canvas.getObjects().filter(object => object.maskId) : [];
             const hasMasks = masks.length > 0;
-            const active = this.canvas.getActiveObject();
-            const hasSelectedMask = active && active.maskId;
-            const isDefault = this.currentScale === 1 && this.currentRotation === 0;
+            const activeObject = this.canvas.getActiveObject();
+            const hasSelectedMask = activeObject && activeObject.maskId;
+            const isDefaultTransform = this.currentScale === 1 && this.currentRotation === 0;
             const canUndo = this.historyManager?.canUndo();
             const canRedo = this.historyManager?.canRedo();
-            const inCrop = !!this._cropMode;
-
-            if (inCrop) {
-                // iterate all element keys and disable unless key is applyCropBtn or cancelCropBtn
-                for (const k of Object.keys(this.elements || {})) {
-                    const el = document.getElementById(this.elements[k]);
-                    if (!el) continue;
-                    if (k === 'applyCropBtn' || k === 'cancelCropBtn') {
-                        el.disabled = false;
+            const isInCropMode = !!this._cropMode;
+
+            if (isInCropMode) {
+                // Disable all controls except the crop action buttons while crop mode is active.
+                for (const key of Object.keys(this.elements || {})) {
+                    const element = document.getElementById(this.elements[key]);
+                    if (!element) continue;
+                    if (key === 'applyCropBtn' || key === 'cancelCropBtn') {
+                        this._setDisabled(key, false);
                     } else {
-                        el.disabled = true;
+                        this._setDisabled(key, true);
                     }
                 }
                 return;
             }
 
-            this._setDisabled('zoomInBtn', !hasImg || this.isAnimating || this.currentScale >= this.options.maxScale);
-            this._setDisabled('zoomOutBtn', !hasImg || this.isAnimating || this.currentScale <= this.options.minScale);
-            this._setDisabled('rotateLeftBtn', !hasImg || this.isAnimating);
-            this._setDisabled('rotateRightBtn', !hasImg || this.isAnimating);
-            this._setDisabled('addMaskBtn', !hasImg || this.isAnimating);
+            this._setDisabled('zoomInBtn', !hasImage || this.isAnimating || this.currentScale >= this.options.maxScale);
+            this._setDisabled('zoomOutBtn', !hasImage || this.isAnimating || this.currentScale <= this.options.minScale);
+            this._setDisabled('rotateLeftBtn', !hasImage || this.isAnimating);
+            this._setDisabled('rotateRightBtn', !hasImage || this.isAnimating);
+            this._setDisabled('addMaskBtn', !hasImage || this.isAnimating);
             this._setDisabled('removeMaskBtn', !hasSelectedMask || this.isAnimating);
             this._setDisabled('removeAllMasksBtn', !hasMasks || this.isAnimating);
-            this._setDisabled('mergeBtn', !hasImg || !hasMasks || this.isAnimating);
-            this._setDisabled('downloadBtn', !hasImg || this.isAnimating);
-            this._setDisabled('resetBtn', !hasImg || isDefault || this.isAnimating);
-            this._setDisabled('undoBtn', !hasImg || this.isAnimating || !canUndo);
-            this._setDisabled('redoBtn', !hasImg || this.isAnimating || !canRedo);
-            this._setDisabled('cropBtn', !hasImg || this.isAnimating);
+            this._setDisabled('mergeBtn', !hasImage || !hasMasks || this.isAnimating);
+            this._setDisabled('downloadBtn', !hasImage || this.isAnimating);
+            this._setDisabled('resetBtn', !hasImage || isDefaultTransform || this.isAnimating);
+            this._setDisabled('undoBtn', !hasImage || this.isAnimating || !canUndo);
+            this._setDisabled('redoBtn', !hasImage || this.isAnimating || !canRedo);
+            this._setDisabled('cropBtn', !hasImage || this.isAnimating);
             this._setDisabled('applyCropBtn', true);
             this._setDisabled('cancelCropBtn', true);
+            this._setDisabled('imageInput', this.isAnimating);
+            this._setDisabled('uploadArea', this.isAnimating);
         }
 
         /**
@@ -1970,12 +2932,30 @@ function ensureFabric() {
          * @private
          */
         _setDisabled(key, disabled) {
-            const el = document.getElementById(this.elements[key]);
-            if (el) el.disabled = !!disabled;
+            const element = document.getElementById(this.elements[key]);
+            if (!element) return;
+            if ('disabled' in element) {
+                element.disabled = !!disabled;
+                return;
+            }
+
+            if (disabled) {
+                element.setAttribute('aria-disabled', 'true');
+                element.style.pointerEvents = 'none';
+            } else {
+                element.removeAttribute('aria-disabled');
+                element.style.pointerEvents = '';
+            }
+        }
+
+        _isElementDisabled(element) {
+            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() {
@@ -1984,20 +2964,21 @@ function ensureFabric() {
         }
 
         /**
-         * 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.placeholderEl) return;
+            if (!this.placeholderElement || !this.containerElement) return;
             if (show) {
-                this.placeholderEl.classList.remove('d-none');
-                this.placeholderEl.classList.add('d-flex');
-                this.containerEl.classList.add('d-none');
+                this.placeholderElement.classList.remove('d-none');
+                this.placeholderElement.classList.add('d-flex');
+                this.containerElement.classList.add('d-none');
             } else {
-                this.placeholderEl.classList.remove('d-flex');
-                this.placeholderEl.classList.add('d-none');
-                this.containerEl.classList.remove('d-none');
+                this.placeholderElement.classList.remove('d-flex');
+                this.placeholderElement.classList.add('d-none');
+                this.containerElement.classList.remove('d-none');
             }
         }
 
@@ -2009,132 +2990,190 @@ function ensureFabric() {
         dispose() {
             // Remove bound DOM event listeners
             try {
-                for (const key in (this._boundHandlers || {})) {
-                    const handlers = this._boundHandlers[key] || [];
-                    const el = document.getElementById(this.elements[key]);
-                    if (!el) continue;
-                    handlers.forEach(h => {
-                        try { el.removeEventListener(h.event, h.handler); } catch (e) { void e; }
+                for (const key in (this._handlersByElementKey || {})) {
+                    const handlers = this._handlersByElementKey[key] || [];
+                    const element = document.getElementById(this.elements[key]);
+                    if (!element) continue;
+                    handlers.forEach(handlerRecord => {
+                        try { element.removeEventListener(handlerRecord.eventName, handlerRecord.handler); } catch (error) { void error; }
                     });
                 }
-            } catch (e) { void e; }
+            } catch (error) { void error; }
 
             if (this._cropRect) {
-                try { this.canvas.remove(this._cropRect); } catch (e) { void e; }
+                try { this.canvas.remove(this._cropRect); } catch (error) { void error; }
                 this._cropRect = null;
             }
 
+            if (this.containerElement && this._containerOriginalOverflow !== undefined) {
+                try { this.containerElement.style.overflow = this._containerOriginalOverflow; } catch (error) { void error; }
+            }
+
             if (this.canvas) {
-                try { this.canvas.dispose(); } catch (e) { void e; }
+                try { this.canvas.dispose(); } catch (error) { void error; }
                 this.canvas = null;
-                this.canvasEl = null;
+                this.canvasElement = null;
                 this.isImageLoadedToCanvas = false;
             }
-            this._boundHandlers = {};
+            this._handlersByElementKey = {};
         }
     }
 
     /**
-     * A simple FIFO queue that guarantees animations are executed sequentially.
-     * @class AnimationQueue
+     * @callback AnimationTaskCallback
+     * @returns {unknown} Animation result or awaitable animation result.
+     */
+
+    /**
+     * @callback PromiseResolveCallback
+     * @param {unknown} value - Promise resolution value.
+     * @returns {void}
+     */
+
+    /**
+     * @callback PromiseRejectCallback
+     * @param {unknown} reason - Promise rejection reason.
+     * @returns {void}
+     */
+
+    /**
+     * @typedef {Object} QueuedAnimationTask
+     * @property {AnimationTaskCallback} animationFn - Queued animation function.
+     * @property {PromiseResolveCallback} resolve - Promise resolver for the queued animation.
+     * @property {PromiseRejectCallback} reject - Promise rejecter for the queued animation.
+     */
+
+    /**
+     * @callback HistoryTaskCallback
+     * @returns {void|Promise<void>} Result of a history operation.
+     */
+
+    /**
+     * FIFO queue that serializes transform animations so Fabric state changes do not overlap.
+     *
+     * @private
      */
     class AnimationQueue {
         /**
-         * Creates a new AnimationQueue.
-         *
-         * @constructor
+         * Creates an empty animation queue.
          */
         constructor() {
             /**
-             * Internal queue holding animation descriptors.
-             * @type {Array<{fn: Function, resolve: Function, reject: Function}>}
+             * Pending animation descriptors.
+             * @type {Array<QueuedAnimationTask>}
              */
-            this.queue = [];
+            this.animationTasks = [];
             /**
-             * Flag indicating whether an animation is currently running.
+             * Whether an animation task is currently running.
              * @type {boolean}
              */
-            this.running = false;
+            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) => {
-                // Push the animation into the queue.
-                this.queue.push({ fn: animationFn, resolve, reject });
-                // Start processing if it's not already running.
-                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();
         }
     }
 
     /**
-     * Command object encapsulating an executable action and its corresponding undo operation.
-     * @class Command
+     * Undoable command with paired execute and undo operations.
+     *
+     * @private
      */
     class Command {
         /**
-         * @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) {
             /**
              * Executes the command.
-             * @type {Function}
+             * @type {HistoryTaskCallback}
              */
             this.execute = execute;
             /**
              * Undoes the command.
-             * @type {Function}
+             * @type {HistoryTaskCallback}
              */
             this.undo = undo;
         }
     }
 
     /**
-     * Manages a history of Command objects enabling undo/redo functionality.
-     * @class HistoryManager
+     * Manages undo/redo history and serializes asynchronous history operations.
+     *
+     * @private
      */
     class HistoryManager {
         /**
-         * @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) {
+            /** @type {Array<Command>} */
             this.history = [];
+            /** @type {number} */
             this.currentIndex = -1;
+            /** @type {number} */
             this.maxSize = maxSize;
+            /** @type {Promise<void>} */
+            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 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;
         }
 
         /**
@@ -2145,20 +3184,27 @@ function ensureFabric() {
          * @returns {void}
          */
         execute(command) {
-            // Perform the command.
             command.execute();
+            this.push(command);
+        }
 
-            // Remove any commands that are ahead of the current index.
+        /**
+         * Pushes an already-applied command onto the history stack.
+         * Truncates any "future" history when branching.
+         *
+         * @param {Command} command  The command to push.
+         * @returns {void}
+         */
+        push(command) {
+            // Discard redo commands when a new branch is created.
             if (this.currentIndex < this.history.length - 1) {
                 this.history = this.history.slice(0, this.currentIndex + 1);
             }
 
-            // Add the new command.
             this.history.push(command);
 
-            // Maintain the max size of the buffer.
             if (this.history.length > this.maxSize) {
-                this.history.shift(); // Remove the oldest command.
+                this.history.shift();
             } else {
                 this.currentIndex++;
             }
@@ -2185,25 +3231,31 @@ function ensureFabric() {
         /**
          * Undoes the last executed command if possible.
          *
-         * @returns {void}
+         * @returns {Promise<void>} Resolves after the undo task completes.
          */
         undo() {
-            if (this.currentIndex >= 0) {
-                this.history[this.currentIndex].undo();
-                this.currentIndex--;
-            }
+            return this.enqueue(async () => {
+                if (this.currentIndex >= 0) {
+                    const index = this.currentIndex;
+                    await this.history[index].undo();
+                    this.currentIndex = index - 1;
+                }
+            });
         }
 
         /**
          * Redoes the next command in history if possible.
          *
-         * @returns {void}
+         * @returns {Promise<void>} Resolves after the redo task completes.
          */
         redo() {
-            if (this.currentIndex < this.history.length - 1) {
-                this.currentIndex++;
-                this.history[this.currentIndex].execute();
-            }
+            return this.enqueue(async () => {
+                if (this.currentIndex < this.history.length - 1) {
+                    const index = this.currentIndex + 1;
+                    await this.history[index].execute();
+                    this.currentIndex = index;
+                }
+            });
         }
     }