@bensitu/image-editor 1.5.1 → 2.0.0

package/dist/types/image/layout-manager.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Pure layout helpers and a small viewport cache used by the
+ * `image-loader` pipeline. The layout manager owns three concerns
+ * used by the image-load pipeline:
+ *
+ * 1. Selecting exactly one layout strategy per load using the
+ *    precedence `fit > cover > expand`.
+ * 2. Computing canvas dimensions and image scale for the selected
+ *    strategy.
+ * 3. Measuring the visible container viewport with a hidden-tab cache
+ *    and a final fall-back to `options.canvasWidth/canvasHeight`.
+ *
+ * The module also exposes a single sizing primitive,
+ * `applyCanvasDimensions`, which is the only place in the editor
+ * that calls `Canvas.setDimensions`. It rounds to integer pixels
+ * and forces a synchronous reflow on the container so that auto
+ * scrollbars settle before the next paint.
+ *
+ * The layout manager intentionally
+ * does NOT mutate developer CSS:
+ * - it never touches `canvas.style` or `container.style`
+ *   (`width`, `height`, `display`, `overflow`),
+ * - it reads `clientWidth` / `clientHeight` and compensates for
+ *   pre-existing auto scrollbars without any `overflow` toggle.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+import type { ResolvedOptions } from '../core/public-types.js';
+/**
+ * Discriminator for the active layout strategy. Exactly one value is
+ * returned by {@link selectLayoutStrategy} per `loadImage` call.
+ */
+export type LayoutStrategy = 'fit' | 'cover' | 'expand';
+/**
+ * Subset of {@link ResolvedOptions} consumed by strategy selection.
+ *
+ * The accepted boolean flags in precedence order are
+ * `fitImageToCanvas`, `coverImageToCanvas`, and `expandCanvasToImage`.
+ */
+export type LayoutFlags = Pick<ResolvedOptions, 'fitImageToCanvas' | 'coverImageToCanvas' | 'expandCanvasToImage'>;
+/**
+ * Choose the active layout strategy using the documented precedence
+ * `fit > cover > expand`.
+ *
+ * The selection is a pure function of the boolean flags — it is
+ * independent of the order in which the option keys were declared,
+ * of any prior load, and of any prior canvas state.
+ *
+ * When all three flags are `false` the function falls back to
+ * `'expand'`. This matches the default-options resolution which sets
+ * `expandCanvasToImage: true` by default, and gives a deterministic
+ * answer even if a consumer disables every layout flag.
+ *
+ */
+export declare function selectLayoutStrategy(options: LayoutFlags): LayoutStrategy;
+/**
+ * Inspect the layout flags and report whether `fitImageToCanvas` and
+ * `coverImageToCanvas` are both enabled — the only pairing that is a
+ * real conflict because both rescale the image to the canvas viewport
+ * but with different aspect-ratio strategies. `expandCanvasToImage`
+ * defaults to `true`, so combining it with one of the other two is
+ * normal usage (the user providedOptions into a per-load override) and is not
+ * flagged.
+ *
+ * The selected strategy still follows the precedence in
+ * {@link selectLayoutStrategy}; this helper exists so the facade can
+ * emit a single warning through the documented reporting path when a
+ * real conflict is detected.
+ *
+ * `null` is returned when no conflict is present.
+ */
+export interface LayoutConflict {
+    /** Strategies the caller had enabled simultaneously. */
+    readonly enabled: readonly LayoutStrategy[];
+    /** The strategy actually selected by `selectLayoutStrategy`. */
+    readonly selected: LayoutStrategy;
+    /** Human-readable summary suitable for `onWarning` consumers. */
+    readonly message: string;
+}
+export declare function detectLayoutConflict(options: LayoutFlags): LayoutConflict | null;
+/**
+ * Two-axis viewport size in CSS pixels.
+ *
+ * Both axes are non-negative integers. `0` is permitted in transient
+ * states (e.g. before the editor is attached) but {@link ViewportCache}
+ * treats any axis of `0` as "hidden" and falls back to a cached or
+ * default value.
+ */
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+/** Native scrollbar gutter size in CSS pixels. */
+export type ScrollbarSize = ViewportSize;
+export type OverflowAxis = 'horizontal' | 'vertical';
+/**
+ * Hidden-container viewport cache.
+ *
+ * The editor often runs inside a tab, modal, or accordion that starts
+ * collapsed. A naive `clientWidth` read in that state returns `0` and
+ * collapses the canvas. The cache remembers the last non-zero
+ * measurement and reuses it while the container reports a zero
+ * dimension on either axis. When no non-zero
+ * measurement has been observed yet, the caller-supplied fallback —
+ * normally `(options.canvasWidth, options.canvasHeight)` — is used
+ * instead. When the container becomes visible
+ * again, the next `measure` call updates the cache so subsequent
+ * sizing decisions reflect the new viewport.
+ *
+ * Measurements compensate for pre-existing auto scrollbars by adding
+ * the scrollbar gutter back to the visible client size. This mirrors
+ * v1.4.2's viewport recovery while still preserving v2's rule that
+ * layout code never mutates the container's `overflow` style.
+ *
+ */
+export declare class ViewportCache {
+    private lastVisible;
+    /**
+     * Measure the visible viewport for `container`, caching the result
+     * when both axes are non-zero. When either axis is zero, return the
+     * cached value if one exists, otherwise the supplied `fallback`.
+     *
+     * `null` containers (no element attached) yield the fallback
+     * directly; the cache is left untouched.
+     *
+     * @param container - The scrollable wrapper around the canvas, or
+     *                  `null` if no container has been resolved.
+     * @param fallback - The size to use when no live measurement and no
+     *                  cached measurement is available. Callers should
+     *                  pass `(options.canvasWidth, options.canvasHeight)`.
+     */
+    measure(container: HTMLElement | null, fallback: ViewportSize, scrollbarSize?: Partial<ScrollbarSize> | null): ViewportSize;
+    /**
+     * Return the cached viewport size without re-measuring. Useful for
+     * tests and for diagnostic logging. `null` indicates no non-zero
+     * measurement has been observed yet.
+     */
+    peek(): ViewportSize | null;
+    /**
+     * Discard the cached measurement. Intended for `dispose` paths.
+     * Calling `measure` again after `clear` behaves as if the editor
+     * has just been instantiated.
+     */
+    clear(): void;
+}
+/**
+ * Result of a layout computation. The image-loader applies these
+ * values to the Fabric canvas and the image object after a successful
+ * decode and Fabric load.
+ *
+ * `imageScale` is the Fabric `scaleX/scaleY` value that produces the
+ * desired on-canvas size for the image. `baseImageScale` is the
+ * editor's anchor scale used when computing zoom factors — see
+ * `image/transform-controller.ts` for how it is consumed.
+ */
+export interface LayoutResult {
+    canvasWidth: number;
+    canvasHeight: number;
+    imageScale: number;
+    imageLeft: number;
+    imageTop: number;
+    baseImageScale: number;
+}
+/**
+ * Measure the browser's native scrollbar gutter. Overlay-scrollbar
+ * environments legitimately return zero on one or both axes.
+ */
+export declare function measureScrollbarSize(ownerDocument?: Document | null): ScrollbarSize;
+/**
+ * Measure the full layout viewport represented by the canvas container.
+ *
+ * In `overflow: auto` containers, `clientWidth` / `clientHeight` can already
+ * be reduced by scrollbars left over from the previous canvas size. v1.4.2
+ * avoided using that reduced viewport by adding the gutter back before the
+ * next Cover/Fit calculation. v2 keeps the same recovery rule without
+ * mutating `style.overflow`.
+ */
+export declare function measureContainerViewport(container: HTMLElement | null, fallback: ViewportSize, scrollbarSize?: Partial<ScrollbarSize> | null): ViewportSize;
+/**
+ * Compute canvas dimensions for content that may overflow the visible
+ * viewport.
+ *
+ * An overflowing axis grows to the content size, while a non-overflowing
+ * axis uses the viewport space left after the perpendicular scrollbar
+ * gutter is accounted for. This keeps Cover/Fit from accidentally creating
+ * a second scrollbar solely because the first scrollbar reduced the cross
+ * axis client size.
+ */
+export declare function computeScrollableCanvasSize(contentWidth: number, contentHeight: number, viewport: ViewportSize, scrollbarSize?: Partial<ScrollbarSize> | null): ViewportSize;
+/**
+ * Compute layout for the `fit` strategy.
+ *
+ * The canvas is set to the visible container viewport, falling back to
+ * `(options.canvasWidth/Height)` only when no viewport measurement is
+ * available, minus one pixel per axis to leave room for any sub-pixel
+ * rounding error and avoid tripping the container's auto scrollbars.
+ * The image is uniformly scaled down to fit, but never up
+ * (`Math.min(..., 1)`).
+ *
+ */
+export declare function computeFitLayout(imageWidth: number, imageHeight: number, optionsCanvasWidth: number, optionsCanvasHeight: number, containerSize: ViewportSize): LayoutResult;
+/**
+ * Compute layout for the `cover` strategy.
+ *
+ * The visible viewport determines the cover target (with a final fall-back
+ * to the configured canvas dimensions if a viewport axis is zero — the
+ * {@link ViewportCache} normally prevents this from happening). Large
+ * images are scaled down until Cover fills one axis without upscaling small
+ * images. When the filled axis would need a scrollbar, the scale is
+ * recomputed against the cross-axis space left after that scrollbar appears;
+ * this preserves the Cover invariant that at least one axis stays scroll-free.
+ *
+ */
+export declare function computeCoverLayout(imageWidth: number, imageHeight: number, optionsCanvasWidth: number, optionsCanvasHeight: number, containerSize: ViewportSize, scrollbarSize?: Partial<ScrollbarSize> | null): LayoutResult;
+/**
+ * Compute layout for the `expand` strategy.
+ *
+ * The canvas grows per-axis to `max(viewport, image)` and the image is
+ * placed at `(0, 0)` at its native size. `baseImageScale` is `1` to
+ * preserve the image's natural aspect ratio and top-left placement.
+ *
+ */
+export declare function computeExpandLayout(imageWidth: number, imageHeight: number, optionsCanvasWidth: number, optionsCanvasHeight: number, containerSize: ViewportSize): LayoutResult;
+/**
+ * Apply canvas pixel dimensions atomically and force a synchronous
+ * reflow on the container.
+ *
+ * In Fabric.js v7 the canvas is a pair of `<canvas>` elements
+ * (`lowerCanvasEl` for rendering, `upperCanvasEl` for pointer events).
+ * `Canvas.setDimensions` is the only API that updates both layers
+ * atomically and keeps their CSS in sync. Manually mutating
+ * Direct canvas element style writes only resize the lower layer and
+ * misaligns the upper layer's hit-test regions, so the editor always
+ * routes through this helper instead of touching the canvas element
+ * styles.
+ *
+ * After `setDimensions`, the container is reflowed by reading
+ * `offsetWidth` (see `utils/dom.ts → forceReflow`). This makes
+ * `overflow: auto` containers show or hide their scrollbars before
+ * the next paint instead of waiting for the following frame.
+ *
+ * The `width` and `height` arguments are clamped to a minimum of `1`
+ * and rounded to integer pixels. Non-finite or non-numeric inputs
+ * collapse to `1` rather than crashing the editor.
+ *
+ * @param canvas - The Fabric canvas to resize. Required.
+ * @param width - Target pixel width. Clamped to `>= 1` and rounded.
+ * @param height - Target pixel height. Clamped to `>= 1` and rounded.
+ * @param containerElement - The wrapper element to reflow. May be `null`
+ *                         when no container has been resolved; in that
+ *                         case the reflow is skipped without error.
+ */
+export declare function applyCanvasDimensions(canvas: FabricNS.Canvas, width: number, height: number, containerElement: HTMLElement | null): void;
+//# sourceMappingURL=layout-manager.d.ts.map

