@bensitu/image-editor 1.5.2 → 2.0.0

package/dist/types/utils/canvas-region.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Pure helpers that turn floating-point Fabric.js bounding
+ * rectangles into integer pixel regions and provide the
+ * bounding-box math that mask preservation across crop and
+ * export paths share.
+ *
+ * ## Owned contracts
+ *
+ * - Export regions SHALL include partially covered trailing pixels so
+ *   sub-pixel image bounds do not lose the right or bottom edge.
+ * - Crop regions SHALL exclude trailing partial pixels so crop does not
+ *   grow by a transparent row or column.
+ * - When `applyCrop` runs with
+ *   `preserveMasksAfterCrop === true` and the image has been rotated,
+ *   each mask's new `left` and `top` SHALL be expressed in the cropped
+ *   image's coordinate frame using the rotation angle.
+ * - Across a crop apply, each mask's `angle`,
+ *   `scaleX`, and `scaleY` SHALL be preserved so the visible shape does
+ *   not change size or orientation.
+ *
+ * ## Why a dedicated module
+ *
+ * Region math is shared by export, crop, expand-to-image sizing, and crop
+ * rectangle initialization. Centralizing it prevents one call site from
+ * drifting from the others (for example, applying `Math.floor` instead of
+ * `Math.round`, or forgetting the `width >= 1` floor).
+ *
+ * ## Design notes
+ *
+ * - Region floors are total: any non-finite input collapses to a
+ *   `1×1` region anchored at `(0, 0)` rather than throwing. The export
+ *   and crop pipelines already validate the presence of an
+ *   `originalImage` upstream, so a defensive fallback here keeps the
+ *   `<canvas>.drawImage` call from being passed `NaN` if Fabric ever
+ *   reports a degenerate bounding rect.
+ * - `getObjectBBox` calls `setCoords` before reading the bounding
+ *   rect because Fabric.js v7's `getBoundingRect` returns the cached
+ *   absolute rect; without the refresh a freshly-mutated mask returns
+ *   stale coordinates. Callers that have already refreshed coords pay
+ *   only a single redundant call, which is cheaper than double-tracking
+ *   "is this object's cache fresh?" at every site.
+ * - `clampRegionToCanvas` exists for the crop pipeline, where the crop
+ *   rectangle's bounding rect can briefly exceed the canvas after a
+ *   user drag near the edge; clamping before the `drawImage` keeps the
+ *   blit inside the source canvas.
+ *
+ * ## Non-goals
+ *
+ * - This module does not perform any coordinate transformation between
+ *   pre-crop and post-crop frames; the rotation math for the
+ *   rotated-mask coordinate frame lives in `crop/crop-controller.ts`,
+ *   which uses
+ *   `getObjectBBox` here only as one input to that calculation.
+ * - This module does not mutate the Fabric object passed to
+ *   `getObjectBBox` beyond the `setCoords` refresh required by
+ *   Fabric.js v7's API.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+/**
+ * A canvas region whose `left` / `top` / `width` / `height` are all
+ * integer pixels suitable for `CanvasRenderingContext2D.drawImage` and
+ * Fabric.js `toDataURL({ left, top, width, height})`.
+ *
+ * Produced by {@link floorRegion} and {@link clampRegionToCanvas}; the
+ * `width` and `height` fields are guaranteed to be at least `1` so
+ * region exports never collapse to a zero-pixel image.
+ */
+export interface IntegerRegion {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface RegionRoundingOptions {
+    /**
+     * When true, `right` / `bottom` are ceiled to include partially covered
+     * trailing pixels. When false, they are floored to exclude them.
+     * @default true
+     */
+    includePartialPixels?: boolean;
+}
+export interface PartialExportEdges {
+    left: boolean;
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+}
+export declare function hasMeaningfulCanvasRegion(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, canvasWidth?: number, canvasHeight?: number): boolean;
+/**
+ * Convert a floating-point rectangle into an {@link IntegerRegion}.
+ *
+ * - `left` / `top` are floored and clamped to `>= 0` so the region
+ *   never starts before the source canvas's top-left corner.
+ * - `right` / `bottom` are ceiled by default to include partially covered
+ *   trailing pixels, or floored when `includePartialPixels` is false.
+ * - `width` / `height` are derived from those integer edges and clamped
+ *   to `>= 1` so no sub-pixel dimensions reach Fabric's region export.
+ * - Non-finite inputs collapse to a `1×1` region at `(0, 0)` rather than
+ *   propagating `NaN` into the canvas pipeline.
+ *
+ * region floor before mask remapping).
+ *
+ * @param rect - The floating-point bounding rect to discretize.
+ * @returns    An {@link IntegerRegion} safe to pass to `drawImage`.
+ */
+export declare function getClampedCanvasRegion(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, canvasWidth?: number, canvasHeight?: number, options?: RegionRoundingOptions): IntegerRegion;
+export declare function floorRegion(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}): IntegerRegion;
+export declare function hasFractionalCanvasEdge(value: number): boolean;
+export declare function getPartialExportEdges(bounds: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+} | null, angle?: number): PartialExportEdges | null;
+/**
+ * Read a Fabric.js object's absolute bounding rectangle in canvas-pixel
+ * coordinates.
+ *
+ * `setCoords` is called first because Fabric.js v7's
+ * `getBoundingRect` returns the cached absolute rect — the per-frame
+ * cache the canvas already maintains. Without the refresh a freshly
+ * mutated mask returns stale coordinates, which can make rotated masks
+ * drift after crop.
+ *
+ * The returned rect uses floating-point coordinates; callers that need
+ * integer pixel regions should pipe the result through
+ * {@link floorRegion}.
+ *
+ * @param object - The Fabric.js object to measure.
+ * @returns   The absolute bounding rect in canvas pixels.
+ */
+export declare function getObjectBBox(object: FabricNS.FabricObject): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/**
+ * Clamp an {@link IntegerRegion} so it fits entirely inside a canvas of
+ * `canvasWidth × canvasHeight` pixels.
+ *
+ * - `left` is clamped to `[0, canvasWidth - 1]`.
+ * - `top` is clamped to `[0, canvasHeight - 1]`.
+ * - `width` is clamped so `left + width <= canvasWidth`.
+ * - `height` is clamped so `top + height <= canvasHeight`.
+ *
+ * The function preserves the `width >= 1` / `height >= 1` invariant
+ * established by {@link floorRegion}, which keeps callers from having
+ * to special-case zero-sized regions when the supplied rect lands
+ * entirely outside the canvas.
+ *
+ * canvas before the mask coordinate remap).
+ *
+ * @param region - The integer region to clamp.
+ * @param canvasWidth - The source canvas's pixel width.
+ * @param canvasHeight - The source canvas's pixel height.
+ * @returns            A clamped {@link IntegerRegion}.
+ */
+export declare function clampRegionToCanvas(region: IntegerRegion, canvasWidth: number, canvasHeight: number): IntegerRegion;
+//# sourceMappingURL=canvas-region.d.ts.map

