@bensitu/image-editor 1.5.2 → 2.1.0

package/dist/types/history/history-manager.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Bounded LIFO history stack of {@link Command} entries with
+ * dispose-aware async `undo` / `redo` semantics.
+ *
+ * Behavior contract:
+ *
+ *  • {@link HistoryManager.execute} and {@link HistoryManager.push} are
+ *  **synchronous** for the history-push step so callers can immediately
+ *  inspect {@link HistoryManager.canUndo} / {@link HistoryManager.canRedo}
+ *  on the next line (e.g. `updateUi` calls that immediately follow
+ *  `saveState`).
+ *
+ *  • {@link HistoryManager.undo} and {@link HistoryManager.redo} are
+ *  **async** and protected by an internal `isProcessing` lock. Overlapping
+ *  calls (rapid clicks) become no-ops that resolve without touching the
+ *  stack so canvas restores cannot interleave.
+ *
+ *  • `currentIndex` only advances **after** the awaited `execute` / `undo`
+ *  promise settles successfully. A rejection leaves the pointer where it
+ *  was so the next click retries the same step instead of skipping past
+ *  a failed restore.
+ *
+ *  • When the stack overflows past `maxSize`, the oldest entry is evicted
+ *  and `currentIndex` stays the same numerically (the entry it pointed to
+ *  has shifted one slot toward the front).
+ *
+ * `Command` is defined in this file (and re-exported from
+ * `./command.ts` as a one-line shim) so that the module can be imported
+ * directly from source by property tests running under Node's
+ * type-stripping mode without needing to resolve a sibling `.js`
+ * specifier at runtime.
+ *
+ * @module
+ */
+/**
+ * Encapsulates a reversible canvas operation as a paired
+ * `execute` / `undo` async closure.
+ *
+ * Both functions return `Promise<void>` so async Fabric.js operations
+ * (`loadFromJSON`, `FabricImage.fromURL`, …) complete before the history
+ * manager marks the step as finished and advances its pointer.
+ *
+ * @example
+ * ```ts
+ * const cmd = new Command(
+ *   async () => {
+ *     await canvas.loadFromJSON(afterJson);
+ *   },
+ *   async () => {
+ *     await canvas.loadFromJSON(beforeJson);
+ *   },
+ * );
+ * historyManager.execute(cmd);
+ * ```
+ */
+export declare class Command {
+    /** Performs (or re-performs) the action. */
+    readonly execute: () => Promise<void>;
+    /** Reverts the action. */
+    readonly undo: () => Promise<void>;
+    constructor(execute: () => Promise<void>, undo: () => Promise<void>);
+}
+/**
+ * Manages a bounded LIFO stack of {@link Command} objects supporting
+ * unlimited undo and redo within the configured history size.
+ */
+export declare class HistoryManager {
+    private history;
+    private currentIndex;
+    private isProcessing;
+    /** Maximum number of commands retained. */
+    readonly maxSize: number;
+    /**
+     * @param maxSize - Maximum number of commands retained.
+     * @default 50
+     */
+    constructor(maxSize?: number);
+    /**
+     * Records a command on the history stack **and** fires its `execute`
+     * (fire-and-forget).
+     *
+     * The history push is synchronous so that {@link canUndo} /
+     * {@link canRedo} reflect the new state on the next line. In the
+     * `saveState` pattern, `command.execute` is a no-op on its first
+     * invocation (guarded by an `executedOnce` flag inside the closure), so
+     * the fire-and-forget is safe and produces no canvas side-effect.
+     */
+    execute(command: Command): void;
+    /**
+     * Pushes a command onto the history stack **without** calling
+     * `execute`. Use this when the operation has already been performed
+     * (for example `applyCrop`) and only the undo/redo wiring is needed.
+     */
+    push(command: Command): void;
+    /** Returns `true` if there is at least one action to undo. */
+    canUndo(): boolean;
+    /** Returns `true` if there is at least one action to redo. */
+    canRedo(): boolean;
+    /**
+     * Undoes the most recent command.
+     *
+     * Resolves as a no-op if {@link canUndo} is `false` or another
+     * `undo` / `redo` is currently in flight (overlapping calls are
+     * rejected via the `isProcessing` lock). The `currentIndex` only moves
+     * after the awaited `command.undo` settles successfully; if it
+     * rejects, the pointer stays where it was so a subsequent click
+     * retries the same step.
+     */
+    undo(): Promise<void>;
+    /**
+     * Re-executes the next command.
+     *
+     * Resolves as a no-op if {@link canRedo} is `false` or another
+     * `undo` / `redo` is currently in flight. The `currentIndex` only
+     * advances after the awaited `command.execute` settles successfully.
+     */
+    redo(): Promise<void>;
+    /**
+     * Shared push/trim path for {@link execute} and {@link push}.
+     *
+     * Discards any redo branch past `currentIndex`, appends the new
+     * command, and either advances `currentIndex` (within capacity) or
+     * evicts the oldest entry without changing `currentIndex` numerically
+     * (overflow past `maxSize`).
+     *
+     */
+    private pushAndTrim;
+}
+//# sourceMappingURL=history-manager.d.ts.map

