@bensitu/image-editor 1.5.1 → 2.0.0

package/dist/types/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,eAAe,WAAW,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAItD,YAAY,EAER,kBAAkB,EAClB,eAAe,EACf,UAAU,EAEV,WAAW,EACX,UAAU,EACV,kBAAkB,EAElB,gBAAgB,EAChB,qBAAqB,EAErB,UAAU,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAElB,aAAa,EACb,aAAa,EACb,qBAAqB,EAErB,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EAEtB,SAAS,EACT,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EAEpB,YAAY,EAEZ,YAAY,GACf,MAAM,wBAAwB,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical public API barrel for the image-editor library.
+ *
+ * The package surface consists of:
+ * - `ImageEditor` (default and named export) — the only public class.
+ * - `isMaskObject` — runtime type guard for mask objects.
+ * - The documented public types listed below.
+ *
+ * Internal helpers (animation queue, command, history manager, controllers,
+ * services, managers, and utility modules) are intentionally not re-exported;
+ * they are implementation details and may change without notice.
+ *
+ * @example
+ * ```ts
+ * import * as fabric from 'fabric';
+ * import { ImageEditor } from '@bensitu/image-editor';
+ * import type {
+ *     ImageEditorOptions,
+ *     MaskConfig,
+ *     MaskObject,
+ * } from '@bensitu/image-editor';
+ * ```
+ *
+ * @module
+ */
+import { ImageEditor } from './image-editor.js';
+export { ImageEditor };
+export default ImageEditor;
+export { isMaskObject } from './core/public-types.js';
+export type { ImageEditorOptions, ResolvedOptions, LayoutMode, LabelConfig, CropConfig, CropExportFileType, LoadImageOptions, RemoveAllMasksOptions, MaskConfig, MaskObject, MaskNumericProp, ResolvedMaskConfig, ImageMimeType, ImageFileType, NormalizedImageFormat, ExportArea, Base64ExportOptions, ImageFileExportOptions, ImageInfo, ImageEditorState, ImageEditorSelection, ImageEditorCallbackContext, ImageEditorOperation, ElementIdMap, FabricModule, } from './core/public-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,eAAe,WAAW,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAItD,YAAY,EAER,kBAAkB,EAClB,eAAe,EACf,UAAU,EAEV,WAAW,EACX,UAAU,EACV,kBAAkB,EAElB,gBAAgB,EAChB,qBAAqB,EAErB,UAAU,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAElB,aAAa,EACb,aAAa,EACb,qBAAqB,EAErB,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EAEtB,SAAS,EACT,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EAEpB,YAAY,EAEZ,YAAY,GACf,MAAM,wBAAwB,CAAC"}