package/dist/types/utils/canvas-region.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-region.d.ts","sourceRoot":"","sources":["../../../src/utils/canvas-region.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,QAAQ,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,yBAAyB,CACrC,IAAI,EAAE;IACF,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB,EACD,WAAW,CAAC,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,MAAM,GACtB,OAAO,CAkCT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE;IACF,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB,EACD,WAAW,CAAC,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE,qBAA0B,GACpC,aAAa,CA4Bf;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB,GAAG,aAAa,CAEhB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED,wBAAgB,qBAAqB,CACjC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC3E,KAAK,SAAI,GACV,kBAAkB,GAAG,IAAI,CAc3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,YAAY,GAAG;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB,CASA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACrB,aAAa,CASf"}

package/dist/types/utils/dom.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DOM micro-helpers used by sizing and visibility flows.
+ *
+ * Kept intentionally small: the editor depends on a single synchronous
+ * reflow primitive after canvas dimension changes, and exposing it as a
+ * named utility lets layout, visibility, and crop flows share the same
+ * documented contract.
+ */
+/**
+ * Force a synchronous layout reflow on `element`.
+ *
+ * Reading an offset/scroll/clientWidth-like property forces the browser
+ * to flush queued style and layout work on the spot, before any further
+ * script runs. The editor relies on this after `Canvas.setDimensions`
+ * so a container with `overflow: auto` shows or hides scrollbars before
+ * the next paint, instead of waiting for the next frame.
+ *
+ * The read is cast to `void` and isolated in this helper so optimizers
+ * cannot eliminate it as a dead access. The function is a no-op when
+ * `element` is `null` or `undefined`, which keeps callers free of guards in
+ * environments where the container element may not yet be attached.
+ *
+ * @param element - The element whose layout should be flushed. `null` is ignored.
+ */
+export declare function forceReflow(element: HTMLElement | null | undefined): void;
+//# sourceMappingURL=dom.d.ts.map

package/dist/types/utils/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../../src/utils/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAMzE"}

package/dist/types/utils/file.d.ts

