@bensitu/image-editor 1.5.1 → 2.0.0

package/README.md

@@ -1,27 +1,19 @@
-# ImageEditor
+# @bensitu/image-editor
 
-[![npm](https://img.shields.io/npm/l/image-editor.svg)](https://github.com/bensitu/image-editor)
+[![npm](https://img.shields.io/npm/l/@bensitu/image-editor.svg)](https://github.com/bensitu/image-editor)
 [![npm](https://img.shields.io/npm/v/@bensitu/image-editor.svg)](https://www.npmjs.com/package/@bensitu/image-editor)
 [![](https://data.jsdelivr.com/v1/package/npm/@bensitu/image-editor/badge)](https://www.jsdelivr.com/package/npm/@bensitu/image-editor)
 
-A lightweight JavaScript wrapper around fabric.js that provides image loading, scaling, rotation, cropping, mask management, history, and export helpers.
+A lightweight, TypeScript-first canvas image editor built on top of
+[Fabric.js](https://fabricjs.com/) v7. `ImageEditor` wraps a Fabric canvas
+with image loading, scale and rotation, mask creation, crop, history
+(undo/redo), and base64/file export — exposed as a single canonical class
+with a stable public surface.
 
-## Overview
-
-ImageEditor offers:
-
-- Image loading from base64 data URLs or file input
-- Zoom in/out and reset transform helpers
-- Rotation with custom degrees or step-based controls
-- Crop mode with optional mask preservation
-- Mask creation, selection, removal, and label support
-- Undo/redo history helpers
-- Merge, download, base64 export, and `File` export helpers
-- Optional DOM/UI binding for common editor controls
-- Large-image downsampling to reduce browser memory pressure
-- Centralized error and warning callbacks
-
-**Note:** This library requires **fabric.js v5.x** to be loaded before creating or initializing the editor.
+> **v2.0.0 is a behavior-preserving migration.** The v1 deprecated method
+> and property aliases have been removed in favor of the canonical names
+> documented below. See [`CHANGELOG.md`](./CHANGELOG.md) for the complete
+> rename map.
 
 ## Demo
 
@@ -29,69 +21,109 @@ ImageEditor offers:
 
 ## Features
 
-- **Fabric.js-powered canvas** - Built on top of fabric.js.
-- **Image scaling** - Configurable min/max limits with smooth animation.
-- **Image rotation** - Step control and animated transitions.
-- **Auto-resizing** - Optional canvas resizing to match the image, fit the viewport, or cover the viewport.
-- **Image crop** - Enter a temporary crop mode and apply or cancel the crop.
-- **Mask management** - Add, remove, remove all, drag, resize, and optionally rotate masks.
-- **Mask labels** - Auto-sync labels with mask movement and scaling.
-- **History** - Undo and redo supported editor state changes.
-- **Performance optimization** - Downsample large images on load.
-- **Export & download** - Export as base64 data URL, `File`, or direct download.
-- **DOM/UI binding** - Bind common buttons, inputs, and placeholders by element ID.
+- TypeScript source with `.d.ts` declarations published alongside the runtime
+- Single canonical class `ImageEditor` exported as both default and named
+- Fabric.js v7 declared as a peer dependency (no bundled Fabric copy)
+- Multi-format publish: ESM (`import`), CommonJS (`require`), UMD (`<script>`),
+  TypeScript declarations (`types`)
+- Transactional `loadImage` with rollback on decode, Fabric, downsample, or
+  timeout failures
+- Animation queue serializes `scaleImage`, `rotateImage`,
+  `resetImageTransform`, `undo`, and `redo` so concurrent clicks never
+  interleave
+- Bounded history stack with idempotent dispose
+- Crop session with mask preservation toggle and atomic apply/cancel
+- Base64 and `File` exports with PNG/JPEG/WebP support, configurable
+  multiplier, and mask compositing
+
+## Requirements
+
+- **Node.js**: `>= 20` for development / building from source
+- **Fabric.js**: peer dependency `^7.0.0` (must be installed by the consumer)
+- **Browsers**: modern evergreen (Chrome, Firefox, Safari, Edge). The library
+  uses ES2022 features and the Fabric v7 promise-based API.
+- **TypeScript**: strict consumers that compile dependencies with
+  `skipLibCheck: false` should include the ES2022 library in `tsconfig.json`.
+  Fabric v7.4 declarations also reference `jsdom` types, so install
+  `@types/jsdom` when your project type-checks Fabric's declaration files.
 
 ## Installation
 
-### npm / pnpm / yarn
-
 ```bash
-npm i @bensitu/image-editor fabric
+npm install @bensitu/image-editor fabric
 # or
 pnpm add @bensitu/image-editor fabric
 # or
 yarn add @bensitu/image-editor fabric
 ```
 
-### ESM / bundler usage
+`fabric@^7.0.0` is a peer dependency: install it explicitly so the editor
+resolves the exact version your application uses.
 
-```javascript
-import ImageEditor, {
-  ImageEditor as NamedImageEditor,
-} from "@bensitu/image-editor";
-```
+## Module formats and entry points
 
-### Browser global usage
+The package ships a single public entry, resolved by tooling via the
+`exports` map in `package.json`:
 
-Include fabric.js first, then ImageEditor:
+| Consumer                              | Resolves to                    |
+| ------------------------------------- | ------------------------------ |
+| ESM (`import`)                        | `dist/esm/index.js`            |
+| CommonJS (`require`)                  | `dist/cjs/index.cjs`           |
+| TypeScript (`types`)                  | `dist/types/index.d.ts`        |
+| UMD (`<script>`, `unpkg`, `jsdelivr`) | `dist/umd/image-editor.umd.js` |
+| `default` fallback                    | `dist/esm/index.js`            |
 
-```html
-<!-- Fabric.js (required) -->
-<script src="https://cdn.jsdelivr.net/npm/fabric@5.5.2/dist/fabric.min.js"></script>
+The UMD bundle exposes a global named `ImageEditor` and treats `fabric` as an
+external global named `fabric`.
 
-<!-- ImageEditor -->
-<script src="path/to/dist/image-editor.min.js"></script>
-<!-- or -->
-<script src="https://cdn.jsdelivr.net/npm/@bensitu/image-editor/dist/image-editor.min.js"></script>
-```
+## Dual entry-point convention
+
+`ImageEditor`'s constructor accepts the Fabric module either explicitly (ESM
+consumers) or via `globalThis.fabric` (UMD consumers). The same source ships
+in all four formats:
+
+- **Explicit module form** (recommended for bundled apps): pass the Fabric
+  module as the first argument.
 
-Use `dist/image-editor.js` or `dist/image-editor.min.js` for browser global script usage. Use `dist/image-editor.esm.mjs` or `dist/image-editor.esm.min.mjs` for standards-compliant ESM imports. Matching `.js` ESM builds are also generated for browser and bundler compatibility.
+    ```ts
+    import * as fabric from 'fabric';
+    import { ImageEditor } from '@bensitu/image-editor';
 
-## Quick Start
+    const editor = new ImageEditor(fabric, {
+        canvasWidth: 800,
+        canvasHeight: 600,
+    });
+    ```
 
-### HTML Structure
+- **Global form** (UMD `<script>` consumers): omit the first argument; the
+  constructor reads `globalThis.fabric`.
+
+    ```html
+    <script src="https://cdn.jsdelivr.net/npm/fabric@7/dist/index.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@bensitu/image-editor/dist/umd/image-editor.umd.js"></script>
+    <script>
+        const editor = new ImageEditor({
+            canvasWidth: 800,
+            canvasHeight: 600,
+        });
+    </script>
+    ```
+
+If neither form yields a usable Fabric module, the constructor logs a single
+descriptive `console.error` and `init()` and `loadImage()` become no-ops that
+resolve to `undefined`.
+
+## Quick start
+
+### HTML
 
 ```html
-<!-- Canvas -->
-<canvas id="fabricCanvas"></canvas>
+<canvas id="canvas"></canvas>
 
-<!-- Optional Controls -->
 <button id="zoomInButton">Zoom In</button>
 <button id="zoomOutButton">Zoom Out</button>
-
 <button id="rotateLeftButton">Rotate Left</button>
 <input id="rotateLeftDegreesInput" type="number" value="90" />
-
 <button id="rotateRightButton">Rotate Right</button>
 <input id="rotateRightDegreesInput" type="number" value="90" />
 
@@ -103,471 +135,343 @@ Use `dist/image-editor.js` or `dist/image-editor.min.js` for browser global scri
 <button id="applyCropButton">Apply Crop</button>
 <button id="cancelCropButton">Cancel Crop</button>
 
+<button id="mergeMasksButton">Merge</button>
+<button id="downloadImageButton">Download</button>
 <button id="undoButton">Undo</button>
 <button id="redoButton">Redo</button>
-
-<button id="mergeMasksButton">Merge</button>
 <button id="resetImageTransformButton">Reset</button>
-<button id="downloadImageButton">Download</button>
 
 <input id="imageInput" type="file" accept="image/*" />
+<ul id="maskList"></ul>
 ```
 
-### JavaScript Implementation
+### TypeScript / ESM
 
-The constructor options are optional. For the smallest setup, create an editor instance and bind it to a canvas element.
+```ts
+import * as fabric from 'fabric';
+import { ImageEditor } from '@bensitu/image-editor';
+import type { ImageEditorOptions, MaskConfig } from '@bensitu/image-editor';
 
-```javascript
-const editor = new ImageEditor();
+const editor = new ImageEditor(fabric, {
+    canvasWidth: 800,
+    canvasHeight: 600,
+    backgroundColor: '#ffffff',
+} satisfies ImageEditorOptions);
 
 editor.init({
-  canvas: "fabricCanvas"
+    canvas: 'canvas',
+    zoomInButton: 'zoomInButton',
+    zoomOutButton: 'zoomOutButton',
+    rotateLeftButton: 'rotateLeftButton',
+    rotateLeftDegreesInput: 'rotateLeftDegreesInput',
+    rotateRightButton: 'rotateRightButton',
+    rotateRightDegreesInput: 'rotateRightDegreesInput',
+    createMaskButton: 'createMaskButton',
+    removeSelectedMaskButton: 'removeSelectedMaskButton',
+    removeAllMasksButton: 'removeAllMasksButton',
+    enterCropModeButton: 'enterCropModeButton',
+    applyCropButton: 'applyCropButton',
+    cancelCropButton: 'cancelCropButton',
+    mergeMasksButton: 'mergeMasksButton',
+    downloadImageButton: 'downloadImageButton',
+    undoButton: 'undoButton',
+    redoButton: 'redoButton',
+    resetImageTransformButton: 'resetImageTransformButton',
+    imageInput: 'imageInput',
+    maskList: 'maskList',
 });
-```
 
-`canvas` is the only required DOM binding when your canvas element does not use the default ID `fabricCanvas`. All other DOM bindings are optional.
+// Load an image programmatically (base64 data URL).
+await editor.loadImage('data:image/jpeg;base64,...');
 
-#### Optional Configuration
+// Add a rectangular mask, then export the result as base64.
+const mask: MaskConfig = { shape: 'rect', width: 120, height: 80, left: '25%', top: '25%' };
+editor.createMask(mask);
 
-You can pass options to override the built-in defaults.
-
-```javascript
-const editor = new ImageEditor({
-  canvasWidth: 800,
-  canvasHeight: 600,
-  backgroundColor: "#ffffff",
-  initialImageBase64: null
-});
+const dataUrl = await editor.exportImageBase64({ fileType: 'png' });
 ```
 
-These are common optional overrides, not required settings.
-
-#### Demo-style Configuration
-
-The docs demo uses an explicit configuration so the demo behavior is predictable. These options are not required for normal usage.
-
-```javascript
-const editor = new ImageEditor({
-  // Layout mode. Enable only one layout mode at a time.
-  expandCanvasToImage: false,
-  fitImageToCanvas: true,
-  coverImageToCanvas: false,
-
-  // Image loading / performance.
-  downsampleOnLoad: true,
-  initialImageBase64: null,
+### CommonJS
 
-  // Mask behavior.
-  maskRotatable: true,
-  maskLabelOnSelect: true,
-  maskLabelOffset: 5,
+```js
+const fabric = require('fabric');
+const { ImageEditor } = require('@bensitu/image-editor');
 
-  // UI behavior.
-  backgroundColor: "transparent",
-  showPlaceholder: true,
-  animationDuration: 100,
-
-  // Export behavior.
-  exportImageAreaByDefault: true
-});
-
-editor.init({
-  canvas: "fabricCanvas",
-  imagePlaceholder: "imagePlaceholder",
-  scalePercentageInput: "scalePercentageInput",
-  rotateLeftButton: "rotateLeftButton",
-  rotateRightButton: "rotateRightButton",
-  rotateLeftDegreesInput: "rotateLeftDegreesInput",
-  rotateRightDegreesInput: "rotateRightDegreesInput",
-  removeSelectedMaskButton: "removeSelectedMaskButton",
-  removeAllMasksButton: "removeAllMasksButton",
-  mergeMasksButton: "mergeMasksButton",
-  downloadImageButton: "downloadImageButton",
-  maskList: "maskList",
-  enterCropModeButton: "enterCropModeButton",
-  applyCropButton: "applyCropButton",
-  cancelCropButton: "cancelCropButton",
-  resetImageTransformButton: "resetImageTransformButton"
-});
+const editor = new ImageEditor(fabric, { canvasWidth: 800, canvasHeight: 600 });
 ```
 
+In v2, `require('@bensitu/image-editor')` returns a namespace object with
+`ImageEditor`, `default`, and `isMaskObject`; it does not return the
+constructor directly.
 
-### Loading an Image Manually
+## Public API
 
-```javascript
-async function loadImageDataUrl(imageBase64) {
-  try {
-    await editor.loadImage(imageBase64);
-  } catch (error) {
-    console.error("Image could not be loaded:", error);
-  }
-}
+`ImageEditor` is the only public class. The package barrel re-exports it as
+both the default export and a named export, alongside `isMaskObject` and the
+documented public types. Internal helpers (animation queue, command, history
+manager, controllers, services, managers, utility modules) are intentionally
+not exported and may change without notice.
 
-loadImageDataUrl("data:image/jpeg;base64,...");
-```
+### Constructor
 
-## Configuration Options
-
-All options are optional. If an option is not provided, the editor uses the default value listed below.
-
-When creating the editor instance, pass an options object to override defaults.
-
-| Option                        | Default                   | Description                                                                                                                                           |
-| ----------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `canvasWidth`                 | `800`                     | Initial canvas width in pixels.                                                                                                                       |
-| `canvasHeight`                | `600`                     | Initial canvas height in pixels.                                                                                                                      |
-| `backgroundColor`             | `transparent`             | Canvas background color.                                                                                                                              |
-| `animationDuration`           | `300`                     | Animation duration for scale and rotation operations, in milliseconds.                                                                                |
-| `minScale`                    | `0.1`                     | Minimum image scale factor.                                                                                                                           |
-| `maxScale`                    | `5.0`                     | Maximum image scale factor.                                                                                                                           |
-| `scaleStep`                   | `0.05`                    | Scale increment/decrement used by zoom controls.                                                                                                      |
-| `rotationStep`                | `90`                      | Default rotation step in degrees.                                                                                                                     |
-| `expandCanvasToImage`         | `true`                    | Expand the canvas to the loaded image size.                                                                                                           |
-| `fitImageToCanvas`            | `false`                   | Fit the loaded image inside the visible canvas viewport.                                                                                              |
-| `coverImageToCanvas`          | `false`                   | Scale the image to cover the visible canvas viewport, allowing overflow when needed.                                                                  |
-| `downsampleOnLoad`            | `true`                    | Downsample large images before rendering.                                                                                                             |
-| `downsampleMaxWidth`          | `4000`                    | Maximum source image width before downsampling.                                                                                                       |
-| `downsampleMaxHeight`         | `3000`                    | Maximum source image height before downsampling.                                                                                                      |
-| `downsampleQuality`           | `0.92`                    | JPEG/WebP quality used when downsampling. `0` is valid and is preserved.                                                                              |
-| `preserveSourceFormat`        | `true`                    | Preserve the source image format where possible during downsampling.                                                                                  |
-| `downsampleMimeType`          | `null`                    | Optional output MIME type for downsampled images. Supported values include `jpeg`, `jpg`, `png`, `webp`, `image/jpeg`, `image/png`, and `image/webp`. |
-| `imageLoadTimeoutMs`          | `30000`                   | Timeout for image decode/load operations.                                                                                                             |
-| `exportMultiplier`            | `1`                       | Default scale multiplier for export.                                                                                                                  |
-| `exportImageAreaByDefault`    | `true`                    | Export only the image area by default instead of the full canvas.                                                                                     |
-| `defaultMaskWidth`            | `50`                      | Default mask width in pixels.                                                                                                                         |
-| `defaultMaskHeight`           | `80`                      | Default mask height in pixels.                                                                                                                        |
-| `maskRotatable`               | `false`                   | Whether masks can be rotated.                                                                                                                         |
-| `maskLabelOnSelect`           | `true`                    | Show the mask label when a mask is selected.                                                                                                          |
-| `maskLabelOffset`             | `3`                       | Offset for mask labels from the mask's top-left corner.                                                                                               |
-| `maskName`                    | `mask`                    | Prefix for mask names and labels.                                                                                                                     |
-| `groupSelection`              | `false`                   | Whether Fabric can select multiple masks as an active selection.                                                                                      |
-| `label.getText`               | `(mask) => mask.maskName` | Callback for custom label text. The second argument is the mask's stable zero-based creation index (`mask.maskId - 1`).                               |
-| `showPlaceholder`             | `true`                    | Show a placeholder when no image is loaded.                                                                                                           |
-| `initialImageBase64`          | `null`                    | Base64 data URL to auto-load during initialization.                                                                                                   |
-| `defaultDownloadFileName`     | `edited_image.jpg`        | Default file name for downloads.                                                                                                                      |
-| `crop.preserveMasksAfterCrop` | `false`                   | Keep masks that intersect the crop area, shifted into the cropped canvas. Merge masks first if they should be baked into the image pixels.            |
-| `onImageLoaded`               | `null`                    | Callback invoked after an image finishes loading.                                                                                                     |
-| `onError`                     | `null`                    | Callback invoked for recoverable internal errors.                                                                                                     |
-| `onWarning`                   | `null`                    | Callback invoked for recoverable internal warnings.                                                                                                   |
-
-`expandCanvasToImage`, `fitImageToCanvas`, and `coverImageToCanvas` are mutually exclusive layout modes. If more than one is enabled, the editor reports a warning and uses the first active mode in its existing load order.
-
-## DOM Binding Keys
-
-`init(idMap)` binds editor behavior to DOM elements by ID. All keys are optional.
-
-| Key                         | Description                                                    |
-| --------------------------- | -------------------------------------------------------------- |
-| `canvas`                    | Required canvas element ID.                                    |
-| `canvasContainer`           | Optional scrollable viewport/container element ID.             |
-| `imagePlaceholder`          | Optional placeholder element shown when no image is loaded.    |
-| `scalePercentageInput`      | Optional element used to display the current scale percentage. |
-| `rotateLeftDegreesInput`    | Optional input used by the rotate-left button.                 |
-| `rotateRightDegreesInput`   | Optional input used by the rotate-right button.                |
-| `rotateLeftButton`          | Rotate image left.                                             |
-| `rotateRightButton`         | Rotate image right.                                            |
-| `createMaskButton`          | Create a new mask.                                             |
-| `removeSelectedMaskButton`  | Remove the currently selected mask.                            |
-| `removeAllMasksButton`      | Remove all masks.                                              |
-| `mergeMasksButton`          | Merge masks into the base image.                               |
-| `downloadImageButton`       | Download the edited image.                                     |
-| `maskList`                  | Optional mask list container.                                  |
-| `zoomInButton`              | Zoom in.                                                       |
-| `zoomOutButton`             | Zoom out.                                                      |
-| `resetImageTransformButton` | Reset scale and rotation.                                      |
-| `undoButton`                | Undo the last state change.                                    |
-| `redoButton`                | Redo the next state change.                                    |
-| `imageInput`                | File input used to load images.                                |
-| `uploadArea`                | Optional clickable upload area that triggers the file input.   |
-| `enterCropModeButton`       | Enter crop mode.                                               |
-| `applyCropButton`           | Apply the current crop rectangle.                              |
-| `cancelCropButton`          | Cancel crop mode.                                              |
-
-### Legacy DOM Binding Keys
-
-The following DOM binding keys remain supported in `1.x` for compatibility, but are deprecated and will be removed in `v2.0.0`.
-
-| Deprecated key       | Use instead                 |
-| -------------------- | --------------------------- |
-| `imgPlaceholder`     | `imagePlaceholder`          |
-| `scaleRate`          | `scalePercentageInput`      |
-| `rotationLeftInput`  | `rotateLeftDegreesInput`    |
-| `rotationRightInput` | `rotateRightDegreesInput`   |
-| `rotateLeftBtn`      | `rotateLeftButton`          |
-| `rotateRightBtn`     | `rotateRightButton`         |
-| `addMaskBtn`         | `createMaskButton`          |
-| `removeMaskBtn`      | `removeSelectedMaskButton`  |
-| `removeAllMasksBtn`  | `removeAllMasksButton`      |
-| `mergeBtn`           | `mergeMasksButton`          |
-| `downloadBtn`        | `downloadImageButton`       |
-| `zoomInBtn`          | `zoomInButton`              |
-| `zoomOutBtn`         | `zoomOutButton`             |
-| `resetBtn`           | `resetImageTransformButton` |
-| `undoBtn`            | `undoButton`                |
-| `redoBtn`            | `redoButton`                |
-| `cropBtn`            | `enterCropModeButton`       |
-| `applyCropBtn`       | `applyCropButton`           |
-| `cancelCropBtn`      | `cancelCropButton`          |
-
-## API Methods
-
-| Method                            | Returns                 | Description                                                                                                           |
-| --------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `init(idMap)`                     | `void`                  | Bind the editor to DOM elements. Pass IDs in an object.                                                               |
-| `loadImage(imageBase64, options)` | `Promise<void>`         | Load an image from a base64 data URL. Resolves after the Fabric image is on the canvas.                               |
-| `isImageLoaded()`                 | `boolean`               | Return whether a valid image is loaded on the canvas.                                                                 |
-| `isBusy()`                        | `boolean`               | Return whether the editor is loading, animating, cropping, or running another compound operation.                     |
-| `scaleImage(factor)`              | `Promise<void>`         | Scale the image to the given factor relative to the base scale.                                                       |
-| `rotateImage(degrees)`            | `Promise<void>`         | Rotate the image to the given angle in degrees.                                                                       |
-| `resetImageTransform()`           | `Promise<void>`         | Reset scale to `1` and rotation to `0`.                                                                               |
-| `undo()`                          | `Promise<void>`         | Undo the last state change. Resolves after the canvas state is restored.                                              |
-| `redo()`                          | `Promise<void>`         | Redo the next state change. Resolves after the canvas state is restored.                                              |
-| `createMask(config)`              | `fabric.Object \| null` | Create a mask on the canvas. Config can include shape, width, height, color, opacity, position, style, and callbacks. |
-| `removeSelectedMask()`            | `void`                  | Remove the currently selected mask or selected masks.                                                                 |
-| `removeAllMasks(options)`         | `void`                  | Remove all masks from the canvas.                                                                                     |
-| `enterCropMode()`                 | `void`                  | Create a resizable/movable selection rectangle on top of the image.                                                   |
-| `cancelCrop()`                    | `void`                  | Cancel crop mode and remove the temporary selection rectangle.                                                        |
-| `applyCrop()`                     | `Promise<void>`         | Apply the current crop rectangle to the canvas.                                                                       |
-| `mergeMasks()`                    | `Promise<void>`         | Merge masks into the base image on the canvas.                                                                        |
-| `downloadImage(fileName)`         | `void`                  | Download the edited image as a file.                                                                                  |
-| `exportImageBase64(options)`      | `Promise<string>`       | Export an image data URL. `fileType` can be `jpeg`, `jpg`, `png`, `webp`, or a supported image MIME type.             |
-| `exportImageFile(options)`        | `Promise<File>`         | Export the current canvas as a `File` object.                                                                         |
-| `saveState()`                     | `void`                  | Save the current editor state to history. Usually called internally after supported edits.                            |
-| `loadFromState(serializedState)`  | `Promise<void>`         | Restore the editor from a serialized canvas/editor state.                                                             |
-
-Deprecated method aliases are still available for compatibility and will be removed in `v2.0.0`.
-
-| Deprecated method         | Use instead                  |
-| ------------------------- | ---------------------------- |
-| `reset()`                 | `resetImageTransform()`      |
-| `addMask(config)`         | `createMask(config)`         |
-| `merge()`                 | `mergeMasks()`               |
-| `getImageBase64(options)` | `exportImageBase64(options)` |
-
-## Mask Configuration
-
-`createMask(config)` accepts an optional configuration object.
-
-| Option             | Description                                                                                |
-| ------------------ | ------------------------------------------------------------------------------------------ |
-| `shape`            | Mask shape. Built-in values include `rect`, `circle`, `ellipse`, and `polygon`.            |
-| `width` / `height` | Mask size in pixels, percentage string, or resolver callback.                              |
-| `radius`           | Circle radius in pixels, percentage string, or resolver callback.                          |
-| `rx` / `ry`        | Ellipse radius or rectangle corner radius.                                                 |
-| `points`           | Polygon points as `{ x, y }` objects or `[x, y]` tuples.                                   |
-| `left` / `top`     | Mask position in pixels, percentage string, or resolver callback.                          |
-| `angle`            | Initial rotation angle in degrees.                                                         |
-| `color`            | Fill color.                                                                                |
-| `alpha`            | Opacity from `0` to `1`.                                                                   |
-| `selectable`       | Whether the mask can be selected.                                                          |
-| `hasControls`      | Whether Fabric transform controls are shown.                                               |
-| `styles`           | Additional Fabric style properties, such as `stroke`, `strokeWidth`, or `strokeDashArray`. |
-| `fabricGenerator`  | Factory callback for creating a custom Fabric object.                                      |
-| `onCreate`         | Callback invoked after the mask is added to the canvas.                                    |
-
-Example:
-
-```javascript
-const mask = editor.createMask({
-  shape: "rect",
-  width: 120,
-  height: 80,
-  left: 20,
-  top: 20,
-  color: "rgba(0, 0, 0, 0.5)",
-  alpha: 0.5,
-});
+```ts
+new ImageEditor(fabric: FabricModule, options?: ImageEditorOptions)
+new ImageEditor(options?: ImageEditorOptions)  // UMD: reads globalThis.fabric
 ```
 
-## Crop Behavior
-
-By default, applying crop removes unmerged masks.
-
-This is intentional: an unmerged mask is still an editable overlay object, not part of the image pixels. When `crop.preserveMasksAfterCrop` is `false`, applying crop discards unmerged masks instead of trying to keep or partially crop those overlay objects.
+### Lifecycle
 
-Choose the workflow based on the result you want:
+| Method         | Description                                                                          |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `init(idMap?)` | Bind the editor to DOM elements. Pass an `ElementIdMap`; any key may be omitted.     |
+| `dispose()`    | Tear down the editor, drain DOM bindings, and dispose the Fabric canvas. Idempotent. |
 
-- **Crop first, then add masks** when masks should be placed only on the final cropped image.
-- **Merge masks before cropping** when masks should become part of the image pixels and appear in the cropped result.
-- **Enable `crop.preserveMasksAfterCrop`** when masks should remain editable after crop. Only masks that intersect the crop area are kept and shifted into the cropped canvas.
-- **Keep the default `crop.preserveMasksAfterCrop: false`** when unmerged masks should be discarded by crop.
+### Image loading
 
-### Preserve editable masks after crop
+| Method                        | Description                                                                                                                                                     |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loadImage(base64, options?)` | Load an image from a `data:image/...` URL. Returns `Promise<void>`. Transactional: any failure restores the prior canvas, scroll, overflow, and snapshot state. |
+| `isImageLoaded()`             | Returns `true` if a valid image is currently loaded on the canvas.                                                                                              |
+| `isBusy()`                    | Returns `true` while the editor is loading, animating, or in crop mode.                                                                                         |
+| `setLayoutMode(mode)`         | Select the layout strategy for future image loads. `mode` is `'fit'`, `'cover'`, or `'expand'`.                                                                 |
 
-```javascript
-const editor = new ImageEditor({
-  crop: {
-    preserveMasksAfterCrop: true,
-  },
-});
-```
+`LoadImageOptions` currently includes `preserveScroll?: boolean` for
+preserving the container's scroll position across both successful loads and
+rollback paths.
 
-### Bake masks into the image before crop
+Use `setLayoutMode()` instead of mutating internal options when a UI lets users
+choose how the next image should be placed:
 
-```javascript
-try {
-  await editor.mergeMasks();
-  editor.enterCropMode();
-  await editor.applyCrop();
-} catch (error) {
-  console.error("Crop workflow failed:", error);
-}
+```ts
+editor.setLayoutMode('fit');
+editor.setLayoutMode('cover');
+editor.setLayoutMode('expand');
 ```
 
-## Export Examples
-
-### Export as Base64
-
-```javascript
-try {
-  const dataUrl = await editor.exportImageBase64({
-    fileType: "jpeg",
-    quality: 0.92,
-    multiplier: 1,
-  });
-
-  console.log(dataUrl);
-} catch (error) {
-  console.error("Export failed:", error);
-}
+File-input helpers accept JPG, PNG, WebP, GIF, and BMP files. GIF and BMP are
+decoded as static raster input for canvas editing; GIF animation and BMP/GIF
+source-format preservation are not retained. Export output remains controlled by
+the JPEG, PNG, or WebP export options.
+
+### Transforms
+
+| Method                  | Description                                                                                         |
+| ----------------------- | --------------------------------------------------------------------------------------------------- |
+| `scaleImage(factor)`    | Scale to `factor` (clamped to `[minScale, maxScale]`). Non-finite values are no-ops. Animated.      |
+| `rotateImage(degrees)`  | Rotate to `degrees`. Non-finite values resolve without changing canvas state. Animated.             |
+| `resetImageTransform()` | Animate to scale 1 and rotation 0. Records exactly one history entry covering the entire transform. |
+
+### Masks
+
+| Method                     | Description                                                                   |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `createMask(config?)`      | The single mask-creation entry point. Returns the new `MaskObject` or `null`. |
+| `removeSelectedMask()`     | Remove the currently selected mask and push one history entry.                |
+| `removeAllMasks(options?)` | Remove every mask. `options.saveHistory` defaults to `true`.                  |
+
+`MaskConfig` supports rect, circle, ellipse, polygon, and a custom
+`fabricGenerator`. Falsy values in `styles` (`0`, `false`, `null`, `''`,
+`NaN`) are applied verbatim.
+
+### Crop
+
+| Method            | Description                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `enterCropMode()` | Add an interactive crop rectangle on top of the image.                               |
+| `applyCrop()`     | Apply the current crop region. Atomic: failure rolls back to the pre-crop snapshot.  |
+| `cancelCrop()`    | Cancel crop mode and restore the prior canvas state without pushing a history entry. |
+
+### Merge and export
+
+| Method                        | Description                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------------------- |
+| `mergeMasks()`                | Bake masks into the base image atomically. Returns `Promise<void>`.                            |
+| `exportImageBase64(options?)` | Returns `Promise<string>` (data URL). Resolves to `''` with a warning when no image is loaded. |
+| `exportImageFile(options?)`   | Returns `Promise<File>`. Rejects when no image is loaded.                                      |
+| `downloadImage(fileName?)`    | Triggers a browser download. No-op when no image is loaded.                                    |
+
+`Base64ExportOptions` and `ImageFileExportOptions` separate mask compositing
+from export region selection:
+
+| Option       | Default   | Description                                                                 |
+| ------------ | --------- | --------------------------------------------------------------------------- |
+| `mergeMask`  | `true`    | Flatten masks into exported pixels. Mask labels are never exported.         |
+| `exportArea` | `'image'` | `'image'` clips to the image bounding box; `'canvas'` exports the canvas.   |
+| `fileType`   | `'jpeg'`  | `'png'`, `'jpeg'`, `'jpg'`, `'webp'`, or matching full MIME strings.        |
+| `format`     | `'jpeg'`  | Alias for `fileType` on `exportImageBase64`; `fileType` wins when both set. |
+| `quality`    | `0.92`    | Lossy quality clamped to `[0, 1]`; ignored for PNG.                         |
+| `multiplier` | `1`       | Output resolution multiplier.                                               |
+| `fileName`   | option    | `ImageFileExportOptions` only. Defaults to `defaultDownloadFileName`.       |
+
+```ts
+await editor.exportImageBase64({ exportArea: 'image', mergeMask: true });
+await editor.exportImageBase64({ exportArea: 'image', mergeMask: false });
+await editor.exportImageBase64({ exportArea: 'canvas', mergeMask: true });
+await editor.exportImageBase64({ exportArea: 'canvas', mergeMask: false });
 ```
 
-### Export as File
-
-```javascript
-try {
-  const file = await editor.exportImageFile({
-    fileName: "edited_image.jpg",
-    fileType: "jpeg",
-    quality: 0.92,
-    mergeMask: true,
-  });
-
-  console.log(file);
-} catch (error) {
-  console.error("File export failed:", error);
-}
-```
-
-## Error Handling
-
-Some ImageEditor API methods may throw synchronously or reject their returned Promise when the operation cannot be completed.
-
-Recommended usage:
+### State and history
+
+| Method                    | Description                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| `saveState()`             | Capture a snapshot of the canvas plus editor metadata into the history stack.         |
+| `loadFromState(snapshot)` | Restore canvas, masks, and editor metadata from a snapshot. Returns `Promise<void>`.  |
+| `undo()`                  | Undo the last state change. Routed through the animation queue. No-op while disposed. |
+| `redo()`                  | Redo the next state change. Routed through the animation queue. No-op while disposed. |
+
+## Configuration options
+
+Pass an `ImageEditorOptions` object as the second constructor argument
+(or as the only argument when using the UMD global form). Unknown keys are
+ignored; nested `label` and `crop` objects are deep-merged with the defaults.
+
+| Option                    | Default              | Description                                                                                                                                                                                                                                                                    |
+| ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `canvasWidth`             | `800`                | Initial and hidden-container fallback canvas width in pixels.                                                                                                                                                                                                                  |
+| `canvasHeight`            | `600`                | Initial and hidden-container fallback canvas height in pixels.                                                                                                                                                                                                                 |
+| `backgroundColor`         | `'transparent'`      | Fabric canvas background color.                                                                                                                                                                                                                                                |
+| `animationDuration`       | `300`                | Duration of scale and rotate animations (ms).                                                                                                                                                                                                                                  |
+| `minScale`                | `0.1`                | Minimum scale factor.                                                                                                                                                                                                                                                          |
+| `maxScale`                | `5.0`                | Maximum scale factor.                                                                                                                                                                                                                                                          |
+| `scaleStep`               | `0.05`               | Scale delta per zoom step.                                                                                                                                                                                                                                                     |
+| `rotationStep`            | `90`                 | Rotation step in degrees.                                                                                                                                                                                                                                                      |
+| `expandCanvasToImage`     | `true`               | Grow the canvas to fit the loaded image (lowest layout precedence).                                                                                                                                                                                                            |
+| `fitImageToCanvas`        | `false`              | Fit the image inside the visible workspace viewport (highest layout precedence).                                                                                                                                                                                               |
+| `coverImageToCanvas`      | `false`              | Scale large images down to cover the visible workspace, cap at native size, and expand overflowing canvas axes so the container can scroll.                                                                                                                                    |
+| `downsampleOnLoad`        | `true`               | Downsample large images on load.                                                                                                                                                                                                                                               |
+| `downsampleMaxWidth`      | `4000`               | Max width before downsampling kicks in.                                                                                                                                                                                                                                        |
+| `downsampleMaxHeight`     | `3000`               | Max height before downsampling kicks in.                                                                                                                                                                                                                                       |
+| `downsampleQuality`       | `0.92`               | Lossy quality used when downsampling and exporting.                                                                                                                                                                                                                            |
+| `preserveSourceFormat`    | `true`               | Preserve PNG/WebP MIME through downsampling unless `downsampleMimeType` is set.                                                                                                                                                                                                |
+| `downsampleMimeType`      | `null`               | Explicit downsample MIME type. Overrides `preserveSourceFormat`.                                                                                                                                                                                                               |
+| `imageLoadTimeoutMs`      | `30000`              | Maximum duration for both decode and Fabric image creation during `loadImage`.                                                                                                                                                                                                 |
+| `exportMultiplier`        | `1`                  | Output resolution multiplier.                                                                                                                                                                                                                                                  |
+| `maxExportPixels`         | `50000000`           | Maximum output pixel count after applying the export multiplier. Invalid values fall back to this default.                                                                                                                                                                     |
+| `maxHistorySize`          | `50`                 | Maximum undo-history entries. Snapshots may include full image data URLs, so large images can duplicate memory across history entries. Lower this for memory-constrained pages.                                                                                                |
+| `exportAreaByDefault`     | `'image'`            | Default export region for `exportImageBase64`, `exportImageFile`, and `downloadImage`.                                                                                                                                                                                         |
+| `mergeMaskByDefault`      | `true`               | Default mask compositing behavior for `exportImageBase64`, `exportImageFile`, and `downloadImage`.                                                                                                                                                                             |
+| `defaultMaskWidth`        | `50`                 | Default mask width.                                                                                                                                                                                                                                                            |
+| `defaultMaskHeight`       | `80`                 | Default mask height.                                                                                                                                                                                                                                                           |
+| `maskRotatable`           | `false`              | Allow masks to be rotated by the user.                                                                                                                                                                                                                                         |
+| `maskLabelOnSelect`       | `true`               | Show a label above a selected mask.                                                                                                                                                                                                                                            |
+| `maskLabelOffset`         | `3`                  | Pixel offset of the label from the mask's top-left corner.                                                                                                                                                                                                                     |
+| `maskName`                | `'mask'`             | Prefix used for auto-generated mask names.                                                                                                                                                                                                                                     |
+| `groupSelection`          | `false`              | Allow Fabric multi-object group selection on the canvas.                                                                                                                                                                                                                       |
+| `showPlaceholder`         | `true`               | Show a placeholder element while no image is loaded.                                                                                                                                                                                                                           |
+| `initialImageBase64`      | `null`               | Base64 data URL auto-loaded after construction.                                                                                                                                                                                                                                |
+| `defaultDownloadFileName` | `'edited_image.jpg'` | Default file name used by `downloadImage()`.                                                                                                                                                                                                                                   |
+| `onImageLoadStart`        | `null`               | Called before a valid image load begins.                                                                                                                                                                                                                                       |
+| `onImageLoaded`           | `null`               | Called as `(info, context)` once after a successful `loadImage`. Extra arguments are ignored by existing zero-argument JavaScript handlers.                                                                                                                                    |
+| `onImageCleared`          | `null`               | Called when a committed image is replaced or cleared.                                                                                                                                                                                                                          |
+| `onImageChanged`          | `null`               | Called with a safe editor state snapshot after visible editor state changes.                                                                                                                                                                                                   |
+| `onBusyChange`            | `null`               | Called only when the public busy state changes.                                                                                                                                                                                                                                |
+| `onEditorDisposed`        | `null`               | Called once when `dispose()` performs teardown.                                                                                                                                                                                                                                |
+| `onMasksChanged`          | `null`               | Called with a shallow copy of current mask objects after the mask collection changes.                                                                                                                                                                                          |
+| `onSelectionChange`       | `null`               | Called with selected mask payload after mask selection changes.                                                                                                                                                                                                                |
+| `onError`                 | `null`               | Called as `(error, message)` when the editor reports an error.                                                                                                                                                                                                                 |
+| `onWarning`               | `null`               | Called as `(error, message)` when the editor reports a recoverable warning.                                                                                                                                                                                                    |
+| `label`                   | see source           | `LabelConfig` for selected-mask labels (`getText`, `textOptions`, `create`).                                                                                                                                                                                                   |
+| `crop`                    | see source           | `CropConfig` (`minWidth`, `minHeight`, `padding`, `hideMasksDuringCrop`, `preserveMasksAfterCrop`, `allowRotationOfCropRect`, `exportFileType`, `exportQuality`). `applyCrop()` preserves the current image format by default (`'source'`) and falls back to PNG when unknown. |
+
+`crop.exportFileType` defaults to `'source'`. Supported explicit values are
+`'png'`, `'jpeg'`, `'jpg'`, `'webp'`, and full image MIME strings. PNG is
+lossless and ignores `crop.exportQuality`; JPEG/WebP use `crop.exportQuality`
+when finite, otherwise `downsampleQuality`, otherwise `0.92`. Choose JPEG/WebP
+only when smaller intermediate crop output is preferred.
+
+## Example workflow
+
+1. Construct `ImageEditor` with options and call `init(idMap)` to wire it up.
+2. Load an image via `loadImage(base64)` or the bound file input.
+3. Adjust with `scaleImage`, `rotateImage`, `resetImageTransform`, and the
+   crop session.
+4. Add `createMask` calls and inspect via the `maskList` element.
+5. Use `mergeMasks` to bake masks into the image, then
+   `exportImageBase64`, `exportImageFile`, or `downloadImage` to produce
+   the final output.
+6. Call `dispose()` when the editor is unmounted.
+
+## Building from source
 
-- Wrap initialization and manual API calls in `try...catch`.
-- Always `await` Promise-based methods such as `loadImage()`, `scaleImage()`, `rotateImage()`, `resetImageTransform()`, `mergeMasks()`, `applyCrop()`, `undo()`, `redo()`, `exportImageBase64()`, `exportImageFile()`, and `loadFromState()`.
-- Use `onError` and `onWarning` for centralized logging or UI notifications.
-- Do not rely only on `onError`; manual API calls should still handle thrown errors or rejected Promises at the call site.
-- Check `editor.isBusy()` before starting user-triggered operations when needed, especially before loading, cropping, rotating, scaling, merging, undoing, redoing, or exporting.
-- Show user-friendly messages in your application instead of exposing raw error text directly.
-
-Example:
-
-```javascript
-const editor = new ImageEditor({
-  onError: (error, message) => {
-    console.error("[ImageEditor]", message, error);
-    showEditorMessage("The image editor could not complete the operation.");
-  },
-
-  onWarning: (error, message) => {
-    console.warn("[ImageEditor]", message, error);
-  },
-});
-
-async function rotateSafely(degrees) {
-  if (editor.isBusy()) {
-    return;
-  }
-
-  try {
-    await editor.rotateImage(degrees);
-  } catch (error) {
-    console.error("Rotate failed:", error);
-    showEditorMessage("Rotation failed. Please try again.");
-  }
-}
-
-function showEditorMessage(message) {
-  // Replace this with your own toast, alert, or inline message UI.
-  console.log(message);
-}
+```bash
+npm install
+npm run build
 ```
 
-### Common Failure Cases
-
-Common failure cases include:
-
-- fabric.js is not loaded before creating or initializing the editor.
-- The configured canvas element cannot be found.
-- The image data URL is invalid, unsupported, too large, or times out while loading.
-- Another operation is already running, such as image loading, animation, crop, undo, redo, merge, or export.
-- The editor has been disposed before the operation completes.
-- The browser cannot create a canvas export because of platform, memory, or security restrictions.
-- A custom `fabricGenerator`, label callback, or external event handler throws an error.
+`npm run build` runs `clean → build:esm → build:cjs → build:types →
+build:umd` in order, emitting:
 
-## Example Workflow
+- `dist/esm/index.js` (and the rest of the decomposed source tree)
+- `dist/cjs/index.cjs`
+- `dist/types/index.d.ts`
+- `dist/umd/image-editor.umd.js`
 
-The recommended order depends on whether masks should remain editable, be baked into the image, or be discarded.
+`npm test` runs the Node-based unit and property tests under `tests/`.
 
-### Common workflow: crop first, then add masks
-
-Use this flow when masks are only needed on the final cropped image.
-
-1. **Load an image** - Via file input or base64 data URL.
-2. **Adjust positioning** - Zoom in/out, rotate, or reset as needed.
-3. **Crop** - Optionally crop the image area.
-4. **Add masks** - Highlight or cover specific areas on the cropped image.
-5. **Merge result** - Flatten masks into the base image when needed.
-6. **Download / export** - Save the final image.
-
-### Alternative workflow: add masks before crop
-
-If masks are added before crop, choose one of these behaviors before applying crop:
-
-- Call `mergeMasks()` before `applyCrop()` if masks should become part of the cropped image pixels.
-- Set `crop.preserveMasksAfterCrop: true` if masks should stay editable after crop.
-- Keep the default `crop.preserveMasksAfterCrop: false` if unmerged masks should be removed by crop.
-
-Example:
-
-```javascript
-// Masks become part of the image pixels before crop.
-await editor.mergeMasks();
-editor.enterCropMode();
-await editor.applyCrop();
-```
-
-## Local Build
+For the full local release gate, run:
 
 ```bash
+npm run format:check
+npm run lint
+npm run typecheck
+npm test
 npm run build
+npm run package:check
+npm audit --audit-level=high
+npm pack --dry-run
 ```
 
-## Tests
-
-```bash
-npm test
-```
+`npm run ci` combines format, lint, typecheck, tests, build, and package
+linting. The test suite also supports a clean checkout where `dist/` has not
+been built yet; integration helpers use source modules until build artifacts
+exist, while partial `dist/` trees still fail the artifact checks.
 
-## Browser Support
+## Browser support
 
 - Chrome 100+
 - Firefox 100+
 - Safari 15+
 - Edge 100+
 
-The package build targets these modern browsers and uses modern DOM and JavaScript features.
-
-IE11 and old mobile Safari are not supported by the distributed build. If you need them, transpile the package and provide any required DOM or JavaScript polyfills in your application.
-
-## Dependencies
-
-- **fabric.js v5.x** — Must be loaded before ImageEditor.
+The library uses modern DOM and ES2022 features (optional chaining, classes,
+`async`/`await`, native promises). Older targets must be transpiled by the
+consumer.
+
+## Type declarations
+
+Public types are re-exported from the package root:
+
+```ts
+import type {
+    ImageEditorOptions,
+    ResolvedOptions,
+    LabelConfig,
+    CropConfig,
+    LoadImageOptions,
+    RemoveAllMasksOptions,
+    MaskConfig,
+    MaskObject,
+    MaskNumericProp,
+    ResolvedMaskConfig,
+    ImageMimeType,
+    ImageFileType,
+    NormalizedImageFormat,
+    ExportArea,
+    CropExportFileType,
+    Base64ExportOptions,
+    ImageFileExportOptions,
+    ImageInfo,
+    ImageEditorState,
+    ImageEditorSelection,
+    ImageEditorCallbackContext,
+    ImageEditorOperation,
+    ElementIdMap,
+    FabricModule,
+} from '@bensitu/image-editor';
+```
 
 ## License
 
-MIT © 2026 Ben Situ
+MIT © Ben Situ.
 
-Fabric.js is licensed under its own MIT license.
+Fabric.js is distributed under its own MIT license.