package/dist/types/mask/mask-factory.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Function-based mask creation entry point used by the
+ * `ImageEditor` orchestrator.
+ *
+ * ## Owned contracts
+ *
+ * - On a successful `createMask`, the editor SHALL
+ *   increment `maskCounter` and assign the result to `mask.maskId`. Counter
+ *   bookkeeping flows through `context.getMaskCounter` / `context.setMaskCounter` so
+ *   the orchestrator retains ownership of the field across loadImage and
+ *   loadFromState (which reset / restore the counter).
+ * - Together with `core/state-serializer.ts`, mask IDs
+ *   stay unique across mixed `createMask` / `mergeMasks` / `undo` / `redo`
+ *   sequences because the counter is monotonic.
+ * - `createMask` is the public mask-creation entry point.
+ * - For `'rect' | 'circle' | 'ellipse' | 'polygon'`
+ *   the corresponding Fabric shape is built with explicit
+ *   `originX: 'left'`, `originY: 'top'`, plus the resolved color, opacity,
+ *   angle, and the user's `styles` block.
+ * - When `config.fabricGenerator` is supplied it is
+ *   called with `(resolvedConfig, canvas, options)` and its return value is
+ *   used verbatim as the mask object.
+ * - Post-create order is fixed: add to canvas →
+ *   update list DOM → `setActiveObject` (when `selectable !== false`) →
+ *   `saveState` → `config.onCreate(mask, canvas)`.
+ * - `config.onCreate` is invoked exactly once,
+ *   strictly after `saveState` has run.
+ * - Falsy values supplied via `config.styles` (`0`,
+ *   `false`, `null`, `''`, `NaN`) are applied verbatim. The factory does
+ *   NOT use `??` to default stroke / strokeWidth / strokeDashArray when the
+ *   key is explicitly present on `styles`.
+ * - `hasControls`, `selectable`, `transparentCorners`,
+ *   `strokeUniform` use the `'foo' in config ? … : default` pattern so that
+ *   an explicit `false` is preserved.
+ * - When a polygon mask is built, its visible
+ *   bounding-box top-left SHALL equal the resolved `(left, top)`. Fabric
+ *   v7's `Polygon` constructor positions the object so the polygon's
+ *   `pathOffset` is centered on `(left, top)`, which means the bounding
+ *   rect generally does NOT land at `(left, top)`. The factory therefore
+ *   constructs the polygon without `left`/`top`, reads the resulting
+ *   bounding rect, and shifts the object by the delta so the rendered
+ *   bounding box top-left matches the requested coordinate.
+ * - Polygon points may be supplied as `{ x, y }`
+ *   objects or `[x, y]` tuples; both forms are normalized via
+ *   `coercePoint` from `utils/number.ts` before reaching Fabric.
+ *
+ * - `removeAllMasks(options?)` accepts a
+ *   `RemoveAllMasksOptions` argument with `saveHistory` defaulting to
+ *   `true`, pushing a single history entry for the batch.
+ * - `removeAllMasks({ saveHistory: false})` removes
+ *   masks without pushing a history entry (used by merge/crop pipelines).
+ * - `removeAllMasks` is operation-guard-rejected
+ *   while `isAnimating` is `true`. The guard lives on the orchestrator;
+ *   this module is only invoked after the guard has cleared.
+ * - `removeAllMasks` clears `lastMask` to `null`,
+ *   so subsequent `createMask` calls cannot auto-place relative to a
+ *   removed reference and `maskId` uniqueness is preserved across mixed
+ *   `createMask` / `removeAllMasks` / `undo` / `redo` sequences.
+ *
+ * ## Out of scope (handled by sibling tasks)
+ *
+ * - Mask label creation/synchronization — see `mask/mask-label-manager.ts`.
+ *
+ * ## Design notes
+ *
+ * - The orchestrator owns the editor-level state (`maskCounter`,
+ *   `lastMask`, the canvas, `saveState`, `updateMaskList`). The factory
+ *   reads/writes those slots through getter/setter callbacks supplied in
+ *   {@link CreateMaskContext} so this module is independent of the
+ *   `ImageEditor` class shape.
+ * - `expandCanvasIfNeeded` is optional. The orchestrator may supply it to
+ *   route through `setCanvasSizePx` (which forces a synchronous reflow on
+ *   the scroll container, see `image-editor.ts`). When absent, the factory
+ *   falls back to the public Fabric API `canvas.setDimensions`.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+import type { FabricModule, MaskConfig, MaskObject, RemoveAllMasksOptions, ResolvedOptions } from '../core/public-types.js';
+/**
+ * State and orchestration callbacks the mask factory needs from the
+ * `ImageEditor` orchestrator.
+ *
+ * The factory does NOT own any of these slots — it only reads and updates
+ * them through the supplied accessors so ownership of `maskCounter`,
+ * `lastMask`, history snapshots, and the mask list DOM stays on the editor.
+ */
+export interface CreateMaskContext {
+    /** Injected Fabric.js v7 module used to construct the shape. */
+    fabric: FabricModule;
+    /** The live Fabric canvas the mask is added to. */
+    canvas: FabricNS.Canvas;
+    /** Fully resolved editor options (defaults already merged). */
+    options: ResolvedOptions;
+    /** Last mask reference, used for the auto-place-to-right behavior. */
+    getLastMask(): MaskObject | null;
+    setLastMask(mask: MaskObject | null): void;
+    /** Mask counter — owned by the orchestrator. */
+    getMaskCounter(): number;
+    setMaskCounter(n: number): void;
+    /** Re-render the mask list DOM (UI ownership lives in `mask/mask-list.ts`). */
+    updateMaskList(): void;
+    /** Save canvas state to history. */
+    saveCanvasState(): void;
+    /**
+     * Optional canvas resize hook used when `options.expandCanvasToImage` is
+     * `true` and the placed mask would extend past the current canvas size.
+     * If omitted, the factory calls `canvas.setDimensions` directly. The
+     * orchestrator typically passes `setCanvasSizePx` here so the scroll
+     * container reflows synchronously with the new canvas size.
+     */
+    expandCanvasIfNeeded?: (width: number, height: number) => void;
+}
+/**
+ * Create a mask via the resolved {@link MaskConfig} and add it to the
+ * canvas.
+ *
+ * Creation steps:
+ *
+ * 1. Resolve the config: apply defaults, then resolve placement
+ *    (`left`/`top`) and dimensions (`width`/`height`/`rx`/`ry`/`radius`)
+ *    via {@link resolveNumeric} so percentages and factory functions
+ *    collapse to pixel numbers before Fabric shape construction.
+ * 2. Optionally expand the canvas if the placement would overflow.
+ * 3. Build the Fabric shape — switch on `config.shape`, or call
+ *    `config.fabricGenerator` if provided.
+ * 4. Apply common mask properties. Falsy flags (`hasControls`,
+ *    `selectable`, `transparentCorners`, `strokeUniform`) use the
+ *    `'foo' in config ? … : default` pattern so an explicit `false` is
+ *    preserved. Stroke / strokeWidth /
+ *    strokeDashArray pulled out of `styles` use the same `in` check so
+ *    `null` and `0` are preserved verbatim.
+ * 5. Increment `maskCounter` and assign `maskId`, `maskName`,
+ *    `originalAlpha`.
+ * 6. Post-create order: add to canvas → `updateMaskList` →
+ *    `setActiveObject` (when `selectable !== false`) → `saveCanvasState`
+ *    → `config.onCreate(mask, canvas)`.
+ *
+ * @param context - Orchestration context — see {@link CreateMaskContext}.
+ * @param config - User-supplied mask configuration.
+ * @returns      The created mask object, or `null` if the canvas is unset.
+ */
+export declare function createMask(context: CreateMaskContext, config?: MaskConfig): MaskObject | null;
+/**
+ * Orchestration callbacks needed by {@link removeSelectedMask} and
+ * {@link removeAllMasks}. The helpers do NOT own any of these slots — they
+ * read and update them through the supplied accessors so ownership of the
+ * canvas, mask label DOM, mask list DOM, history, and `lastMask` stays on
+ * the editor.
+ */
+export interface RemoveMaskContext {
+    /** The live Fabric canvas the mask(s) are removed from. */
+    canvas: FabricNS.Canvas;
+    /**
+     * Remove the label overlay associated with `mask` (if any). The
+     * orchestrator typically delegates to `mask/mask-label-manager.ts`.
+     */
+    removeLabelForMask(mask: MaskObject): void;
+    /** Re-render the mask list DOM (UI ownership in `mask/mask-list.ts`). */
+    updateMaskList(): void;
+    /** Push a single history entry for the removal batch. */
+    saveCanvasState(): void;
+    /**
+     * Reset the orchestrator's `lastMask` reference. Called with `null`
+     * when every mask is removed so the next `createMask` does not
+     * auto-place relative to a removed mask.
+     */
+    setLastMask(mask: MaskObject | null): void;
+}
+/**
+ * Remove the currently selected mask (if it is a {@link MaskObject}).
+ *
+ * Steps:
+ *
+ * 1. Read the active object from the canvas. No-op if missing or not a mask.
+ * 2. Remove the mask's label overlay via {@link RemoveMaskContext.removeLabelForMask}.
+ * 3. Remove the mask object from the canvas and clear the active selection.
+ * 4. Re-render the mask list DOM and the canvas.
+ * 5. Push a single history entry via {@link RemoveMaskContext.saveCanvasState}.
+ *
+ * @param context - Orchestration context — see {@link RemoveMaskContext}.
+ */
+export declare function removeSelectedMask(context: RemoveMaskContext): void;
+/**
+ * Remove all masks (and their label overlays) from the canvas.
+ *
+ * When `options.saveHistory` is `false`, the helper does NOT push a history
+ * entry — used by the internal `mergeMasks` and `applyCrop` pipelines, which
+ * already record one enclosing history entry for the operation. The default
+ * (and the public-facing call from `ImageEditor.removeAllMasks`) is
+ * `saveHistory: true`, which pushes a single entry for the batch.
+ *
+ * Steps:
+ *
+ * 1. Collect every {@link MaskObject} on the canvas. No-op if none.
+ * 2. For each mask: remove its label overlay, then remove the mask object
+ *    from the canvas.
+ * 3. Clear the active selection.
+ * 4. Reset `lastMask` to `null` so the next `createMask` does not
+ *    auto-place relative to a removed reference.
+ * 5. Re-render the mask list DOM and the canvas.
+ * 6. Conditionally push a history entry depending on
+ *    `options.saveHistory`.
+ *
+ * @param context - Orchestration context — see {@link RemoveMaskContext}.
+ * @param options - Bulk-removal options. Defaults to `{ saveHistory: true}`.
+ */
+export declare function removeAllMasks(context: RemoveMaskContext, options?: RemoveAllMasksOptions): void;
+//# sourceMappingURL=mask-factory.d.ts.map