@@ -0,0 +1,80 @@
+/**
+ * File-input helpers used by the editor's file-input flow.
+ *
+ * These helpers cover three concerns:
+ *
+ * - Determining whether a `File` selected through the upload control is a
+ *   supported image, including the extension fallback when `file.type` is
+ *   empty (some operating systems and browsers report an empty MIME type
+ *   for known extensions).
+ * - Reading the file as a base64 data URL so the result can be routed
+ *   through the existing transactional `loadImage` pipeline (and therefore
+ *   inherit its rollback behavior on decode/Fabric/timeout failure).
+ * - Resetting the file input value after every attempt so selecting the
+ *   same file again triggers a fresh `change` event.
+ *
+ * The helpers do not call `loadImage` themselves; the orchestrator wires
+ * them into the file-input change handler. That keeps the public
+ * `loadImage` API unchanged beyond `LoadImageOptions`.
+ */
+/**
+ * Supported image extensions and the MIME type each one resolves to.
+ *
+ * Supported file extensions: `png`, `jpg`/`jpeg`, `webp`, `gif`, `bmp`.
+ * GIF and BMP are accepted as static raster input for canvas editing. GIF
+ * animation and GIF/BMP source-format preservation are not retained; exports
+ * are emitted through the editor's JPEG, PNG, or WebP export options.
+ *
+ * Keys are lowercase extensions without the leading `.`.
+ */
+export declare const SUPPORTED_IMAGE_EXTENSIONS: Record<string, string>;
+export declare const SUPPORTED_IMAGE_MIME_TYPES: Set<string>;
+/**
+ * Determine whether a `File` is a supported image and return its resolved
+ * MIME type, or `null` when it should be rejected.
+ *
+ * Resolution order:
+ *
+ * 1. If `file.type` is one of the supported image MIME types, return it
+ *    verbatim.
+ * 2. If `file.type` is empty, infer the MIME type from the file
+ *    extension via {@link SUPPORTED_IMAGE_EXTENSIONS}. This covers the
+ *    case where a browser or OS reports `''` for files with a known
+ *    extension.
+ * 3. Otherwise, return `null` so the caller can skip the load without
+ *    mutating editor state.
+ *
+ * @param file - File selected via the upload control.
+ * @returns The resolved MIME type, or `null` when the file is not a
+ *          supported image.
+ */
+export declare function inferImageMimeType(file: File): string | null;
+/**
+ * Read a `File` as a base64 data URL using `FileReader`.
+ *
+ * The returned data URL is suitable for the transactional `loadImage`
+ * pipeline: on failure the editor's existing
+ * rollback bundle restores placeholder visibility, scroll, overflow,
+ * `originalImage`, `lastSnapshot`, and the canvas JSON snapshot.
+ *
+ * @param file - File to read.
+ * @returns A promise that resolves to the data URL string, or rejects when
+ *          the underlying `FileReader` errors out or returns a non-string
+ *          result.
+ */
+export declare function readFileAsDataUrl(file: File): Promise<string>;
+/**
+ * Reset a file input element's value so selecting the same file again
+ * triggers a fresh `change` event.
+ *
+ * Some browsers reject programmatic assignment to `input.value` on
+ * security grounds; the assignment is wrapped in a `try`/`catch` so the
+ * caller never has to special-case those environments. A `null` input is
+ * a no-op so callers can pass the result of `document.getElementById`
+ * without an extra null check.
+ *
+ * @param input - File input element, or `null` when the element is not
+ *              present in the DOM.
+ */
+export declare function resetFileInput(input: HTMLInputElement | null): void;
+//# sourceMappingURL=file.d.ts.map

package/dist/types/utils/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../../src/utils/file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO7D,CAAC;AAEF,eAAO,MAAM,0BAA0B,aAAqD,CAAC;AAE7F;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAO5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAOnE"}