package/dist/types/image/layout-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-manager.d.ts","sourceRoot":"","sources":["../../../src/image/layout-manager.ts"],"names":[],"mappings":"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"}

package/dist/types/image/transform-controller.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Animated scale, rotate, and reset operations on the
+ * `originalImage` with history integration. Owns the current
+ * transform pipeline that the `ImageEditor` facade routes
+ * through the `AnimationQueue`.
+ *
+ * ## Owned contracts
+ *
+ * - `scaleImage(factor)` clamps `factor` to
+ *   `[options.minScale, options.maxScale]` and animates the image scale
+ *   to the clamped factor over `options.animationDuration` milliseconds.
+ *   `scaleX` and `scaleY` are tweened together; {@link animateProps}
+ *   hides the v7 per-property
+ *   `onComplete` shape.
+ * - `rotateImage(degrees)` animates `angle` to
+ *   the requested value over `options.animationDuration` milliseconds.
+ *   The animation tweens around the visual centroid by temporarily
+ *   switching the image origin to `'center'/'center'`; the original
+ *   `'left'/'top'` origin is restored after the animation settles.
+ * - `scaleImage()` and `rotateImage()` return resolved promises for
+ *   non-finite inputs without modifying canvas state. The guards are the
+ *   first checks so no rollback bundle is needed.
+ * - `resetImageTransform` records exactly
+ *   one history entry covering the full reset. Per-operation
+ *   `saveCanvasState` calls inside the chained `scaleImage(1)` and
+ *   `rotateImage(0)` are suppressed via
+ *   {@link TransformContext.setSuppressSaveState}, and a single
+ *   `saveCanvasState` is emitted at the very end (success path) so
+ *   the entire reset is one undoable step. Failures inside the chain
+ *   still release the suppression flag in `finally` so subsequent
+ *   transforms continue to record history.
+ * - `scaleImage`, `rotateImage`, and
+ *   `resetImageTransform` each call `saveCanvasState` on success so
+ *   the new state is undoable. The orchestrator wires
+ *   `saveCanvasState` to the full `core/state-serializer.ts → saveState`
+ *   path; this module does not serialize the canvas itself.
+ *
+ * ## Dispose, animation guard, and origin safety
+ *
+ * The transform pipeline cooperates with three guards:
+ *
+ * 1. The orchestrator's {@link TransformContext.guard} sets
+ *    `isAnimating` true/false around the Fabric animation. The
+ *    `OperationGuard.runAnimation()` bracket clears the flag inside a
+ *    `finally` so the public promise sees `isAnimating === false` before
+ *    settling.
+ * 2. The animation queue (owned by the orchestrator) serializes
+ *    `scaleImage`, `rotateImage`, and `resetImageTransform` so concurrent
+ *    callers do not interleave mid-animation Fabric mutations. The
+ *    transform controller does NOT enqueue on the queue itself; the
+ *    orchestrator wraps each call through `animQueue.add(...)` before
+ *    invoking the controller method.
+ * 3. The dispose flag on {@link TransformContext.guard} lets animation
+ *    callbacks consult `guard.isDisposed()` before touching the canvas.
+ *    Rotation animations also restore the `'left'/'top'` origin via
+ *    {@link restoreOrigin} when dispose interrupts the animation so a
+ *    post-dispose inspector or a re-init that reuses the image reference
+ *    still sees the documented origin.
+ *
+ * ## Why a class with a context bundle?
+ *
+ * The legacy monolithic `ImageEditor` owned all transform state. This module keeps that
+ * state on the facade so `currentScale`, `currentRotation`,
+ * `baseImageScale`, and `shouldSuppressSaveState` remain on a single owner
+ * (these are part of the snapshot wire format). The
+ * controller therefore reads and writes through the
+ * {@link TransformContext} accessor pairs rather than duplicating the
+ * fields. Mirrors the same pattern used by
+ * `LoadImageContext`.
+ *
+ * Owner module references (per the documented "Mapping Contracts to
+ * modules" table): this module is imported by `image-editor.ts`. It is
+ * intentionally NOT re-exported from `src/index.ts`.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+import type { ResolvedOptions } from '../core/public-types.js';
+import type { OperationGuard } from '../core/operation-guard.js';
+/**
+ * Dependency bundle passed by the `ImageEditor` facade into
+ * {@link TransformController}. Mirrors the
+ * `LoadImageContext` shape so each pipeline
+ * keeps the orchestrator as the single owner of editor state.
+ *
+ * The facade is responsible for:
+ *
+ * - constructing a single {@link OperationGuard} per editor and reusing it
+ *   across pipelines so `isAnimating` and `isDisposed` live in one place,
+ * - routing each public transform method through the animation queue
+ *   before calling into the controller,
+ * - wiring {@link TransformContext.saveCanvasState} to the shared
+ *   `core/state-serializer.ts → saveState` path so the snapshot embeds
+ *   `_editorState`,
+ * - honouring {@link TransformContext.setSuppressSaveState} by making
+ *   `saveCanvasState` a no-op while the suppression flag is `true` —
+ *   this is what lets `resetImageTransform` record exactly one history
+ *   entry,
+ * - performing post-animation UI refresh (rotation/scale input boxes,
+ *   undo/redo buttons, mask label sync) — those concerns belong on the
+ *   facade, not in the controller, so per-step UI updates remain
+ *   centralized.
+ *
+ */
+export interface TransformContext {
+    /** The live Fabric canvas the original image lives on. */
+    canvas: FabricNS.Canvas;
+    /** Resolved editor options (animation duration, min/max scale). */
+    options: ResolvedOptions;
+    /**
+     * Shared operation guard. The controller calls
+     * {@link OperationGuard.runAnimation} to set `isAnimating` for the
+     * lifetime of each Fabric animation and to honour the dispose flag.
+     */
+    guard: OperationGuard;
+    /** Reads the previously-committed `originalImage`. */
+    getOriginalImage(): FabricNS.FabricImage | null;
+    /** Reads `currentScale`. */
+    getCurrentScale(): number;
+    /** Writes `currentScale`. */
+    setCurrentScale(n: number): void;
+    /** Reads `currentRotation` in degrees. */
+    getCurrentRotation(): number;
+    /** Writes `currentRotation` in degrees. */
+    setCurrentRotation(n: number): void;
+    /** Reads `baseImageScale` chosen at load time. */
+    getBaseImageScale(): number;
+    /**
+     * Persist a snapshot to the history stack. Wired by the orchestrator
+     * to `core/state-serializer.ts → saveState` plus the surrounding
+     * mask-label hide/restore bracket. While the suppression flag set by
+     * `setSuppressSaveState(true)` is active, the orchestrator
+     * MUST treat this as a no-op so `resetImageTransform` records exactly
+     * one history entry.
+     */
+    saveCanvasState(): void;
+    /**
+     * Toggle the suppression flag that turns {@link saveCanvasState} into
+     * a no-op. Used by {@link TransformController.resetImageTransform} to
+     * collapse the per-operation history entries from the chained
+     * `scaleImage(1)` and `rotateImage(0)` calls into a single reset
+     * entry. The orchestrator owns the flag itself; this method is the
+     * controller's only handle on it.
+     */
+    setSuppressSaveState(suppress: boolean): void;
+    /**
+     * Optional post-snap hook the orchestrator wires for legacy parity. Runs
+     * AFTER the controller commits the final value with `set` /
+     * `setCoords` and BEFORE `saveCanvasState`. Used to:
+     *
+     * - resize the canvas to image bounds when
+     *   `options.expandCanvasToImage` is `true`,
+     * - re-align the image bounding box to the canvas top-left,
+     * - re-sync mask label positions for visible labels.
+     *
+     * The hook is invoked only on the success path (no dispose) and only
+     * when defined — controllers running outside the facade (in tests)
+     * may omit it. Errors thrown from the hook propagate to the caller's
+     * `try/catch`, which mirrors legacy behaviour where the post-snap UI
+     * helpers ran inline inside the transform method.
+     */
+    afterTransformSnap?(): void;
+}
+/**
+ * Owns the animated `scaleImage`, `rotateImage`, and
+ * `resetImageTransform` operations. Each method is invoked from a queue
+ * entry on the orchestrator's animation queue and returns a Promise that
+ * resolves once the Fabric animation has settled and `saveCanvasState`
+ * has been called (or the operation no-opped because of dispose, an
+ * already-running animation, or non-finite input).
+ *
+ * Lifetime is one-per-editor — a fresh controller is constructed inside
+ * the `ImageEditor` constructor and lives until `dispose` runs. The
+ * controller holds no mutable state of its own; the {@link TransformContext}
+ * is the single source of truth.
+ *
+ */
+export declare class TransformController {
+    private readonly context;
+    /**
+     * @param context - Dependency bundle owned by the `ImageEditor` facade.
+     */
+    constructor(context: TransformContext);
+    /**
+     * Animate the image scale to `factor`, clamped to
+     * `[options.minScale, options.maxScale]`.
+     *
+     * Steps:
+     *
+     * 1. Bail (resolved) when no image is loaded, an animation is already
+     *    in progress, or the editor has been disposed.
+     * 2. Clamp `factor` to `[minScale, maxScale]` and update
+     *    `currentScale` so toolbar inputs reflect the requested value
+     *    BEFORE the animation begins (matches legacy timing).
+     * 3. Re-anchor the image origin to its current visual top-left so
+     *    `scaleX` / `scaleY` tweens scale around the upper-left corner
+     *    rather than the Fabric default centre.
+     * 4. Run a `scaleX` + `scaleY` tween via
+     *    {@link animateProps} inside an
+     *    {@link OperationGuard.runAnimation} bracket.
+     * 5. After the animation settles, snap to the exact target via
+     *    `set({ scaleX, scaleY})` + `setCoords` so floating-point
+     *    drift on the last tick does not leak into history.
+     * 6. Run the optional {@link TransformContext.afterTransformSnap}
+     *    hook for canvas resize / mask label sync.
+     * 7. Call {@link TransformContext.saveCanvasState} so the new state
+     *    is undoable. When dispose ran during the
+     *    animation, the controller exits without snapping or saving so
+     *    no torn-down canvas reference is touched.
+     *
+     * @param factor - Requested scale factor (1 = base, may exceed bounds —
+     *               the value is clamped before use).
+     * @returns A promise that resolves once the animation has settled and
+     *          history has been recorded, or immediately when the call
+     *          short-circuits due to one of the bail conditions.
+     *
+     */
+    scaleImage(factor: number): Promise<void>;
+    /**
+     * Animate the image rotation to `degrees`. Returns a resolved promise
+     * without modifying canvas state when `degrees` is not finite.
+     *
+     * Steps:
+     *
+     * 1. Bail (resolved) on non-finite input, missing image, in-flight animation,
+     *    or disposed editor.
+     * 2. Update `currentRotation` BEFORE the animation begins so toolbar
+     *    inputs reflect the requested value during the tween.
+     * 3. Switch the image origin to `'center'/'center'` around its
+     *    visual centroid so Fabric tweens the angle around the centre
+     *    of mass rather than the top-left corner.
+     * 4. Run an `angle` tween via {@link animateProps} inside an
+     *    {@link OperationGuard.runAnimation} bracket.
+     * 5. After the animation settles, snap to the exact target via
+     *    `set('angle', degrees)` + `setCoords`.
+     * 6. Restore the `'left'/'top'` origin around the new visual
+     *    top-left corner so subsequent placements (mask creation, crop
+     *    rectangle, etc.) read off the documented origin.
+     * 7. Run the optional {@link TransformContext.afterTransformSnap}
+     *    hook for canvas resize and mask label sync.
+     * 8. Call {@link TransformContext.saveCanvasState}.
+     *
+     * If dispose runs during the animation, step 6's origin restore
+     * branch is skipped — leaving the image in the temporary
+     * centre-origin state. The controller invokes
+     * {@link restoreOrigin} from `finally` so a post-dispose inspector
+     * still sees the documented `'left'/'top'` origin. `restoreOrigin`
+     * is documented as silent
+     * best-effort cleanup so it cannot mask the original animation
+     * error.
+     *
+     * @param degrees - Target rotation angle in degrees. Non-finite values are no-ops.
+     * @returns A promise that resolves once the animation has settled and
+     *          history has been recorded, or immediately when the call
+     *          short-circuits due to one of the bail conditions.
+     *
+     */
+    rotateImage(degrees: number): Promise<void>;
+    /**
+     * Animate the image to `scale = 1` and `rotation = 0` and record
+     * exactly one history entry covering the whole reset.
+     *
+     * Implementation strategy: chain `scaleImage(1)` and `rotateImage(0)`
+     * but suppress their per-operation history entries via
+     * {@link TransformContext.setSuppressSaveState}. After both
+     * sub-animations settle (or one rejects), release the suppression
+     * flag and emit a single `saveCanvasState` so the entire reset is
+     * one undoable step.
+     *
+     * Failure handling:
+     *
+     * - If `scaleImage(1)` or `rotateImage(0)` throws, the suppression
+     *   flag is still released in `finally` so subsequent transforms
+     *   continue to record history.
+     * - The single `saveCanvasState` call only runs on the success path.
+     *   A failed reset therefore does not push a half-applied snapshot
+     *   to history (the partially-applied scale or rotation is still
+     *   recoverable via subsequent successful transforms).
+     *
+     * @returns A promise that resolves once both sub-animations have
+     *          settled and the single history entry has been recorded.
+     *          Resolves immediately as a no-op when no image is loaded.
+     *
+     */
+    resetImageTransform(): Promise<void>;
+}
+//# sourceMappingURL=transform-controller.d.ts.map

package/dist/types/image/transform-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-controller.d.ts","sourceRoot":"","sources":["../../../src/image/transform-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAKjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,gBAAgB;IAC7B,0DAA0D;IAC1D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;IACxB,mEAAmE;IACnE,OAAO,EAAE,eAAe,CAAC;IACzB;;;;OAIG;IACH,KAAK,EAAE,cAAc,CAAC;IAEtB,sDAAsD;IACtD,gBAAgB,IAAI,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;IAEhD,4BAA4B;IAC5B,eAAe,IAAI,MAAM,CAAC;IAC1B,6BAA6B;IAC7B,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC,0CAA0C;IAC1C,kBAAkB,IAAI,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC,kDAAkD;IAClD,iBAAiB,IAAI,MAAM,CAAC;IAE5B;;;;;;;OAOG;IACH,eAAe,IAAI,IAAI,CAAC;IAExB;;;;;;;OAOG;IACH,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IAE9C;;;;;;;;;;;;;;;OAeG;IACH,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC/B;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAE3C;;OAEG;gBACS,OAAO,EAAE,gBAAgB;IAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6D/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0EjD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB7C"}