@ascentsparksoftware/react-image-editor 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1023 @@
+import { ReactElement } from 'react';
+
+/**
+ * Loader contracts for the editor's optional, heavyweight features — AI
+ * background removal (`@imgly/background-removal` + `onnxruntime-web`) and HEIC
+ * decoding (`heic2any`).
+ *
+ * The core editor deliberately does NOT `import()` these packages. They ship
+ * WASM, web workers and deep CJS graphs that the dev-server bundlers (Vite's
+ * optimizer in particular) cannot pre-bundle reliably; having them in the core's
+ * import graph breaks the editor for EVERY consumer, whether or not they use the
+ * feature. Instead the consumer installs the package it wants and injects a
+ * loader (see `providers.ts`). The heavy `import()` then lives in the consumer's
+ * own code, where they own the bundler config and only they pay the cost.
+ *
+ * These are intentionally MINIMAL structural types describing only the call
+ * surface the editor uses, so this file has zero dependency on the optional
+ * packages' own type declarations.
+ */
+/** The `heic2any` call surface the decoder uses. */
+type Heic2AnyFn = (opts: {
+    blob: Blob;
+    toType?: string;
+    quality?: number;
+}) => Promise<Blob | Blob[]>;
+/** Whatever `() => import('heic2any')` resolves to — a module namespace or the bare fn. */
+type AspHeicDecoderModule = {
+    readonly default?: Heic2AnyFn;
+} | Heic2AnyFn;
+/**
+ * A loader that resolves the `heic2any` decoder on demand. Register it with
+ * `provideAspHeicDecoder(() => import('heic2any'))` to enable HEIC/HEIF import.
+ */
+type AspHeicDecoderLoader = () => Promise<AspHeicDecoderModule>;
+/** The `@imgly/background-removal` call surface the engine uses. */
+type RemoveBackgroundFn = (source: Blob | string, config?: {
+    progress?: (key: string, current: number, total: number) => void;
+}) => Promise<Blob>;
+/** Whatever `() => import('@imgly/background-removal')` resolves to. */
+interface AspBackgroundRemovalModule {
+    readonly removeBackground: RemoveBackgroundFn;
+}
+/**
+ * A loader that resolves the background-removal engine on demand. Register it
+ * with `provideAspBackgroundRemoval(() => import('@imgly/background-removal'))`
+ * to enable the Remove-background / Cut-out-subject tools.
+ */
+type AspBackgroundRemovalLoader = () => Promise<AspBackgroundRemovalModule>;
+
+/**
+ * The editor's scoped CSS custom-property contract.
+ *
+ * Every visual style in the library references one of these `--asp-*` variables,
+ * and {@link deriveTheme} produces a value for each from the three theming inputs.
+ * Hosts may override any individual variable in their own CSS for fine control.
+ */
+/** Color tokens derived at runtime from `baseColor` + `accentColor` + `themeMode`. */
+declare const COLOR_TOKEN_NAMES: readonly ["--asp-bg", "--asp-surface", "--asp-surface-2", "--asp-surface-sunk", "--asp-ink", "--asp-ink-700", "--asp-ink-muted", "--asp-ink-faint", "--asp-line", "--asp-line-strong", "--asp-accent", "--asp-accent-ink", "--asp-accent-hover", "--asp-accent-soft", "--asp-accent-soft-ink", "--asp-ring", "--asp-scrim", "--asp-success", "--asp-warning", "--asp-error"];
+/** Non-color tokens: fixed dimensional/typographic values, the same in every theme. */
+declare const STATIC_TOKEN_NAMES: readonly ["--asp-radius-sm", "--asp-radius-md", "--asp-radius-lg", "--asp-radius-pill", "--asp-ctl-h", "--asp-ctl-h-sm", "--asp-font-mono"];
+/** Every token name the editor sets on its root element. */
+declare const THEME_TOKEN_NAMES: readonly ["--asp-bg", "--asp-surface", "--asp-surface-2", "--asp-surface-sunk", "--asp-ink", "--asp-ink-700", "--asp-ink-muted", "--asp-ink-faint", "--asp-line", "--asp-line-strong", "--asp-accent", "--asp-accent-ink", "--asp-accent-hover", "--asp-accent-soft", "--asp-accent-soft-ink", "--asp-ring", "--asp-scrim", "--asp-success", "--asp-warning", "--asp-error", "--asp-radius-sm", "--asp-radius-md", "--asp-radius-lg", "--asp-radius-pill", "--asp-ctl-h", "--asp-ctl-h-sm", "--asp-font-mono"];
+type ThemeTokenName = (typeof THEME_TOKEN_NAMES)[number];
+/** A fully-resolved theme: every token name mapped to a CSS value string. */
+type AspThemeTokens = Record<ThemeTokenName, string>;
+
+/**
+ * Derive the full `--asp-*` token set from the three theming inputs.
+ *
+ * Strategy: surfaces, ink, and lines are generated as a perceptually-even
+ * lightness scale tinted toward the BASE hue (so the editor blends with the
+ * host's neutral palette); interactive tokens are generated from the ACCENT.
+ * Text tokens are then run through {@link ensureContrastAA} against their actual
+ * background so WCAG AA (AAA for primary ink) is GUARANTEED for any input pair,
+ * in both light and dark — the 3 inputs alone always yield a legible result.
+ */
+
+/** Light or dark derivation. */
+type AspThemeMode = 'light' | 'dark';
+/**
+ * Build the complete theme token map.
+ *
+ * @param baseColor neutral anchor (hex) — surfaces/ink/lines tint toward its hue.
+ * @param accentColor interactive accent (hex) — kept exactly as the brand color.
+ * @param mode `'light'` or `'dark'`.
+ * @throws {Error} if either color is not valid hex.
+ */
+declare function deriveTheme(baseColor: string, accentColor: string, mode: AspThemeMode): AspThemeTokens;
+
+/**
+ * Public type contract for the editor.
+ *
+ * The tool and filter unions are derived from `as const` source arrays so the
+ * registry (and any exhaustiveness check) is structurally guaranteed to cover
+ * every member — there is one source of truth, not a union plus a parallel list
+ * that can drift.
+ */
+/** Layout/baseline preset — sets the chrome and a default tool set. */
+type AspMode = 'viewer' | 'basic' | 'advanced' | 'full';
+/**
+ * A host-controllable size: a number (interpreted as `px`) or any CSS length —
+ * `'600px'`, `'70%'`, `'80vh'`, `'calc(100vh - 120px)'`. Used for the editor's
+ * `width`/`height` inputs. A per-mode minimum is always enforced on top so the
+ * toolbars and panels keep enough room to render.
+ */
+type AspSize = number | string;
+/** Every tool the editor can expose, grouped by capability. Source of truth for {@link AspTool}. */
+declare const ALL_TOOLS: readonly ["crop", "rotate", "straighten", "flip", "resize", "pen", "highlighter", "eraser", "shapes", "arrow", "line", "text", "sticker", "redact", "magicwand", "removebg", "selectsubject", "adjust", "filters", "select", "layers", "duplicate", "delete", "opacity", "align", "group", "background", "frame"];
+type AspTool = (typeof ALL_TOOLS)[number];
+/** Fabric.js built-in filters exposed by the editor. Source of truth for {@link AspFilter}. */
+declare const ALL_FILTERS: readonly ["brightness", "contrast", "saturation", "vibrance", "hue", "blur", "sharpen", "grayscale", "sepia", "invert", "pixelate", "noise", "gamma", "blendColor"];
+type AspFilter = (typeof ALL_FILTERS)[number];
+/** Export formats. `json` serializes the re-editable Fabric scene; `pdf` embeds a raster. */
+type AspExportFormat = 'png' | 'jpeg' | 'webp' | 'svg' | 'json' | 'pdf';
+/** A structured error surfaced via the `errorOccurred` output. */
+interface AspEditorError {
+    /** Stable machine code, e.g. `'load-failed'`, `'export-failed'`, `'engine-init-failed'`. */
+    readonly code: string;
+    readonly message: string;
+}
+/** Crop aspect-ratio presets. */
+type AspAspectPreset = 'free' | '1:1' | '4:3' | '16:9' | '3:2' | 'original';
+/**
+ * A host-defined crop aspect option — e.g. a CMS target like a 1200×630 social
+ * image. `ratio` is width / height; build it from explicit dimensions with
+ * {@link aspectOption}.
+ */
+interface AspAspectOption {
+    readonly label: string;
+    readonly ratio: number;
+}
+/** Build an {@link AspAspectOption} from explicit pixel dimensions. */
+declare function aspectOption(width: number, height: number, label?: string): AspAspectOption;
+
+/**
+ * Lazy web-font loading for the text tool.
+ *
+ * A chosen family is loaded by injecting the Google Fonts stylesheet once and
+ * awaiting the CSS Font Loading API, so text renders in the correct font rather
+ * than a fallback. System/generic stacks need no loading. SSR-safe (no-op when
+ * `document` is absent), idempotent, and resolves even if loading fails (the
+ * fallback simply renders).
+ */
+interface FontOption {
+    readonly label: string;
+    /** CSS `font-family` value applied to the text object. */
+    readonly value: string;
+}
+/** Default font choices: a system stack plus popular Google families. */
+declare const DEFAULT_FONTS: readonly FontOption[];
+
+interface ImageEditorProps {
+    readonly src?: string | Blob | null;
+    readonly mode?: AspMode;
+    /**
+     * Editor width — a number (px) or any CSS length (`'70%'`, `'80vh'`,
+     * `'calc(100vw - 320px)'`). Defaults to filling the host's container. A
+     * per-mode minimum is always enforced so the chrome stays usable.
+     */
+    readonly width?: AspSize | null;
+    /** Editor height — same shape as {@link ImageEditorProps.width}. */
+    readonly height?: AspSize | null;
+    readonly tools?: readonly AspTool[] | null;
+    readonly disabledTools?: readonly AspTool[];
+    readonly filters?: readonly AspFilter[] | 'all' | null;
+    readonly aspectPresets?: readonly AspAspectPreset[];
+    /**
+     * Aspect the crop starts at. When set, the editor opens already constrained to
+     * it (in basic mode the crop frame is live immediately; in advanced/full it is
+     * the crop tool's starting aspect). When unset, a sole non-`free` preset is
+     * auto-selected, otherwise the crop opens unconstrained (`free`).
+     */
+    readonly initialAspect?: AspAspectPreset | null;
+    /** Host-defined crop aspect targets (e.g. CMS sizes); shown after the presets. */
+    readonly aspectRatios?: readonly AspAspectOption[];
+    readonly exportFormats?: readonly AspExportFormat[];
+    readonly exportQuality?: number;
+    readonly baseColor?: string;
+    readonly accentColor?: string;
+    readonly themeMode?: AspThemeMode;
+    /** Heading shown by the `basic` modal layout. */
+    readonly heading?: string;
+    /** Show the edit-history panel in the workspace (hosts that don't want it set false). */
+    readonly showHistory?: boolean;
+    /** Enable keyboard shortcuts while the pointer is over the editor. */
+    readonly keyboardEnabled?: boolean;
+    /** Available text fonts (host-overridable). */
+    readonly fonts?: readonly FontOption[];
+    /**
+     * Enable AI background removal / subject cut-out. Install
+     * `@imgly/background-removal` in the consuming app and pass its dynamic import:
+     * `backgroundRemovalLoader={() => import('@imgly/background-removal')}`.
+     * The heavy WASM/worker `import()` then lives in the consumer's bundle, not the
+     * library's. Without it the Remove-background / Cut-out tools are hidden.
+     */
+    readonly backgroundRemovalLoader?: AspBackgroundRemovalLoader | null;
+    /**
+     * Enable HEIC/HEIF image import. Install `heic2any` in the consuming app and
+     * pass its dynamic import: `heicDecoderLoader={() => import('heic2any')}`.
+     * Without it, importing a HEIC/HEIF file throws a descriptive error.
+     */
+    readonly heicDecoderLoader?: AspHeicDecoderLoader | null;
+    readonly onSaved?: (blob: Blob) => void;
+    readonly onCanceled?: () => void;
+    /** Fired after an image successfully loads (initial, picker, or upload). */
+    readonly onImageLoaded?: () => void;
+    /** Fired with the exported Blob when the user downloads from the Export menu. */
+    readonly onExported?: (blob: Blob) => void;
+    /** Fired on a recoverable error (load/export/engine init) instead of throwing. */
+    readonly onError?: (error: AspEditorError) => void;
+}
+/**
+ * `<ImageEditor>` — the editor's root/container component.
+ *
+ * Owns the {@link EditorController} (and through it the Fabric engine), the
+ * resolved tool/filter sets, theming, and all workspace state. Presentational
+ * children (rail, options panel, history, layers) render data and emit intent;
+ * this container is the only place that drives the engine.
+ */
+declare function ImageEditor({ src, mode, width, height, tools, disabledTools, filters, aspectPresets, initialAspect, aspectRatios, exportFormats, exportQuality, baseColor, accentColor, themeMode, heading, showHistory, keyboardEnabled, fonts, backgroundRemovalLoader, heicDecoderLoader, onSaved, onCanceled, onImageLoaded, onExported, onError, }: ImageEditorProps): ReactElement;
+
+/** Options for {@link openImageEditorDialog}. */
+interface OpenImageEditorConfig {
+    readonly src?: string | Blob | null;
+    readonly heading?: string;
+    readonly baseColor?: string;
+    readonly accentColor?: string;
+    readonly themeMode?: AspThemeMode;
+    readonly aspectPresets?: readonly AspAspectPreset[];
+    /** Aspect the crop opens constrained to (e.g. `'1:1'` for an avatar). */
+    readonly initialAspect?: AspAspectPreset;
+    readonly exportFormats?: readonly AspExportFormat[];
+}
+/**
+ * Opens the editor's `basic` layout in a modal overlay and resolves with the
+ * saved image Blob, or `null` if the user cancels (close button, scrim click,
+ * or Escape). Implemented with a dedicated React root on a detached scrim so
+ * it works from any event handler without a host component.
+ */
+declare function openImageEditorDialog(config?: OpenImageEditorConfig): Promise<Blob | null>;
+
+/**
+ * Data-driven tool and filter catalog.
+ *
+ * The rail, options panels, and resolution all read from these tables — there
+ * is no per-tool branching anywhere else. `mode`/`tools`/`disabledTools`/
+ * `filters` resolve against this metadata (see `resolve-tools.ts`).
+ */
+
+type AspToolGroup = 'transform' | 'annotate' | 'color' | 'object' | 'canvas';
+interface ToolMeta {
+    readonly key: AspTool;
+    readonly label: string;
+    /** Iconify/Lucide icon id. */
+    readonly icon: string;
+    readonly group: AspToolGroup;
+}
+/** A filter is either a continuous "adjustment" (slider) or a one-tap "look". */
+type FilterKind = 'adjustment' | 'look';
+interface FilterMeta {
+    readonly key: AspFilter;
+    readonly label: string;
+    readonly kind: FilterKind;
+    /** Slider bounds + default for adjustments (omitted for looks). */
+    readonly min?: number;
+    readonly max?: number;
+    readonly defaultValue?: number;
+    readonly unit?: string;
+}
+declare const TOOL_REGISTRY: Record<AspTool, ToolMeta>;
+declare const FILTER_REGISTRY: Record<AspFilter, FilterMeta>;
+declare const DEFAULT_TOOLS: Record<AspMode, readonly AspTool[]>;
+/** Default filter set per mode. `'all'` means every Fabric filter. */
+declare const DEFAULT_FILTERS: Record<AspMode, readonly AspFilter[] | 'all'>;
+
+/**
+ * Resolve the visible tool and filter sets from the public inputs.
+ *
+ * Tools:   `tools` (explicit allowlist) ?? default-for-`mode`, then minus `disabledTools`.
+ * Filters: `filters` (`'all'` | explicit list) ?? default-for-`mode`.
+ *
+ * In all cases the output is de-duplicated and restricted to known catalog
+ * members, so a stray or misspelled entry can never crash the UI or render a
+ * phantom control. Explicit lists preserve their given order; an explicit empty
+ * list is honored as "show nothing" (it is an override, not a fall-through).
+ */
+
+/**
+ * Resolve the ordered set of enabled tools.
+ *
+ * @param mode baseline preset.
+ * @param tools explicit allowlist, or `null` to use the mode default.
+ * @param disabledTools tools to subtract from the resolved set.
+ */
+declare function resolveTools(mode: AspMode, tools: readonly AspTool[] | null, disabledTools: readonly AspTool[]): AspTool[];
+/**
+ * Resolve the ordered set of enabled filters.
+ *
+ * @param mode baseline preset.
+ * @param filters explicit list, the literal `'all'`, or `null` for the mode default.
+ */
+declare function resolveFilters(mode: AspMode, filters: readonly AspFilter[] | 'all' | null): AspFilter[];
+
+/**
+ * A bounded linear undo/redo history.
+ *
+ * Each entry pairs a human label (for the History panel) with an opaque state
+ * snapshot (the editor stores serialized Fabric scenes here). Pure and fully
+ * unit-testable — it holds no Fabric references.
+ */
+interface HistoryEntry<T> {
+    readonly label: string;
+    readonly state: T;
+}
+declare class EditHistory<T> {
+    private readonly stack;
+    private cursor;
+    private readonly maxEntries;
+    constructor(initialLabel: string, initialState: T, maxEntries?: number);
+    /** All retained entries, oldest first. */
+    get entries(): readonly HistoryEntry<T>[];
+    /** Index of the current entry within {@link entries}. */
+    get index(): number;
+    get length(): number;
+    get current(): HistoryEntry<T>;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /**
+     * Record a new state. Any redo branch ahead of the cursor is discarded, and
+     * the oldest entries are dropped once the cap is exceeded.
+     */
+    push(label: string, state: T): void;
+    /** Step back one entry, or return `null` if already at the start. */
+    undo(): HistoryEntry<T> | null;
+    /** Step forward one entry, or return `null` if already at the end. */
+    redo(): HistoryEntry<T> | null;
+    /** Replace the entire history with a single fresh entry. */
+    reset(label: string, state: T): void;
+}
+
+/**
+ * A bounded linear undo/redo history that stores **diffs**, not full snapshots.
+ *
+ * The editor serializes its whole scene (often hundreds of KB once an image is
+ * loaded) on every edit. Keeping 50 full snapshots would cost tens of MB. This
+ * history keeps one full base plus a chain of jsondiffpatch deltas — each
+ * incremental edit (move a shape, tweak a color) is a sub-KB delta — and
+ * reconstructs any state on demand by replaying deltas from the base.
+ *
+ * Behavior is identical to a full-snapshot stack: `current`/`undo`/`redo`
+ * return the exact serialized state, branches truncate on push, and the oldest
+ * entries drop once the cap is exceeded (the new oldest is re-materialized into
+ * the base so the chain stays valid). Pure and unit-testable — no Fabric refs.
+ */
+
+/** Minimal projection of an entry for the History panel (labels only). */
+interface HistoryStep {
+    readonly label: string;
+}
+declare class DeltaHistory {
+    private readonly differ;
+    private readonly stack;
+    private cursor;
+    private readonly maxEntries;
+    constructor(initialLabel: string, initialState: string, maxEntries?: number);
+    /** Labels for every retained entry, oldest first (for the History panel). */
+    get entries(): readonly HistoryStep[];
+    get index(): number;
+    get length(): number;
+    get current(): HistoryEntry<string>;
+    /** The base entry (index 0) — used by the engine's full "reset edits" action. */
+    get first(): HistoryEntry<string>;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /**
+     * Record a new state. The redo branch ahead of the cursor is discarded, and
+     * the oldest entries drop once the cap is exceeded.
+     */
+    push(label: string, state: string): void;
+    /** Step back one entry, or return `null` if already at the start. */
+    undo(): HistoryEntry<string> | null;
+    /** Step forward one entry, or return `null` if already at the end. */
+    redo(): HistoryEntry<string> | null;
+    /** Replace the entire history with a single fresh base entry. */
+    reset(label: string, state: string): void;
+    /** Serialized byte length of the delta retained for an entry (for tests/metrics). */
+    retainedDeltaBytes(index: number): number;
+    /** Reconstruct the serialized state at an index by replaying deltas from the base. */
+    private entryAt;
+    /**
+     * Replay the delta chain from the base (index 0) up to `targetIndex`. The
+     * base is deep-cloned first so patching never mutates retained state.
+     */
+    private reconstruct;
+    /**
+     * Drop the base entry and promote the next one to a fresh base by
+     * materializing its full state (its delta no longer has a predecessor).
+     */
+    private dropOldest;
+}
+
+/**
+ * EditorEngine — the only component that talks to Fabric.js directly.
+ *
+ * It owns a Fabric `Canvas` holding one base `FabricImage` (the photo) plus
+ * annotation objects on top, and exposes high-level editor operations: load,
+ * zoom/pan, rotate/flip/straighten, crop, adjustments/filters, shapes/text/
+ * free-draw, undo/redo (serialized-scene snapshots), and export. UI components
+ * call these methods and never import Fabric themselves.
+ *
+ * Not unit-tested in jsdom (Fabric needs a real canvas/WebGL); verified through
+ * the demo with Playwright screenshots, per the project's visual-truth rule.
+ */
+
+interface EngineOptions {
+    readonly width: number;
+    readonly height: number;
+    /**
+     * Loader for AI background removal (`@imgly/background-removal`). When absent,
+     * the Remove-background / Cut-out tools are unavailable. Kept out of the core
+     * import graph on purpose — see `engine/loaders.ts`.
+     */
+    readonly backgroundRemovalLoader?: AspBackgroundRemovalLoader | null;
+    /**
+     * Loader for the HEIC/HEIF decoder (`heic2any`). When absent, importing a
+     * HEIC/HEIF file throws a descriptive error.
+     */
+    readonly heicDecoderLoader?: AspHeicDecoderLoader | null;
+}
+type ShapeKind = 'rect' | 'ellipse' | 'line' | 'arrow' | 'triangle' | 'diamond' | 'pentagon' | 'hexagon' | 'star';
+type RedactMode = 'blur' | 'pixelate' | 'solid';
+interface AnnotationStyle {
+    readonly color: string;
+    readonly strokeWidth: number;
+    /** Rectangle corner radius (px, in object coordinates). `0`/absent = sharp corners. */
+    readonly cornerRadius?: number;
+}
+interface TextStyle {
+    readonly color: string;
+    readonly fontSize: number;
+    readonly fontFamily?: string;
+}
+/** Rich-text attributes of the selected text, for the Text panel toggles. */
+interface TextStyleInfo {
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly underline: boolean;
+    readonly strike: boolean;
+    readonly align: string;
+    /** The text's current font family, so the panel can reflect it on selection. */
+    readonly fontFamily: string;
+}
+/** Editable style of the current selection, surfaced to the host UI. */
+interface SelectionStyleInfo {
+    /** `'text'` → color is fill + size is fontSize; `'stroke'` → color is stroke + size is strokeWidth. */
+    readonly kind: 'text' | 'stroke';
+    readonly color: string;
+    readonly size: number;
+    /** Present when a single text object is selected. */
+    readonly textStyle?: TextStyleInfo;
+    /** Present when a single rectangle is selected: its current corner radius. */
+    readonly cornerRadius?: number;
+    /** Present when a single rectangle is selected: the pill-cap radius for its size. */
+    readonly cornerRadiusMax?: number;
+}
+/** One entry in the layers panel (top of the z-stack first). */
+interface LayerInfo {
+    readonly id: string;
+    readonly label: string;
+    readonly locked: boolean;
+    readonly visible: boolean;
+    readonly selected: boolean;
+    /** Object opacity, 0–1. */
+    readonly opacity: number;
+    /** False for the base image, which should not be deletable. */
+    readonly removable: boolean;
+}
+/** A target output size in pixels for the artboard / export region. */
+interface ArtboardSize {
+    readonly width: number;
+    readonly height: number;
+}
+/** Progress of an in-browser AI operation (model fetch + inference). */
+interface AiProgress {
+    /** `'loading'` while fetching the model, `'processing'` during inference, `'done'`. */
+    readonly stage: 'loading' | 'processing' | 'done';
+    /** 0–1 within the current stage (best-effort; some stages report no total). */
+    readonly progress: number;
+}
+/** A user-placed guide line at a fixed scene coordinate. */
+interface ManualGuide {
+    readonly id: string;
+    /** `h` = horizontal line at scene-y `pos`; `v` = vertical line at scene-x `pos`. */
+    readonly orientation: 'h' | 'v';
+    readonly pos: number;
+}
+/** The current view transform plus canvas size — everything a ruler needs. */
+interface Viewport {
+    readonly zoom: number;
+    readonly panX: number;
+    readonly panY: number;
+    readonly width: number;
+    readonly height: number;
+}
+declare class EditorEngine {
+    private readonly canvas;
+    private readonly fabric;
+    private readonly history;
+    private baseImage;
+    private rotation;
+    private straighten;
+    private zoomPct;
+    private adjustments;
+    private looks;
+    private frame;
+    private idCounter;
+    private clipboard;
+    private panMode;
+    private panLast;
+    private snapEnabled;
+    private activeGuides;
+    private artboard;
+    /** Committed crop region (scene coords) — drives the dim mask and raster/PDF export. */
+    private cropRegion;
+    /** The interactive crop frame while the Crop tool is active, else null. */
+    private cropFrame;
+    /** Aspect ratio (w/h) constraining the crop frame, or null for free crop. */
+    private cropRatio;
+    /** Per-object interactivity saved while a crop session locks the rest of the scene. */
+    private cropPrevState;
+    private cropPrevUniformScaling;
+    /**
+     * Avatar-style crop (basic mode): a FIXED crop frame, with the base image
+     * panned and zoomed underneath it. Distinct from the movable `cropFrame` of the
+     * advanced workspace.
+     */
+    private imageCropActive;
+    /** The "cover" scale at which the image exactly fills the fixed crop frame (zoom floor). */
+    private imageCropFitScale;
+    private rulersEnabled;
+    private manualGuides;
+    /** Live preview of a guide being dragged from a ruler (not yet committed). */
+    private guideDraft;
+    /** Id of an existing manual guide being dragged on the canvas, if any. */
+    private draggingGuideId;
+    private guideIdCounter;
+    private selectionListener;
+    private layersListener;
+    private viewportListener;
+    private guidesListener;
+    private textMode;
+    private textPlacementListener;
+    private textFinishListener;
+    private pendingFinishText;
+    private redactPlacement;
+    private magicMode;
+    private magicListener;
+    private aiProgressListener;
+    private onFontsLoaded;
+    private lastViewportKey;
+    /** Consumer-injected loaders for the optional heavy features (may be null). */
+    private readonly bgRemovalLoader;
+    private readonly heicLoader;
+    /** Snap distance in *screen* pixels; divided by zoom to get a scene threshold. */
+    private static readonly SNAP_PX;
+    /** Pointer proximity (screen px) for grabbing a manual guide on the canvas. */
+    private static readonly GUIDE_GRAB_PX;
+    private constructor();
+    private nextId;
+    /** Register a callback fired when the active selection (and its style) changes. */
+    setSelectionListener(cb: (info: SelectionStyleInfo | null) => void): void;
+    /** Register a callback fired when the layer set or its state changes. */
+    setLayersListener(cb: () => void): void;
+    private notifyLayers;
+    private notifySelection;
+    private describeSelection;
+    /**
+     * Set the corner radius of the currently selected rectangle. The value is in
+     * on-screen pixels and is clamped to the rectangle's pill cap. No-op (returns
+     * false) when the selection is not a single rectangle. Pass `commit: false`
+     * for live slider drags; commit once on release.
+     */
+    setSelectedCornerRadius(radius: number, commit?: boolean): boolean;
+    /**
+     * Apply a color and/or size to the currently selected object(s), routing by
+     * object type (text → fill/fontSize, shapes & paths → stroke/strokeWidth, and
+     * recursing into groups such as arrows). Returns false if nothing is selected.
+     * Pass `commit: false` for live slider drags; commit once on release.
+     */
+    styleActiveObject(style: {
+        color?: string;
+        size?: number;
+        fontFamily?: string;
+    }, commit?: boolean): boolean;
+    private styleOne;
+    /** Enable/disable edge & center snapping. Clears any visible guides when off. */
+    setSnapping(enabled: boolean): void;
+    /** Scene-space bounding box of an object from its absolute corner coords. */
+    private sceneBox;
+    /**
+     * Nudge a dragged object so a near edge/center aligns to the canvas or another
+     * object, and record the guide lines to draw. Snap threshold is constant in
+     * *screen* pixels (zoom-aware) so it feels the same at any zoom.
+     */
+    private applySnap;
+    /** Pick the smallest within-threshold offset from any anchor to any line. */
+    private bestSnap;
+    /** Paint active guides onto the overlay context, mapped through the viewport. */
+    private drawGuides;
+    /** Drop the guides and repaint so the overlay is clean. */
+    private clearGuides;
+    /**
+     * Erase the overlay (top) context. `contextTop` can be momentarily undefined
+     * outside a render cycle, so this guards before touching it; clearing by the
+     * backing canvas's pixel size is correct regardless of retina scaling.
+     */
+    private clearOverlay;
+    /** Register a callback fired when the view transform or canvas size changes. */
+    setViewportListener(cb: () => void): void;
+    /** Register a callback fired when manual guides (or the live draft) change. */
+    setGuidesListener(cb: () => void): void;
+    private notifyGuides;
+    /** Current view transform + canvas size, in CSS pixels / scene units. */
+    getViewport(): Viewport;
+    private notifyViewportIfChanged;
+    /** Show/hide rulers; when off, an in-progress guide draft is dropped. */
+    setRulersEnabled(enabled: boolean): void;
+    isRulersEnabled(): boolean;
+    getManualGuides(): readonly ManualGuide[];
+    /** The live guide preview during a ruler drag, or null. */
+    getGuideDraft(): ManualGuide | null;
+    /** Map a viewport (screen, CSS-px) point to scene coordinates. */
+    viewportToScene(vx: number, vy: number): {
+        x: number;
+        y: number;
+    };
+    /** Map a client (page) point to canvas viewport (CSS-px) coordinates. */
+    clientToViewport(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Show a live guide preview at a scene position (during a ruler drag).
+     * Pass `null` to clear the preview. Does not touch history.
+     */
+    setGuideDraft(orientation: 'h' | 'v', scenePos: number | null): void;
+    /** Commit a new manual guide at a scene position and record it in history. */
+    addManualGuide(orientation: 'h' | 'v', scenePos: number): void;
+    /** Remove every manual guide and record it in history (no-op if already empty). */
+    clearManualGuides(): void;
+    /** The manual guide whose line is within grab range of a screen point, or null. */
+    private guideAtViewport;
+    /** Live-move the guide being dragged to the scene coordinate under the pointer. */
+    private dragGuideTo;
+    /**
+     * Finish a guide drag. Dropping the line outside the canvas removes it;
+     * otherwise the move is committed to history. Restores object selection.
+     */
+    private endGuideDrag;
+    /**
+     * Set (or clear) the artboard — a fixed output region. Content outside the
+     * region is dimmed on screen and excluded from raster/PDF export, which is
+     * rendered at exactly the artboard's pixel dimensions. `null` exports the
+     * whole canvas (the default).
+     */
+    setArtboard(size: ArtboardSize | null): void;
+    getArtboard(): ArtboardSize | null;
+    /** True while the interactive crop frame is on the canvas. */
+    isCropping(): boolean;
+    /** True once a crop region has been applied (drives the dim mask + export). */
+    hasCropRegion(): boolean;
+    /**
+     * Begin an interactive crop. Drops a draggable, resizable frame over the canvas
+     * (rule-of-thirds + dimmed surroundings), starting from any existing crop region
+     * or a centered default for the given aspect `ratio` (null = free). The rest of
+     * the scene is made non-interactive until {@link applyCropRegion} or
+     * {@link cancelCrop}.
+     */
+    beginCrop(ratio: number | null): void;
+    /** Reshape the active crop frame to a new aspect `ratio` (null = free). */
+    setCropRatio(ratio: number | null): void;
+    /** Only corner handles when an aspect ratio is locked; all handles when free. */
+    private applyCropControls;
+    /** Keep the dragged/resized crop frame within the canvas (and on-ratio). */
+    private constrainCropFrame;
+    /** Commit the crop frame as the output region and end the session. */
+    applyCropRegion(): void;
+    /** End the crop session without applying (the previous region is kept). */
+    cancelCrop(): void;
+    /** Clear any committed crop region (back to the full canvas). */
+    clearCropRegion(): void;
+    /** True while the fixed-frame, pan-and-zoom-the-image crop is active. */
+    isImageCropping(): boolean;
+    /**
+     * Begin an avatar-style crop: a FIXED crop frame of `ratio`, with the base
+     * image grabbable to pan and zoomable (via {@link zoomImageCrop}) underneath
+     * it. The image always covers the frame — there are no gaps. `null` ratio ends
+     * the image crop (full image).
+     */
+    beginImageCrop(ratio: number | null): void;
+    /** Switch the fixed crop frame to a new aspect (recenters + re-covers the image). */
+    setImageCropRatio(ratio: number | null): void;
+    /**
+     * Zoom the image within the fixed crop frame. `pct` is 100..400 where 100% is
+     * the "cover" floor (image exactly fills the frame). Zooms about the frame
+     * centre and keeps the frame covered.
+     */
+    zoomImageCrop(pct: number): void;
+    /** Commit the avatar crop: keep the fixed region as the export region, end the mode. */
+    applyImageCrop(): void;
+    /** End the avatar crop and clear the region (full image, no crop). */
+    cancelImageCrop(): void;
+    private endImageCrop;
+    /** Place the fixed crop frame for `ratio` and cover it with the image, centred. */
+    private setImageCropFrame;
+    /** The smallest image scale at which its (rotated) bounds still cover `frame`. */
+    private coverScaleFor;
+    /** Keep the panned/zoomed image fully covering the fixed crop frame (no gaps). */
+    private clampImageToCover;
+    /** Remove the crop frame and restore the rest of the scene's interactivity. */
+    private endCropSession;
+    /**
+     * The artboard's on-canvas rectangle in scene coordinates: the largest
+     * centered rectangle of the artboard's aspect ratio that fits the canvas.
+     * Returns null when no artboard is set.
+     */
+    private artboardRect;
+    /** Render the output region to a data URL at its target pixel size. */
+    private artboardDataUrl;
+    /** Output pixel size of the current region (crop region in scene px, else artboard preset). */
+    private outputSize;
+    /**
+     * Dim the canvas outside the current output region and outline it, on the
+     * overlay context. During an interactive crop the region is the live crop
+     * frame (with a rule-of-thirds grid and no extra outline, since Fabric draws
+     * the frame and its handles); otherwise it is the committed crop/artboard.
+     */
+    private drawArtboardMask;
+    /** The current output region (committed crop, else centered artboard), scene coords. */
+    private outputRect;
+    /** The live crop frame's rectangle in scene coordinates (bakes its scale). */
+    private cropFrameRect;
+    /** Create an engine bound to a `<canvas>` element. */
+    static create(canvasEl: HTMLCanvasElement, options: EngineOptions): Promise<EditorEngine>;
+    /**
+     * Resolve an import source into a canvas-ready URL.
+     *
+     * - SVG → rasterized at high resolution (Fabric's vector parser mangles complex
+     *   SVGs and a raw `<img>` misreads their intrinsic size).
+     * - Blob / data URL → decoded with EXIF orientation and downscaled, converting
+     *   formats the browser can't decode natively (HEIC/HEIF). Throws a descriptive
+     *   error on undecodable input rather than silently yielding nothing.
+     * - Remote URL → returned as-is and left to Fabric, since canvas-resampling a
+     *   cross-origin image would taint it.
+     */
+    private resolveImportUrl;
+    /**
+     * Load an image from a URL or Blob, fit it to the canvas, and reset history.
+     *
+     * A Blob is first decoded into a data URL so the image's serialized `src`
+     * survives in history snapshots (a transient object URL would be revoked and
+     * break undo).
+     */
+    loadImage(src: string | Blob): Promise<void>;
+    get hasImage(): boolean;
+    private fitBaseImage;
+    /** Rotate the image by a signed multiple of 90°. */
+    rotateBy(deg: number): void;
+    /** Fine straighten angle, −45..45°. */
+    setStraighten(deg: number, commit?: boolean): void;
+    private applyAngle;
+    /** Image-crop zoom as a percentage where 100% is the cover floor (for the slider). */
+    get imageCropZoomPct(): number;
+    /** Flip the image horizontally or vertically. */
+    flip(axis: 'h' | 'v'): void;
+    get zoom(): number;
+    setZoom(pct: number): void;
+    zoomBy(deltaPct: number): void;
+    resetView(): void;
+    /** Crop the base image to a centered rectangle of the given aspect preset. */
+    applyCrop(preset: AspAspectPreset): void;
+    /**
+     * Crop the base image to a centered rectangle of an arbitrary width/height
+     * ratio (`null` = full image). Use this for host-defined / CMS aspect targets.
+     */
+    applyCropRatio(ratio: number | null): void;
+    /** Merge adjustment values and re-render. Pass `commit` on slider release. */
+    setAdjustments(values: Partial<Record<AspFilter, number>>, commit?: boolean): void;
+    /** Toggle a one-tap look filter (grayscale/sepia/invert/sharpen). */
+    toggleLook(look: AspFilter): void;
+    isLookActive(look: AspFilter): boolean;
+    getAdjustment(key: AspFilter): number;
+    private rebuildFilters;
+    /** Add a shape at the canvas center. */
+    addShape(kind: ShapeKind, style: AnnotationStyle): void;
+    private buildArrow;
+    /** Add an editable text box at the canvas center. */
+    addText(text: string, style: TextStyle): void;
+    /**
+     * Enable/disable the "click to place text" mode (the Text tool). While on, the
+     * cursor is a text caret and clicking empty canvas drops an editable box.
+     */
+    setTextMode(enabled: boolean): void;
+    /** Register the callback fired with a scene point when text mode is clicked. */
+    setTextPlacementListener(cb: (point: {
+        x: number;
+        y: number;
+    }) => void): void;
+    /** Enable/disable magic-wand mode (a canvas click flood-fill erases a region). */
+    setMagicMode(enabled: boolean): void;
+    /** Register the callback fired with a scene point when magic mode is clicked. */
+    setMagicListener(cb: (point: {
+        x: number;
+        y: number;
+    }) => void): void;
+    /**
+     * Register the callback fired when an empty-canvas click in text mode finishes
+     * an already-placed text (so the host can switch back to the Select tool).
+     */
+    setTextFinishListener(cb: () => void): void;
+    /**
+     * Add a text box at a scene point and immediately enter in-place editing with
+     * the placeholder pre-selected, so the user just starts typing (Photoshop-style).
+     */
+    addTextAt(x: number, y: number, style: TextStyle): void;
+    private placeText;
+    /**
+     * Add a movable/resizable redaction marquee centered on the canvas. The user
+     * positions it over the area to conceal; transient until {@link applyRedaction}
+     * bakes it.
+     */
+    addRedactionMarquee(): void;
+    /** Add a redaction marquee centered at a scene point (used by click-to-place). */
+    addRedactionMarqueeAt(cx: number, cy: number): void;
+    /**
+     * Enable/disable click-to-place for redaction: while on, clicking empty canvas
+     * drops a new marquee there (but only when one isn't already present, so you
+     * reposition the existing box rather than spawning duplicates).
+     */
+    setRedactPlacement(enabled: boolean): void;
+    /** Remove the redaction marquee without applying it. */
+    cancelRedaction(): void;
+    /**
+     * Bake the redaction: conceal the COMPOSITED content under the marquee. `solid`
+     * lays an opaque box; `blur`/`pixelate` sample the rendered pixels in the region
+     * (so all underlying layers are hidden) and place a filtered, opaque patch.
+     */
+    applyRedaction(mode: RedactMode): Promise<void>;
+    private findByRole;
+    /**
+     * Apply a decorative frame around the image. Each style maps to a distinct,
+     * real border rendering (`none` clears it). The frame is a non-interactive
+     * rectangle tagged with `aspRole: 'frame'` so it can be re-found and replaced
+     * even after a history restore rebuilds every canvas object.
+     */
+    applyFrame(style: string, color: string): void;
+    /**
+     * Set the canvas background to a solid color (`'transparent'` clears it, showing
+     * the checkerboard). Fabric serializes `backgroundColor`, so it survives undo.
+     */
+    setBackground(color: string): void;
+    /** Set the canvas background to a linear gradient of the given color stops. */
+    setBackgroundGradient(colors: readonly string[]): void;
+    /** Set an uploaded image as the canvas background, scaled to cover. */
+    setBackgroundImage(src: string | Blob): Promise<void>;
+    /** Remove every canvas object tagged with the given `aspRole`. */
+    private removeTagged;
+    /**
+     * Enable or disable freehand drawing. When `highlighter` is set, the brush is
+     * translucent and wider so strokes read as a highlight over the underlying
+     * content rather than an opaque line.
+     */
+    setFreeDraw(enabled: boolean, style: AnnotationStyle, highlighter?: boolean): void;
+    /** Apply rich-text attributes (weight/style/underline/align/spacing/bg) to the active text. */
+    applyTextStyle(props: Record<string, string | number | boolean>, commit?: boolean): boolean;
+    /** Set the fill of the active non-text object(s) (`'transparent'` clears it). */
+    setActiveFill(color: string, commit?: boolean): boolean;
+    /** Set opacity (0–1) on the active object(s). Returns false if nothing selected. */
+    setOpacity(value: number, commit?: boolean): boolean;
+    /** Set opacity (0–1) on a specific layer. */
+    setLayerOpacity(id: string, value: number, commit?: boolean): void;
+    /** Delete the currently selected object(s). */
+    deleteActive(): void;
+    /** Clear the active selection. */
+    discardSelection(): void;
+    /** Select all editable (unlocked, non-base) objects. */
+    selectAll(): void;
+    /** Copy the current selection to the internal clipboard. */
+    copy(): Promise<void>;
+    /** Paste the clipboard contents, offset and selected. */
+    paste(): Promise<void>;
+    /** Add an image (e.g. pasted from the OS clipboard) as a movable object. */
+    addImageObject(src: string | Blob): Promise<void>;
+    /**
+     * Magic-wand erase: from a scene point, flood-fill the image under the pointer
+     * and clear (make transparent) every contiguous pixel within `tolerance`
+     * (0–100) of the clicked color. Great for knocking out a solid background.
+     * Operates on the base image, or a selected image layer if one is active.
+     */
+    magicErase(scenePoint: {
+        x: number;
+        y: number;
+    }, tolerance: number): Promise<boolean>;
+    /** Register a callback for AI-operation progress (model fetch + inference). */
+    setAiProgressListener(cb: (info: AiProgress) => void): void;
+    /** Whether AI background removal has a loader wired (drives feature gating). */
+    get backgroundRemovalAvailable(): boolean;
+    /**
+     * In-browser AI background removal. Segments the target image (the base image,
+     * or a selected image layer) and either replaces it with the cut-out subject
+     * (`mode: 'replace'`) or adds the cut-out as a new layer (`mode: 'subject'`).
+     * The model is fetched and cached on first use; progress is reported via the AI
+     * progress listener. Returns false if there's no image to process.
+     */
+    removeImageBackground(mode: 'replace' | 'subject'): Promise<boolean>;
+    /** Draw an image object's source bitmap to a fresh canvas and return a PNG blob. */
+    private imageToBlob;
+    /** Duplicate the current selection in place (offset). */
+    duplicateActive(): Promise<void>;
+    private addClones;
+    private setActive;
+    /** Group the current multi-selection into a single object. */
+    groupActive(): void;
+    /** Ungroup the selected group back into individual objects. */
+    ungroupActive(): void;
+    /** Align the active object/selection to an edge or center of the canvas. */
+    alignActive(mode: 'left' | 'center-h' | 'right' | 'top' | 'center-v' | 'bottom'): void;
+    /** Enable/disable space-drag panning (disables selection while active). */
+    setPanMode(enabled: boolean): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    get historyEntries(): readonly HistoryStep[];
+    get historyIndex(): number;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    /**
+     * Serialize the whole editor — scene objects, transform/adjustment/look/frame
+     * state, and the artboard — into a portable, versioned template string. The
+     * inverse of {@link loadScene}.
+     */
+    exportScene(): string;
+    /**
+     * Restore a template produced by {@link exportScene}. Resets the history to
+     * the loaded state so it becomes the new undo baseline. Throws on malformed
+     * input rather than loading a partial scene.
+     */
+    loadScene(json: string): Promise<void>;
+    /**
+     * Serialize the full editor state — the Fabric scene PLUS the engine's own
+     * transform/adjustment/look/frame state — so a restore puts both back in sync
+     * (the canvas alone does not capture rotation buckets, slider values, etc).
+     */
+    private snapshot;
+    private commit;
+    private restore;
+    private findBaseImage;
+    /** Reset all edits back to the freshly-loaded image. */
+    reset(): Promise<void>;
+    get rotationAngle(): number;
+    get straightenAngle(): number;
+    /** A copy of the current adjustment values. */
+    getAdjustments(): Record<AspFilter, number>;
+    /** The single active look (UI is single-select), or null. */
+    get activeLook(): AspFilter | null;
+    get activeFrame(): string;
+    /** The layer stack, top of the z-order first (matching visual stacking). */
+    getLayers(): LayerInfo[];
+    private findById;
+    /**
+     * Select a layer by id (no-op if it is locked or missing). When `additive`
+     * (shift/cmd/ctrl-click in the panel), toggle the layer in/out of a
+     * multi-selection instead of replacing it.
+     */
+    selectLayer(id: string, additive?: boolean): void;
+    /**
+     * Reorder the whole z-stack to match a display order (front-most first, as the
+     * Layers panel shows it). Used by drag-and-drop reordering.
+     */
+    reorderLayers(displayOrderIds: readonly string[]): void;
+    /** Rename a layer; an empty/blank name clears back to the auto label. */
+    renameLayer(id: string, name: string): void;
+    /** Lock/unlock a layer. Locked layers are not selectable, so clicks pass through. */
+    toggleLayerLock(id: string): void;
+    private setLocked;
+    /** Show/hide a layer. */
+    toggleLayerVisible(id: string): void;
+    /** Move a layer up (forward) or down (backward) in the z-order. */
+    moveLayer(id: string, direction: 'up' | 'down'): void;
+    /** Delete a layer (the base image is protected). */
+    deleteLayer(id: string): void;
+    /** Export the current scene to a Blob in the requested format. */
+    exportImage(format: AspExportFormat, qualityPct: number, allowedFormats: readonly AspExportFormat[]): Promise<Blob>;
+    /**
+     * Inline the web fonts used by the scene's text into the SVG so it is
+     * self-contained. Network failures fall back to the original SVG (text keeps
+     * its font-family). No-op outside a browser (no `fetch`).
+     */
+    private embedSvgFonts;
+    /** Distinct `fontFamily` values across all text objects (recursing into groups). */
+    private collectTextFontFamilies;
+    /**
+     * Render into a single-page PDF. The page is sized to the artboard (when set)
+     * or the full canvas, and the image is the matching region. jsPDF is lazy-loaded.
+     */
+    private exportPdf;
+    /** Pixel data of the current canvas, or null if no rendering context. */
+    getImageData(): ImageData | null;
+    /** Resize the editing surface. */
+    setSize(width: number, height: number): void;
+    /** Tear down the Fabric canvas and release resources. */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Apply a derived theme to an element as scoped CSS custom properties.
+ *
+ * Tokens are set on the element's inline `style`, so they cascade only to the
+ * editor's own subtree and never leak into (or clash with) the host page. Hosts
+ * can still override any individual `--asp-*` variable with higher specificity.
+ */
+declare function applyTheme(element: HTMLElement, tokens: AspThemeTokens): void;
+
+export { ALL_FILTERS, ALL_TOOLS, type AiProgress, type AnnotationStyle, type ArtboardSize, type AspAspectOption, type AspAspectPreset, type AspBackgroundRemovalLoader, type AspBackgroundRemovalModule, type AspEditorError, type AspExportFormat, type AspFilter, type AspHeicDecoderLoader, type AspHeicDecoderModule, type AspMode, type AspSize, type AspThemeMode, type AspThemeTokens, type AspTool, type AspToolGroup, COLOR_TOKEN_NAMES, DEFAULT_FILTERS, DEFAULT_FONTS, DEFAULT_TOOLS, DeltaHistory, EditHistory, EditorEngine, type EngineOptions, FILTER_REGISTRY, type FilterKind, type FilterMeta, type FontOption, type Heic2AnyFn, type HistoryEntry, type HistoryStep, ImageEditor, type ImageEditorProps, type LayerInfo, type ManualGuide, type OpenImageEditorConfig, type RedactMode, type RemoveBackgroundFn, STATIC_TOKEN_NAMES, type SelectionStyleInfo, type ShapeKind, THEME_TOKEN_NAMES, TOOL_REGISTRY, type TextStyle, type ThemeTokenName, type ToolMeta, type Viewport, applyTheme, aspectOption, deriveTheme, openImageEditorDialog, resolveFilters, resolveTools };