package/dist/types/utils/number.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Pure helpers used by `mask/mask-factory.ts` to turn the
+ * flexible `MaskNumericProp` and `PolygonPoint` inputs of
+ * {@link MaskConfig} into concrete numbers and `{ x, y }`
+ * points before a Fabric.js shape is constructed.
+ *
+ * ## Owned contracts
+ *
+ * - `MaskConfig` percentage values supplied for
+ *   `left`, `width`, `rx`, or `radius` SHALL resolve against the canvas
+ *   pixel **width** (axis `'x'`).
+ * - `MaskConfig` percentage values supplied for
+ *   `top`, `height`, or `ry` SHALL resolve against the canvas pixel
+ *   **height** (axis `'y'`).
+ * - A `MaskNumericProp` provided as a function
+ *   SHALL be invoked with `(canvas, ResolvedOptions)` and the returned
+ *   number used directly.
+ * - Polygon point items SHALL be accepted in
+ *   either `{ x, y }` object form or `[x, y]` tuple form and coerced to
+ *   numeric `{ x, y }` internally.
+ *
+ * ## Why a dedicated module
+ *
+ * `resolveNumeric` is axis-aware so horizontal values resolve against
+ * canvas width and vertical values resolve against canvas height.
+ * `coercePoint` lives next to it because both helpers are pure functions
+ * consumed by the same mask-factory pipeline.
+ *
+ * ## Design notes
+ *
+ * - `resolveNumeric` is total: any input that is not a number, a finite
+ *   percentage string, or a function falls through to `fallback` rather
+ *   than throwing.
+ * - Percentages are floored (`Math.floor`) to keep rendered placement
+ *   deterministic across canvas resizes.
+ * - The helper does NOT clamp the result against canvas bounds; callers
+ *   are responsible for any subsequent clamping (the mask factory may
+ *   expand the canvas to accommodate larger placements when
+ *   `expandCanvasToImage` is enabled).
+ *
+ * ## Non-goals
+ *
+ * - This module does not validate that the supplied `axis` matches the
+ *   field being resolved. Routing each `MaskConfig` field to the correct
+ *   axis is the mask factory's responsibility.
+ * - This module does not coerce or round the output of factory functions
+ *   (`(canvas, options) => number`); their return value is used verbatim
+ *   so consumers retain full control over sub-pixel placement.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+import type { MaskNumericProp, PolygonPoint, ResolvedOptions } from '../core/public-types.js';
+/**
+ * Axis selector used by {@link resolveNumeric} to decide which canvas
+ * dimension a percentage value resolves against.
+ *
+ * - `'x'` → `canvas.getWidth`
+ * - `'y'` → `canvas.getHeight`
+ */
+export type Axis = 'x' | 'y';
+/**
+ * Resolve a {@link MaskNumericProp} into a concrete pixel number.
+ *
+ * Resolution rules (in order):
+ * 1. If `val` is a `number`, return it unchanged.
+ * 2. If `val` is a function, invoke it as `val(canvas, options)` and
+ *    return the result.
+ * 3. If `val` is a string ending in `'%'`, parse the leading number,
+ *    multiply by `canvas.getWidth` (axis `'x'`) or
+ *    `canvas.getHeight` (axis `'y'`), floor the product, and return
+ *    it. Strings that do not parse to a
+ *    finite number fall through to `fallback`.
+ * 4. Anything else (including `undefined`, `null`, non-percent strings,
+ *    booleans, etc.) returns `fallback`.
+ *
+ * @example
+ * ```ts
+ * // 50% of an 800px-wide canvas:
+ * resolveNumeric('50%', 'x', 0, canvas, options); // → 400
+ *
+ * // Function form receives the live canvas and ResolvedOptions:
+ * resolveNumeric(
+ *   (canvas) => canvas.getWidth() - 20,
+ *   'x',
+ *   0,
+ *   canvas,
+ *   options,
+ * ); // → canvas.getWidth() - 20
+ *
+ * // Unrecognized input falls back:
+ * resolveNumeric(undefined, 'x', 10, canvas, options); // → 10
+ * ```
+ *
+ * @param val - The flexible mask numeric property to resolve.
+ * @param axis - Which canvas dimension a percentage resolves against.
+ * @param fallback - Value returned when `val` cannot be resolved.
+ * @param canvas - Live Fabric.js canvas; only `getWidth`/`getHeight`
+ *                 are read here, but the entire canvas is forwarded to
+ *                 factory functions.
+ * @param options - Fully-resolved editor options forwarded to factory
+ *                 functions.
+ *
+ * @returns The resolved pixel number, or `fallback` when no rule applies.
+ */
+export declare function resolveNumeric(val: MaskNumericProp | undefined, axis: Axis, fallback: number, canvas: FabricNS.Canvas, options: ResolvedOptions): number;
+/**
+ * Coerce a {@link PolygonPoint} into the canonical `{ x, y }` numeric
+ * shape used by Fabric.js polygon construction.
+ *
+ * Both input forms are accepted so callers may write polygon points in
+ * whichever style is most ergonomic at the call site:
+ *
+ * ```ts
+ * coercePoint({ x: 10, y: 20 }); // → { x: 10, y: 20 }
+ * coercePoint([10, 20]); // → { x: 10, y: 20 }
+ * ```
+ *
+ * Values are coerced via `Number(...)` so string-encoded coordinates
+ * (e.g. coming straight from a JSON payload) round-trip correctly. Any
+ * value that fails to coerce becomes `NaN`, matching the rest of the
+ * mask pipeline's tolerant input handling — callers that need stricter
+ * validation should perform it before constructing the polygon.
+ *
+ * @param pt - A polygon vertex in object or tuple form.
+ * @returns An `{ x, y }` numeric point.
+ */
+export declare function coercePoint(pt: PolygonPoint): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=number.d.ts.map