package/dist/types/mask/mask-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask-factory.d.ts","sourceRoot":"","sources":["../../../src/mask/mask-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EACR,YAAY,EACZ,UAAU,EACV,UAAU,EACV,qBAAqB,EAErB,eAAe,EAClB,MAAM,yBAAyB,CAAC;AAcjC;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAC9B,gEAAgE;IAChE,MAAM,EAAE,YAAY,CAAC;IACrB,mDAAmD;IACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;IACxB,+DAA+D;IAC/D,OAAO,EAAE,eAAe,CAAC;IACzB,sEAAsE;IACtE,WAAW,IAAI,UAAU,GAAG,IAAI,CAAC;IACjC,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC;IAC3C,gDAAgD;IAChD,cAAc,IAAI,MAAM,CAAC;IACzB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,+EAA+E;IAC/E,cAAc,IAAI,IAAI,CAAC;IACvB,oCAAoC;IACpC,eAAe,IAAI,IAAI,CAAC;IACxB;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE;AA+GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,GAAE,UAAe,GAAG,UAAU,GAAG,IAAI,CAsSjG;AA6BD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC9B,2DAA2D;IAC3D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;IACxB;;;OAGG;IACH,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3C,yEAAyE;IACzE,cAAc,IAAI,IAAI,CAAC;IACvB,yDAAyD;IACzD,eAAe,IAAI,IAAI,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAYnE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,qBAA0B,GACpC,IAAI,CAqBN"}