package/dist/types/history/history-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-manager.d.ts","sourceRoot":"","sources":["../../../src/history/history-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,OAAO;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;gBAEvB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;CAItE;AAED;;;GAGG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,YAAY,CAAS;IAE7B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;OAGG;gBACS,OAAO,GAAE,MAAW;IAIhC;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAQ/B;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI5B,8DAA8D;IAC9D,OAAO,IAAI,OAAO;IAIlB,8DAA8D;IAC9D,OAAO,IAAI,OAAO;IAIlB;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;CAgBtB"}

package/dist/types/image/image-loader.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Transactional `loadImage` pipeline. Validates the input,
+ * snapshots every field that the pipeline is about to mutate
+ * into a {@link RollbackBundle}, decodes the data URL into an
+ * `HTMLImageElement` under the configured timeout, optionally
+ * downsamples via {@link resampleImage}, awaits
+ * `FabricImage.fromURL` under the same timeout, applies the
+ * layout strategy chosen by `image/layout-manager.ts`, commits
+ * the new image to the canvas, and emits a fresh
+ * `lastSnapshot` via `core/state-serializer.ts`. Any failure
+ * between the snapshot and the commit replays the bundle and
+ * rejects with the original error.
+ *
+ * ## Owned contracts
+ *
+ * - When `loadImage` rejects, the original error is
+ *   routed through the public `onError(error, message)` callback via
+ *   `core/callback-reporter.ts → reportError`, AFTER `replayRollback` has
+ *   restored editor state. Callback exceptions are caught and logged so a
+ *   faulty integrator callback cannot mask the original error that the
+ *   loader re-throws. The success path does NOT invoke `onError`.
+ * - Strings that do not start with `data:image/`
+ *   resolve without mutating placeholder visibility, scroll position,
+ *   image state, or canvas state. The function returns before
+ *   capturing the rollback bundle, so no observable side effect occurs.
+ * - On a valid `data:image/` URL, the loader captures
+ *   the rollback bundle *before* mutating any of the fields it tracks
+ *   (placeholder `hidden`, container `scrollTop`/`scrollLeft`, container
+ *   `originalImage`, `lastSnapshot`, the canvas JSON
+ *   snapshot, plus the editor transform fields the rollback needs to
+ *   restore the live canvas to a consistent state).
+ * - Decode, Fabric, downsample, and timeout failures
+ *   restore every field captured in the rollback bundle and reject with the
+ *   original error.
+ * - On success, `isImageLoadedToCanvas` is set to
+ *   `true`, `lastSnapshot` is replaced with a fresh snapshot derived from
+ *   the new canvas, and `maskCounter` is reset to `0`.
+ * - Either the new image is committed fully, or the
+ *   prior committed state is restored fully. No partial state is observable
+ *   after the returned promise settles.
+ * - Both the decode step and the
+ *   `FabricImage.fromURL` step are bounded by `options.imageLoadTimeoutMs`
+ *   via {@link withTimeout}.
+ * - Timeout failures reject with
+ *   {@link ImageLoadTimeoutError} (built by `utils/timeout.ts`) and replay
+ *   the rollback bundle.
+ * - The 2D-context failure inside
+ *   {@link resampleImage} surfaces as {@link DownsampleError}; the loader
+ *   catches it and routes through the rollback path.
+ * - On success, `maskCounter` is reset to `0`.
+ *
+ * ## Implementation notes
+ *
+ * The loader is an exported **function** that takes its dependencies in a
+ * {@link LoadImageContext} parameter rather than a class. The `ImageEditor`
+ * facade owns all editor state (the canvas reference, the placeholder
+ * element, the editor scalar fields), so the loader must read and write
+ * that state through a small set of getter/setter callbacks. The class
+ * shape of legacy was a side effect of the monolith; current keeps the loader
+ * stateless so the rollback bundle is the single source of truth for what
+ * the operation has captured.
+ *
+ * The rollback bundle is built before the loader hides the placeholder or
+ * touches the canvas. It captures *every* field listed in the documented
+ * RollbackBundle definition plus the editor scalar fields
+ * (`isImageLoadedToCanvas`, `maskCounter`, `currentScale`,
+ * `currentRotation`, `baseImageScale`) the success path mutates. Restoring
+ * those scalars is required for atomic rollback — without them, a failed
+ * load that ran past the scalar reset would leave the editor with
+ * `currentScale = 1` and `currentRotation = 0` even though
+ * `originalImage` (and therefore the live canvas) had been rewound to the
+ * previous image.
+ *
+ * `preserveScroll` is honored on both the success path
+ * and the rollback path. On success it is conditional on
+ * `loadOptions.preserveScroll === true`; on rollback the bundle is replayed
+ * unconditionally, which the rollback contract already requires for
+ * transactional rewind. When `preserveScroll` is omitted or `false`, the
+ * success path leaves the container scroll untouched, so legacy's documented
+ * scroll/viewport behavior for the selected layout mode prevails.
+ *
+ * The loader does not invoke public success callbacks. It owns
+ * transactional mutation and rollback; the `ImageEditor` facade emits
+ * `onImageLoaded`, `onImageChanged`, `onMasksChanged`, and related lifecycle
+ * callbacks after this function returns from a committed load. The rollback
+ * path still reports load failures through `onError` after replaying the
+ * rollback bundle.
+ *
+ * Owner module references (per the documented "Mapping Contracts to
+ * modules" table): this module is the canonical owner of the transactional
+ * load helpers. It is NOT re-exported from `src/index.ts`.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+import type { FabricModule, ImageMimeType, LoadImageOptions, ResolvedOptions } from '../core/public-types.js';
+import { type ViewportCache } from './layout-manager.js';
+/**
+ * Snapshot of every field the loader is about to mutate, captured before
+ * the first mutation so a failure mid-pipeline can rewind the editor to
+ * its pre-call state.
+ *
+ * Mirrors the documented `RollbackBundle` definition with the addition of
+ * the editor scalar fields the success path also rewrites
+ * (`isImageLoadedToCanvas`, `maskCounter`, `currentScale`,
+ * `currentRotation`, `baseImageScale`). Those scalars must be restored
+ * together with the canvas JSON for atomic rewind.
+ *
+ */
+export interface RollbackBundle {
+    /** `placeholderElement.hidden` immediately before the loader hid it. */
+    placeholderHidden: boolean | null;
+    /** Container `scrollTop` immediately before the loader started. */
+    containerScrollTop: number | null;
+    /** Container `scrollLeft` immediately before the loader started. */
+    containerScrollLeft: number | null;
+    /** The previously-committed `originalImage` reference, if any. */
+    originalImage: FabricNS.FabricImage | null;
+    /** Whether an image was already committed before this call. */
+    isImageLoadedToCanvas: boolean;
+    /** Snapshot string used as the history baseline before the call. */
+    lastSnapshot: string | null;
+    /**
+     * Full canvas JSON serialization captured via `canvas.toJSON` with the
+     * editor's custom keys. Restored via `loadFromJSON` on rollback.
+     */
+    canvasJson: string;
+    /** Mask counter value before the loader reset it to 0. */
+    maskCounter: number;
+    /** Image scale factor before the loader reset it to 1. */
+    currentScale: number;
+    /** Image rotation in degrees before the loader reset it to 0. */
+    currentRotation: number;
+    /** Base scale chosen by the previous load, restored on rollback. */
+    baseImageScale: number;
+    /** MIME type of the image committed before the load started. */
+    currentImageMimeType: ImageMimeType | null;
+}
+/**
+ * Dependency bundle passed by the `ImageEditor` facade into
+ * {@link loadImage}. The loader has no class state of its own — every
+ * editor field it reads or writes is exposed here as a getter/setter pair
+ * so the facade keeps ownership of the canonical state.
+ *
+ * The facade is responsible for:
+ * - constructing the {@link ViewportCache} once and reusing it across
+ *   loads (so hidden-tab fallbacks work),
+ * - providing a `setPlaceholderVisible` callback that delegates to
+ *   `ui/visibility-state.ts`.
+ *
+ * The facade is also responsible for public success lifecycle callbacks after
+ * this transactional helper returns. The loader only reports failed loads
+ * through `onError` after rollback.
+ */
+export interface LoadImageContext {
+    /** The Fabric module providing `FabricImage.fromURL`. */
+    fabric: FabricModule;
+    /** The live Fabric canvas. */
+    canvas: FabricNS.Canvas;
+    /** Resolved editor options (timeouts, downsample knobs, layout flags). */
+    options: ResolvedOptions;
+    /** Scrollable container wrapping the canvas, or `null`. */
+    containerElement: HTMLElement | null;
+    /** Empty-state placeholder element, or `null`. */
+    placeholderElement: HTMLElement | null;
+    /** Hidden-container viewport cache shared with the layout manager. */
+    viewportCache: ViewportCache;
+    /** Reads the previously-committed `originalImage`. */
+    getOriginalImage(): FabricNS.FabricImage | null;
+    /** Writes `originalImage` (used both on commit and on rollback). */
+    setOriginalImage(imageObject: FabricNS.FabricImage | null): void;
+    /** Reads `isImageLoadedToCanvas`. */
+    getIsImageLoadedToCanvas(): boolean;
+    /** Writes `isImageLoadedToCanvas`. */
+    setIsImageLoadedToCanvas(v: boolean): void;
+    /** Reads `lastSnapshot`. */
+    getLastSnapshot(): string | null;
+    /** Writes `lastSnapshot`. */
+    setLastSnapshot(s: string | null): void;
+    /** Reads `maskCounter`. */
+    getMaskCounter(): number;
+    /** Writes `maskCounter`. */
+    setMaskCounter(n: number): void;
+    /** Reads `currentScale`. */
+    getCurrentScale(): number;
+    /** Writes `currentScale`. */
+    setCurrentScale(n: number): void;
+    /** Reads `currentRotation`. */
+    getCurrentRotation(): number;
+    /** Writes `currentRotation`. */
+    setCurrentRotation(n: number): void;
+    /** Reads `baseImageScale`. */
+    getBaseImageScale(): number;
+    /** Writes `baseImageScale`. */
+    setBaseImageScale(n: number): void;
+    /** Reads the MIME type of the currently committed image. */
+    getCurrentImageMimeType(): ImageMimeType | null;
+    /** Writes the MIME type of the currently committed image. */
+    setCurrentImageMimeType(mimeType: ImageMimeType | null): void;
+    /**
+     * Toggle placeholder/canvas-container visibility via
+     * `ui/visibility-state.ts`. `show === false` means "an image is now on
+     * the canvas — hide the placeholder".
+     */
+    setPlaceholderVisible(show: boolean): void;
+}
+/**
+ * Transactional image loader. Loads a base64 data URL onto the Fabric
+ * canvas with full rollback on any failure.
+ *
+ * Steps, in order:
+ *
+ * 1. **Validate** — non-`data:image/` strings resolve
+ *    immediately without capturing the bundle or touching state.
+ * 2. **Snapshot** — capture every field the pipeline
+ *    will mutate into a {@link RollbackBundle}.
+ * 3. **Hide placeholder** — first observable mutation. Restored on
+ *    rollback.
+ * 4. **Decode** — race the `<img>.onload` against
+ *    `imageLoadTimeoutMs` via {@link withTimeout}.
+ * 5. **Downsample** — if the source exceeds the
+ *    configured bounds, run {@link resampleImage}; a 2D-context failure
+ *    surfaces as {@link DownsampleError} and triggers rollback.
+ * 6. **Fabric load** — `FabricImage.fromURL` under the
+ *    same timeout.
+ * 7. **Layout** — pick a strategy via {@link selectLayoutStrategy} and
+ *    apply via {@link applyCanvasDimensions}.
+ * 8. **Commit** — set `isImageLoadedToCanvas`,
+ *    reset `maskCounter` to 0, reset transforms, and emit a fresh
+ *    `lastSnapshot` via {@link saveState}.
+ *
+ * Any rejection between step 3 and step 8 routes through {@link replayRollback}
+ * before re-throwing the original error. On the rollback
+ * path, the original error is also dispatched to the public `onError`
+ * callback via {@link reportError}; the helper catches
+ * and logs callback exceptions so a faulty integrator callback cannot
+ * replace the original error that this function re-throws.
+ *
+ * `preserveScroll` is honored on success when
+ * `loadOptions.preserveScroll === true`: after the canvas has been resized
+ * and the new image committed, the captured pre-load `scrollTop` and
+ * `scrollLeft` are written back to the container. The rollback path always
+ * restores scroll regardless of `preserveScroll` because the rollback
+ * requires the bundle to be replayed in full on failure. When
+ * `preserveScroll` is omitted or `false`, the success path leaves scroll
+ * untouched and legacy's documented scroll/viewport behavior for the selected
+ * layout mode applies.
+ *
+ * Public success lifecycle callbacks are emitted by the facade after this
+ * helper returns from a committed load. Keeping them outside the loader keeps
+ * transactional mutation/rollback separate from facade-level event ordering.
+ *
+ * @param context - Editor dependency bundle.
+ * @param imageBase64 - Base64 data URL to load (`data:image/...;base64...`).
+ * @param loadOptions - Public {@link LoadImageOptions}. Currently only
+ *                     `preserveScroll` is consulted; defaults to `false`.
+ * @returns Resolved promise on success, rejected with the original error
+ *          (after rollback) on failure. Non-data:image inputs resolve
+ *          without observable mutation.
+ *
+ */
+export declare function loadImage(context: LoadImageContext, imageBase64: string, loadOptions?: LoadImageOptions): Promise<void>;
+//# sourceMappingURL=image-loader.d.ts.map

package/dist/types/image/image-loader.d.ts.map

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

package/dist/types/image/image-resampler.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Aspect-preserving downsampling and alpha-aware MIME selection
+ * for oversized source images loaded by `image/image-loader.ts`.
+ *
+ * The resampler is a pure helper module: it does not know about the editor,
+ * the canvas, or the rollback bundle. It exposes three small, individually
+ * testable building blocks plus one orchestrating function:
+ *
+ * - {@link computeDownsampleDimensions} — pure aspect-ratio math used by
+ *   property tests for the resampler size contract.
+ * - {@link selectDownsampleMimeType}   — pure MIME-resolution table used by
+ *   property tests for the alpha-preserving fallback path.
+ * - {@link detectSourceMimeType}       — extracts the MIME prefix from a
+ *   base64 data URL.
+ * - {@link resampleImage}              — composes the above with a real
+ *   `<canvas>` to produce the downsampled data URL. Throws
+ *   {@link DownsampleError} when the offscreen canvas fails to obtain a
+ *   2D context so the loader can replay its rollback
+ *   bundle transactionally.
+ *
+ * This module is internal — it is NOT re-exported from `src/index.ts`.
+ *
+ * @module
+ */
+import type { ImageMimeType } from '../core/public-types.js';
+/**
+ * Result returned by {@link resampleImage}.
+ *
+ * `dataUrl` is the rasterised data URL produced by the offscreen canvas,
+ * `width` / `height` are the integer pixel dimensions used for that raster,
+ * and `mimeType` is the MIME chosen by {@link selectDownsampleMimeType}.
+ */
+export interface ResampleResult {
+    /** Rasterised data URL (`data:image/...;base64...`). */
+    dataUrl: string;
+    /** Output width in pixels (integer). */
+    width: number;
+    /** Output height in pixels (integer). */
+    height: number;
+    /** Resolved output MIME type. */
+    mimeType: ImageMimeType;
+}
+/**
+ * Compute target dimensions while preserving the source aspect ratio.
+ *
+ * Returns the source dimensions unchanged when both axes are already within
+ * `(maxWidth, maxHeight)`. When either bound is exceeded, returns the
+ * largest box that fits inside both bounds and matches the source aspect
+ * ratio, with each axis rounded to an integer.
+ *
+ * Pure function — no DOM access, safe to call from property tests.
+ *
+ * @param srcWidth - Source pixel width (must be > 0 for meaningful output).
+ * @param srcHeight - Source pixel height (must be > 0 for meaningful output).
+ * @param maxWidth - Maximum allowed output width in pixels.
+ * @param maxHeight - Maximum allowed output height in pixels.
+ * @returns `{ width, height, needsResize}` where `needsResize` is `true`
+ *          only when at least one source axis exceeded its bound.
+ *
+ */
+export declare function computeDownsampleDimensions(srcWidth: number, srcHeight: number, maxWidth: number, maxHeight: number): {
+    width: number;
+    height: number;
+    needsResize: boolean;
+};
+/**
+ * Select the output MIME type for downsampling.
+ *
+ * Selection table:
+ *
+ * | sourceMime          | preserveSourceFormat | downsampleMimeType | result               |
+ * | ------------------- | -------------------- | ------------------ | -------------------- |
+ * | image/png           | true                 | unset              | image/png            |
+ * | image/webp          | true                 | unset              | image/webp           |
+ * | image/png           | false                | unset              | image/jpeg           |
+ * | image/png           | true                 | image/jpeg         | image/jpeg           |
+ * | image/jpeg          | (any)                | unset              | image/jpeg           |
+ * | image/jpeg          | (any)                | image/webp         | image/webp           |
+ * | null / unknown      | (any)                | unset              | image/jpeg           |
+ *
+ * Pure function — no DOM access, safe to call from property tests.
+ *
+ * @param sourceMime - Detected source MIME (e.g. from
+ *                             {@link detectSourceMimeType}) or `null` if
+ *                             unknown.
+ * @param preserveSourceFormat - When `true`, alpha-capable source MIMEs
+ *                             survive downsampling unless overridden by
+ *                             `downsampleMimeType`.
+ * @param downsampleMimeType - Explicit MIME override; when truthy, wins over
+ *                             both `sourceMime` and `preserveSourceFormat`.
+ * @returns The MIME type to emit from the offscreen canvas.
+ *
+ */
+export declare function selectDownsampleMimeType(sourceMime: string | null, preserveSourceFormat: boolean, downsampleMimeType: ImageMimeType | null | undefined): ImageMimeType;
+/**
+ * Detect the MIME type embedded in a base64 data URL.
+ *
+ * Matches the standard `data:<mime>;...` prefix. Returns `null` when the
+ * input does not start with a recognizable image data URL prefix, so callers
+ * can pass the result straight into {@link selectDownsampleMimeType}.
+ *
+ * @param dataUrl - Base64 data URL (e.g. `data:image/png;base64,iVBOR...`).
+ * @returns The lowercased MIME type, or `null` when no `image/*` prefix is
+ *          present.
+ */
+export declare function detectSourceMimeType(dataUrl: string): string | null;
+/**
+ * Downsample an `HTMLImageElement` to fit within `(maxWidth, maxHeight)` and
+ * return the resampled data URL alongside its final dimensions and MIME.
+ *
+ * The function is the only piece of the resampler that touches the DOM. It
+ * creates an offscreen `<canvas>`, paints the source image into it at the
+ * computed dimensions, and reads back a data URL using the MIME selected by
+ * {@link selectDownsampleMimeType}. PNG output ignores `quality` because PNG
+ * is lossless; JPEG and WebP output use `quality` as the
+ * lossy compression knob.
+ *
+ * Failure mode: when `<canvas>.getContext('2d')` returns
+ * `null`, this function throws {@link DownsampleError} so
+ * `image/image-loader.ts` can replay its Transactional_Load rollback bundle
+ * before rejecting the public `loadImage` promise.
+ *
+ * @param imageElement - Decoded source image element.
+ * @param maxWidth - Maximum allowed output width in pixels.
+ * @param maxHeight - Maximum allowed output height in pixels.
+ * @param sourceMime - Detected source MIME from the original data
+ *                             URL (or `null` if unknown).
+ * @param preserveSourceFormat - When `true`, alpha-capable MIMEs survive.
+ * @param downsampleMimeType - Optional explicit MIME override.
+ * @param quality - Lossy compression quality in `[0, 1]` for
+ *                             JPEG/WebP output. Ignored for PNG.
+ * @returns The resampled data URL plus its dimensions and MIME.
+ *
+ * @throws {@link DownsampleError} when the offscreen canvas cannot obtain a
+ *         2D rendering context.
+ *
+ */
+export declare function resampleImage(imageElement: HTMLImageElement, maxWidth: number, maxHeight: number, sourceMime: string | null, preserveSourceFormat: boolean, downsampleMimeType: ImageMimeType | null | undefined, quality: number, ownerDocument?: Document): ResampleResult;
+//# sourceMappingURL=image-resampler.d.ts.map

package/dist/types/image/image-resampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-resampler.d.ts","sourceRoot":"","sources":["../../../src/image/image-resampler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC3B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,QAAQ,EAAE,aAAa,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAClB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CA8BzD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,wBAAwB,CACpC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,oBAAoB,EAAE,OAAO,EAC7B,kBAAkB,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GACrD,aAAa,CAaf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CACzB,YAAY,EAAE,gBAAgB,EAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,oBAAoB,EAAE,OAAO,EAC7B,kBAAkB,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACpD,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,QAAQ,GACzB,cAAc,CAmDhB"}