package/dist/types/utils/number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../../../src/utils/number.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE9F;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG,GAAG,GAAG,GAAG,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,cAAc,CAC1B,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,QAAQ,CAAC,MAAM,EACvB,OAAO,EAAE,eAAe,GACzB,MAAM,CAgBR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAKtE"}

package/dist/types/utils/timeout.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Promise/timer race helper used by the image-loader pipeline
+ * to bound the decode and `FabricImage.fromURL` steps.
+ *
+ * ## Owned contracts
+ *
+ * - `loadImage(base64)` decode of the data URL into
+ *   an `HTMLImageElement` SHALL be bounded by `options.imageLoadTimeoutMs`.
+ * - `loadImage(base64)` `FabricImage.fromURL` step
+ *   SHALL be bounded by the same `options.imageLoadTimeoutMs`.
+ * - If either timeout elapses, the returned promise
+ *   SHALL reject with a timeout error whose message includes the elapsed
+ *   milliseconds. The {@link ImageLoadTimeoutError} class owns the message
+ *   format; this module simply produces the error with the correct
+ *   `(label, elapsedMs)` pair.
+ *
+ * ## Why a dedicated module
+ *
+ * The image-loader needs to apply the *same* timeout policy to two
+ * independent async steps (decode and Fabric image creation). Centralizing
+ * the race in one helper keeps the loader straight-line, ensures both
+ * steps reject with the same error type, and gives the timeout logic a
+ * single place to evolve (for example, future cancellation hooks).
+ *
+ * ## Design notes
+ *
+ * - The race is implemented with a `setTimeout`-based timer that is
+ *   cleared as soon as the wrapped promise settles, so a slow-but-eventual
+ *   resolution does not leave a dangling timer (and the elapsed-time
+ *   measurement remains tight).
+ * - On timeout, the helper computes elapsed ms from a `Date.now` taken
+ *   at the start of the race. This avoids drift versus the `ms` argument
+ *   for callers that want to log the actual wall-clock duration.
+ * - On rejection of the wrapped promise, the original error is forwarded
+ *   verbatim so the loader can branch on its specific type
+ *   (`ImageDecodeError`, `DownsampleError`, etc.) rather than always
+ *   seeing a `ImageLoadTimeoutError`.
+ *
+ * ## Non-goals
+ *
+ * - The helper does NOT cancel the wrapped promise. JavaScript promises
+ *   have no built-in cancellation; the caller is responsible for any
+ *   cleanup of the underlying work (e.g. clearing an `<img>.src`).
+ * - The helper does NOT validate `ms`. Callers pass the resolved
+ *   `imageLoadTimeoutMs` from `default-options.ts`, which is already
+ *   coerced to a finite non-negative number.
+ *
+ * @module
+ */
+/**
+ * Race a promise against a timer. If the timer fires first, reject with
+ * an {@link ImageLoadTimeoutError} whose message includes `label` and the
+ * elapsed milliseconds. If the wrapped promise settles
+ * first, the timer is cleared and the original outcome is forwarded.
+ *
+ * Used by `image/image-loader.ts` to bound both the decode step and the
+ * `FabricImage.fromURL` step of `loadImage`.
+ *
+ * @example
+ * ```ts
+ * await withTimeout(
+ *   decodeImageElement(base64),
+ *   options.imageLoadTimeoutMs,
+ *   'image decode',
+ * );
+ * ```
+ *
+ * @typeParam T - Resolved value type of the wrapped promise.
+ *
+ * @param promise - The async work to race. Forwarded verbatim on resolution; rejection
+ *   reasons are forwarded unchanged so callers can branch on the original
+ *   error type.
+ * @param ms - Timeout duration in milliseconds. Expected to be a finite,
+ *   non-negative number; the caller (typically `default-options.ts`) is
+ *   responsible for coercion.
+ * @param label - Human-readable step label embedded in the timeout error message
+ *   (e.g. `'image decode'`, `'FabricImage.fromURL'`).
+ *
+ * @returns A promise that resolves to the wrapped promise's value, or
+ *   rejects with the wrapped promise's reason, or rejects with
+ *   {@link ImageLoadTimeoutError} if the timer fires first.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+//# sourceMappingURL=timeout.d.ts.map

package/dist/types/utils/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../../src/utils/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBzF"}