package/dist/types/mask/mask-label-manager.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Per-mask label overlay creation, positioning, show/hide, and
+ * removal. Owns the legacy `createLabelForMask`, `syncMaskLabel`,
+ * `showLabelForMask`, `hideAllMaskLabels`, and
+ * `removeLabelForMask` logic that was inlined on the editor
+ * in legacy and is now extracted into pure(ish) helpers that take a
+ * {@link MaskLabelManagerContext}.
+ *
+ * ## Owned contracts
+ *
+ * - Label text is computed via
+ *   `options.label.getText(mask, mask.maskId - 1)`. The index argument is
+ *   the stable creation index (`maskId - 1`), NOT the live canvas list
+ *   position. legacy passed `this.maskCounter` here, which drifted whenever
+ *   masks were added or removed; the current contract pins the index to the
+ *   mask's own identity so labels stay consistent across
+ *   `createMask` / `removeSelectedMask` / `removeAllMasks` / `undo`/`redo`.
+ *
+ * - Every label-overlay text object SHALL be
+ *   constructed with `originX: 'left'`, `originY: 'top'`, since the label
+ *   is positioned by its top-left corner. The defaults injected by this
+ *   module set those origins explicitly, and {@link syncMaskLabel}
+ *   re-asserts them on every sync so an externally-mutated label still
+ *   honors the contract.
+ *
+ * - **Pretty_Printer filter** — Every label object is
+ *   tagged with `maskLabel = true` so `core/state-serializer.ts` can
+ *   exclude it from history snapshots. Labels are session-only and never
+ *   persisted.
+ *
+ * ## Out of scope (handled by sibling modules)
+ *
+ * - Mask creation, falsy-style preservation, polygon placement — see
+ *   `mask/mask-factory.ts`.
+ * - Mask list DOM rendering — see `mask/mask-list.ts`.
+ * - Hover/selection appearance — see `mask/mask-style.ts`.
+ *
+ * ## Implementation notes
+ *
+ * - The orchestrator (`src/image-editor.ts`) owns the canvas reference,
+ *   resolved options, and Fabric module. The helpers in this module
+ *   receive those slots through a {@link MaskLabelManagerContext} so the
+ *   module is independent of the `ImageEditor` class shape and can be unit
+ *   tested in isolation against a stub Fabric environment.
+ * - When `options.label.create` is supplied, the user owns the full label
+ *   build (it may even return `null` to opt out for a particular mask).
+ *   When the factory returns `null` or the option is absent, this module
+ *   falls back to a default Fabric text constructed from the deep-merged
+ *   `options.label.textOptions`. The default already carries
+ *   `originX: 'left'`/`originY: 'top'` via `core/default-options.ts`, but
+ *   we set them explicitly here as well so the contract holds even when a
+ *   caller bypasses `resolveOptions` (e.g. in unit tests).
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+import type { FabricModule, MaskObject, ResolvedOptions } from '../core/public-types.js';
+/**
+ * State the label helpers read from the `ImageEditor` orchestrator.
+ *
+ * The module does NOT own any of these slots — it only reads them so
+ * ownership of the canvas, Fabric module, and resolved options stays on the
+ * orchestrator (where legacy left them).
+ */
+export interface MaskLabelManagerContext {
+    /** Injected Fabric.js v7 module used to construct the label text. */
+    fabric: FabricModule;
+    /** The live Fabric canvas the label overlay is added to. */
+    canvas: FabricNS.Canvas;
+    /** Fully resolved editor options (defaults already merged). */
+    options: ResolvedOptions;
+}
+/**
+ * Remove the label overlay associated with `mask` (if any).
+ *
+ * No-op when the canvas is unset or the mask has no `labelObject`. Each
+ * removal step is wrapped in `try/catch` so a stale Fabric reference does
+ * not break callers that iterate every mask (e.g. {@link hideAllMaskLabels}
+ * or `removeAllMasks`).
+ *
+ * Steps:
+ *
+ * 1. If `mask.labelObject` is present and still on the canvas, remove it.
+ * 2. Delete `mask.labelObject` so subsequent {@link showLabelForMask} calls
+ *    rebuild it instead of reusing a stale reference.
+ *
+ * @param context - Orchestration context — see {@link MaskLabelManagerContext}.
+ * @param mask - The mask whose label overlay should be removed.
+ */
+export declare function removeLabelForMask(context: MaskLabelManagerContext, mask: MaskObject): void;
+/**
+ * Create (or recreate) the label overlay for `mask`.
+ *
+ * No-op when the canvas is unset or `options.maskLabelOnSelect` is `false`.
+ *
+ * Steps:
+ *
+ * 1. Remove any existing label so a stale reference is never reused.
+ * 2. If `options.label.create` is a function, call it with
+ *    `(mask, fabric)` and use its return value when truthy. The factory
+ *    may return `null` to opt out, in which case the default builder runs.
+ * 3. Otherwise (or when the factory returned `null`), compute label text
+ *    via `options.label.getText(mask, mask.maskId - 1)` so the index is
+ *    the stable creation index rather than the live list position. Build
+ *    a Fabric text using `options.label.textOptions` with `originX: 'left'`
+ *    and `originY: 'top'` re-asserted explicitly.
+ * 4. Tag the resulting object with `maskLabel = true` so the state
+ *    serializer filters it out of history snapshots.
+ * 5. Attach the label to the mask, add it to the canvas, bring it to the
+ *    front, and run an initial {@link syncMaskLabel} to position it.
+ *
+ * @param context - Orchestration context — see {@link MaskLabelManagerContext}.
+ * @param mask - The mask the label overlay is being created for.
+ */
+export declare function createLabelForMask(context: MaskLabelManagerContext, mask: MaskObject): void;
+/**
+ * Re-position the label overlay to track its mask's current bounding box,
+ * angle, and visibility.
+ *
+ * No-op when the canvas is unset, `options.maskLabelOnSelect` is `false`,
+ * or the mask has no `labelObject`. Designed to be called from Fabric event
+ * handlers (`object:moving`, `object:scaling`, `object:rotating`,
+ * `object:modified`) without checking those guards at every call site.
+ *
+ * Geometry (matches legacy):
+ *
+ * - The label's top-left is placed `options.maskLabelOffset` pixels from
+ *   the mask's top-left corner, along the vector from the top-left to the
+ *   center of the rotated bounding box. This keeps the offset visually
+ *   consistent regardless of mask rotation.
+ * - The label inherits the mask's `angle` so it rotates with the mask.
+ * - `originX: 'left'` and `originY: 'top'` are re-asserted on every sync
+ *   to.
+ *
+ * @param context - Orchestration context — see {@link MaskLabelManagerContext}.
+ * @param mask - The mask whose label should be repositioned.
+ */
+export declare function syncMaskLabel(context: MaskLabelManagerContext, mask: MaskObject): void;
+/**
+ * Ensure the label for `mask` is present and visible.
+ *
+ * No-op when `options.maskLabelOnSelect` is `false`. Creates a fresh label
+ * via {@link createLabelForMask} when the mask has none, otherwise toggles
+ * `visible` to `true` and re-syncs the position. Used by the orchestrator's
+ * selection handler when a single mask becomes the active object.
+ *
+ * @param context - Orchestration context — see {@link MaskLabelManagerContext}.
+ * @param mask - The mask whose label should be shown.
+ */
+export declare function showLabelForMask(context: MaskLabelManagerContext, mask: MaskObject): void;
+/**
+ * Remove every label overlay currently on the canvas and detach the
+ * `labelObject` reference from every mask.
+ *
+ * Called by the orchestrator before serialization (`saveState`) and
+ * after `loadFromJSON`-driven restores so that label objects — which
+ * Fabric DOES serialize unless filtered — never leak into history.
+ *
+ * Steps:
+ *
+ * 1. Remove every object flagged with `maskLabel === true` from the
+ *    canvas. Each removal is wrapped in `try/catch` so a stale Fabric
+ *    reference does not break the loop.
+ * 2. Delete `labelObject` from every mask object so a subsequent
+ *    {@link showLabelForMask} rebuilds the label rather than reusing a
+ *    detached reference.
+ *
+ * @param context - Orchestration context — see {@link MaskLabelManagerContext}.
+ */
+export declare function hideAllMaskLabels(context: MaskLabelManagerContext): void;
+//# sourceMappingURL=mask-label-manager.d.ts.map

package/dist/types/mask/mask-label-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask-label-manager.d.ts","sourceRoot":"","sources":["../../../src/mask/mask-label-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAIzF;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACpC,qEAAqE;IACrE,MAAM,EAAE,YAAY,CAAC;IACrB,4DAA4D;IAC5D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;IACxB,+DAA+D;IAC/D,OAAO,EAAE,eAAe,CAAC;CAC5B;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAc3F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAgE3F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CA2BtF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CASzF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAuBxE"}

package/dist/types/mask/mask-list.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Mask list DOM rendering — owns the legacy `updateMaskList` and
+ * `_handleMaskListClick` logic that was inlined on the editor in
+ * legacy and is now extracted into pure(ish) helpers that take a
+ * {@link MaskListContext}.
+ *
+ * ## Owned contracts
+ *
+ * - When the mask list DOM container is bound,
+ *   {@link renderMaskList} renders exactly one `<li>` per mask currently on
+ *   the canvas, in canvas object order. The list is rebuilt from scratch on
+ *   every call so it stays in sync with `canvas.getObjects` after creates,
+ *   removals, undo/redo, and JSON restores.
+ *
+ * - Every `<li>` carries a `data-mask-id` attribute
+ *   (via `dataset.maskId`) equal to the mask's `maskId`. Clients keying off
+ *   the list (the click handler below, the test suite under
+ *   `tests/properties/mask-list-dom.test.mjs`) MUST use this attribute and
+ *   never the visible label text — the label may be rewritten by the
+ *   integrator via `options.label.getText`, so it is NOT a stable key.
+ *
+ * - Clicking a list item selects the mask whose
+ *   `maskId` equals the clicked item's `data-mask-id`, regardless of where
+ *   the item currently sits in the list. The click handler does NOT use the
+ *   item's array index, so reordering the canvas (e.g. via Fabric layering)
+ *   does not break selection.
+ *
+ * ## Out of scope (handled by sibling modules)
+ *
+ * - Label text generation and `mask.maskId - 1` index — see
+ *   `mask/mask-label-manager.ts`.
+ * - Mask creation, removal, and the post-create `updateMaskList` call — see
+ *   `mask/mask-factory.ts`. The factory
+ *   invokes the orchestrator's `updateMaskList` callback, which delegates
+ *   here.
+ * - Hover/selection appearance on the canvas — see `mask/mask-style.ts`.
+ *
+ * ## Implementation notes
+ *
+ * - The orchestrator (`src/image-editor.ts`) owns the canvas reference, the
+ *   resolved `elements` table, and the selection callback. The helpers in
+ *   this module receive those slots through a {@link MaskListContext} so the
+ *   module is independent of the `ImageEditor` class shape and can be unit
+ *   tested in isolation against a stub Fabric environment plus a JSDOM
+ *   container.
+ * - The DOM contract — `<li class="list-group-item mask-item">` with a
+ *   `dataset.maskId` — matches legacy verbatim so existing CSS, theme overrides,
+ *   and integrator selectors continue to work unchanged.
+ * - Each render replaces the container's `innerHTML`. That is intentional:
+ *   it guarantees the DOM mirrors `canvas.getObjects` exactly, and the
+ *   Fabric event handlers (`object:added`, `object:removed`, `selection:*`)
+ *   already fire often enough that an incremental diff is not justified.
+ *   `innerHTML = ''` also detaches every prior `onclick` handler we attached
+ *   below, so there is no need to track listeners separately.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+import type { MaskObject } from '../core/public-types.js';
+/**
+ * State the mask-list helpers read from the `ImageEditor` orchestrator.
+ *
+ * The module does NOT own any of these slots — it only reads them so
+ * ownership of the canvas, the resolved DOM element ID map, and the
+ * selection-changed pipeline stays on the orchestrator (where legacy left
+ * them).
+ */
+export interface MaskListContext {
+    /**
+     * The live Fabric canvas the list mirrors. May be `null` after
+     * `dispose` or before `init` has run; the helpers no-op in that
+     * case.
+     */
+    canvas: FabricNS.Canvas | null;
+    /**
+     * Returns the resolved DOM element ID for the mask list container, or a
+     * falsy value when the integrator omitted `maskList` from the `idMap`.
+     * The orchestrator's `elements.maskList` slot fills this role.
+     */
+    getListElementId(): string | null | undefined;
+    /**
+     * Invoked by the click handler after `setActiveObject(mask)` has run,
+     * so the orchestrator can drive its selection-changed pipeline (label
+     * overlay, hover/selection styling, list highlight) the same way it
+     * does for canvas-originated selections. Mirrors legacy's
+     * `_handleSelectionChanged([mask])` call from `_handleMaskListClick`.
+     */
+    onMaskSelected(mask: MaskObject): void;
+}
+/**
+ * Re-render the mask list DOM from `canvas.getObjects`.
+ *
+ * No-op when the canvas is unset, the integrator did not supply a
+ * `maskList` element ID, or the configured element does not exist in the
+ * document. Tolerating partial DOM is intentional — the editor supports
+ * being driven from code without any sidebar UI (the editor's
+ * tolerated-bindings contract).
+ *
+ * Steps:
+ *
+ * 1. Resolve the list element via `context.getListElementId`. Bail out if
+ *    missing.
+ * 2. Clear the container with `innerHTML = ''`. This also detaches every
+ *    `onclick` handler attached on the previous render, so there is no
+ *    listener bookkeeping to track separately.
+ * 3. For each {@link MaskObject} returned by `canvas.getObjects` (in
+ *    canvas object order), build a fresh `<li>`:
+ *      - class `list-group-item mask-item` (matches legacy verbatim so
+ *        existing CSS keeps working);
+ *      - `textContent` set to `mask.maskName` (the label-text contract
+ *        owned by `mask/mask-label-manager.ts`; this list shows the same
+ *        identifier);
+ *      - `dataset.maskId` set to `String(mask.maskId)` so the click
+ *        handler and tests can key off a stable identifier;
+ *      - an `onclick` handler that looks up the mask by `maskId` —
+ *        regardless of the item's current position in the list — calls
+ *        `setActiveObject` on the canvas, and
+ *        forwards to `context.onMaskSelected(mask)` so the orchestrator's
+ *        selection-changed pipeline runs.
+ *
+ * @param context - Orchestration context — see {@link MaskListContext}.
+ */
+export declare function renderMaskList(context: MaskListContext): void;
+/**
+ * Toggle the `active` CSS class on every `<li class="mask-item">` so the
+ * one whose `data-mask-id` matches `selectedMask.maskId` is highlighted.
+ *
+ * Matches legacy's `updateMaskListSelection` behavior except that selection is
+ * keyed off `data-mask-id` instead of the list-item text content. legacy used
+ * the visible name (`textContent === selectedMask.maskName`), which broke
+ * when an integrator overrode `options.label.getText` to render anything
+ * other than `maskName`. Keying off `data-mask-id` keeps the highlight in
+ * lock-step with the stable `data-mask-id` identifier and tolerates any
+ * label-text customization.
+ *
+ * No-op when the integrator did not supply a `maskList` element ID or the
+ * configured element does not exist in the document.
+ *
+ * @param context - Orchestration context — see {@link MaskListContext}.
+ * @param selectedMask - The currently selected mask, or `null` to clear the
+ *                      highlight.
+ */
+export declare function updateMaskListSelection(context: MaskListContext, selectedMask: MaskObject | null): void;
+//# sourceMappingURL=mask-list.d.ts.map

package/dist/types/mask/mask-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask-list.d.ts","sourceRoot":"","sources":["../../../src/mask/mask-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;OAIG;IACH,MAAM,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;OAIG;IACH,gBAAgB,IAAI,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CA0C7D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,UAAU,GAAG,IAAI,GAChC,IAAI,CAWN"}