@coolms/image-editor-angular 2.0.0-alpha.2

package/types/coolms-image-editor-angular.d.ts

@@ -0,0 +1,1488 @@
+import * as _angular_core from '@angular/core';
+import { AfterViewInit, OnDestroy, OnInit } from '@angular/core';
+
+/**
+ * Pure geometry primitives shared across the engine and any UI shell
+ * sitting on top. Deliberately framework-agnostic: no Angular, no
+ * fabric.js, no Toast UI imports — these types are part of the public
+ * surface of `@coolms/image-editor` and need to compile without the
+ * peer dependency installed.
+ */
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Axis-aligned rectangle. The engine's `crop(rect)` consumes this shape
+ * directly; UI shells produce one from their cropzone overlay.
+ */
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface Bounds {
+    readonly minWidth: number;
+    readonly minHeight: number;
+    readonly maxWidth: number;
+    readonly maxHeight: number;
+}
+
+/**
+ * Filter contract for the engine.
+ *
+ * The public API uses lowercase names and normalised parameter ranges
+ * so the UI shell never has to know about fabric.js conventions.
+ * The `FabricEngineAdapter` is the single translation point: lowercase
+ * filter names map to fabric's BaseFilter classes, and `sharpen`
+ * resolves to a `Convolute` filter constructed with the canonical
+ * 3x3 sharpen kernel.
+ */
+type FilterName = 'brightness' | 'contrast' | 'saturation' | 'sepia' | 'grayscale' | 'invert' | 'blur' | 'sharpen' | 'noise' | 'pixelate';
+/**
+ * Per-filter parameter shape. Range conventions:
+ *   brightness   -1..1   (0 = no change)
+ *   contrast     -1..1   (0 = no change)
+ *   saturation   -1..1   (0 = no change)
+ *   blur          0..1   (0 = no blur, 1 = max)
+ *   noise         0..1
+ *   pixelate     blockSize in pixels (>= 2)
+ *
+ * sepia / grayscale / invert are parameterless (boolean toggles via
+ * `applyFilter(name)` and `removeFilter(name)`).
+ */
+interface FilterParams {
+    readonly brightness?: number;
+    readonly contrast?: number;
+    readonly saturation?: number;
+    readonly blur?: number;
+    readonly noise?: number;
+    readonly pixelate?: number;
+}
+
+/**
+ * Object / layer model for the image editor (Track C.1).
+ *
+ * The editor was historically single-image (one `FabricImage`, flat
+ * bitmap). C.1 introduces an **objects-as-layers** model: the base
+ * image is the bottom layer; every shape / text the author adds is a
+ * layer stacked on top. Fabric's canvas is already an ordered object
+ * stack, so a "layer" is just a canvas object carrying a stable id.
+ *
+ * Resize / filters still operate on the base image only — they're
+ * pixel-baking ops, meant to run before annotations. C.1c makes
+ * **rotate / flip** target the selected non-image layer (falling back
+ * to the base image) and adds **masking** (a clip-path on the target;
+ * see {@link MaskSpec}); C.1e makes **crop** composition-aware — the
+ * annotation layers shift with the cropped content and clip at the new
+ * edges, so a crop after annotating stays aligned.
+ */
+/** What a layer is. `image` is the immovable-from-the-stack base. */
+type LayerKind = 'image' | 'shape' | 'text';
+/** The shape primitives the Shapes tool can insert. */
+type ShapeKind = 'rect' | 'ellipse' | 'line' | 'arrow' | 'triangle';
+/**
+ * Canvas-space geometry of an annotation shape — the round-trippable
+ * subset consumers that author geometry (e.g. the ImageMap region
+ * page) read and write via `addShapeAt()` / `getShapeGeometry()`.
+ * Coordinates are SCENE space (viewport zoom/pan factored out), the
+ * same space `getImageBounds()` reports in.
+ */
+type ShapeGeometry = {
+    kind: 'rect';
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+} | {
+    kind: 'ellipse';
+    center: {
+        x: number;
+        y: number;
+    };
+    rx: number;
+    ry: number;
+} | {
+    kind: 'polygon';
+    points: {
+        x: number;
+        y: number;
+    }[];
+};
+/**
+ * Options for `addShapeAt()`. Style keys mirror {@link ShapeOptions};
+ * the extras tune the shape for geometry-authoring use:
+ * - `name`: layer display name (defaults to the shape kind).
+ * - `lockRotation`: hide the rotate handle — authored geometry is
+ *   axis-aligned (rect regions have no rotation representation).
+ * - `lockNonUniformScaling`: hide the edge handles so corner drags
+ *   scale uniformly (keeps a circle circular).
+ */
+interface AnnotationShapeOptions {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    name?: string;
+    lockRotation?: boolean;
+    lockNonUniformScaling?: boolean;
+}
+/**
+ * How a shape / text layer is filled (C.1b).
+ *
+ * - `solid`  : a single flat colour.
+ * - `linear` : a linear gradient from `color` -> `color2` along `angle`.
+ * - `radial` : a radial gradient from `color` (centre) -> `color2` (edge).
+ */
+type FillType = 'solid' | 'linear' | 'radial';
+/**
+ * UI-friendly, serialisable description of a fill. The engine
+ * translates this to / from a fabric solid colour or `Gradient`, so the
+ * tool components never import fabric. Colours are `#rrggbb` hex (what
+ * `<input type="color">` reads / writes); `angle` is in degrees
+ * (0 = left->right, 90 = top->bottom) and only meaningful for `linear`.
+ */
+interface FillSpec {
+    type: FillType;
+    color: string;
+    color2: string;
+    angle: number;
+}
+/**
+ * A read-only view of one layer, surfaced to the Layers panel. The
+ * engine owns the fabric objects; this is the serialisable projection
+ * the UI binds to (never a live fabric handle).
+ */
+interface LayerInfo {
+    readonly id: string;
+    readonly kind: LayerKind;
+    readonly name: string;
+    readonly visible: boolean;
+    /** 0..1. */
+    readonly opacity: number;
+    /**
+     * True for the base image: it can't be deleted or reordered below
+     * itself (it's the canvas floor). Shapes / text are never locked.
+     */
+    readonly locked: boolean;
+}
+/** Style options for an inserted shape. */
+interface ShapeOptions {
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+    /**
+     * Richer fill description (solid colour or gradient). When present
+     * it takes precedence over the flat `fill` string. The Shapes tool
+     * always sends this; `fill` stays a plain-colour fallback for any
+     * caller that doesn't. (C.1b)
+     */
+    fillSpec?: FillSpec;
+}
+/** Style options for inserted text. */
+interface TextOptions {
+    text: string;
+    fontFamily: string;
+    fontSize: number;
+    fill: string;
+    fontWeight: 'normal' | 'bold';
+    fontStyle: 'normal' | 'italic';
+    textAlign: 'left' | 'center' | 'right';
+    /** Gradient-capable fill; see {@link ShapeOptions.fillSpec}. (C.1b) */
+    fillSpec?: FillSpec;
+}
+/**
+ * Generic property bag the style panels read/write against the active
+ * object. Keys are fabric property names (`fill`, `stroke`,
+ * `strokeWidth`, `opacity`, `fontFamily`, …); the engine reads them off
+ * / sets them on the active object without the UI importing fabric.
+ */
+type ObjectProps = Record<string, string | number>;
+/**
+ * Mask / clip shapes a layer can be cut to (C.1c / C.1d).
+ *
+ * `none` clears the mask. `rect` / `rounded` / `ellipse` / `triangle`
+ * are geometric primitives; `star` / `heart` / `hexagon` are SVG-path
+ * presets. `custom` (C.1d) clips to arbitrary path geometry the user
+ * pasted or uploaded as an SVG — see {@link MaskSpec.svgPath}. The
+ * engine builds the matching fabric `clipPath` against the target's own
+ * box, so the mask tracks the object through scale / move, and the
+ * export flatten bakes it in (the clip is part of the object's normal
+ * render path).
+ */
+type MaskShape = 'none' | 'rect' | 'rounded' | 'ellipse' | 'triangle' | 'star' | 'heart' | 'hexagon' | 'custom';
+/**
+ * UI-friendly description of a layer mask. The engine translates it to /
+ * from a fabric `clipPath`, so the tool component never imports fabric.
+ *
+ * - `inset`   : 0..40, percent each edge is pulled in from the box (a
+ *               symmetric margin around the clip).
+ * - `radius`  : 0..50, corner radius for `rounded` only, as a percent of
+ *               the clip's shorter half-dimension (50 = pill / circle).
+ * - `svgPath` : SVG path `d` data for `shape: 'custom'` (C.1d). Sanitised
+ *               geometry extracted from a pasted path string or uploaded
+ *               SVG file — every drawable element is flattened to a single
+ *               combined path (paths only, no script / external refs). The
+ *               engine scales its bounding box to the clip box exactly
+ *               like the built-in path presets, so it tracks scale / move
+ *               and round-trips through the `coolmsMask` stamp.
+ */
+interface MaskSpec {
+    shape: MaskShape;
+    inset: number;
+    radius: number;
+    svgPath?: string;
+}
+
+/**
+ * Normalised event surface for `ImageEditorEngine`.
+ *
+ * The adapter translates engine-internal events (Toast UI's
+ * `objectActivated`, `undoStackChanged`, etc.) into this stable map
+ * so the UI shell never imports vendor types.
+ */
+
+interface EngineEvents {
+    /** Fires after `loadImage()` resolves. Carries the loaded dimensions. */
+    readonly imageLoaded: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Any operation that mutates the canvas (filter, crop, rotate, etc.). */
+    readonly imageChanged: void;
+    /** History stacks updated. Use `canUndo`/`canRedo` for current depth. */
+    readonly historyStateChanged: {
+        readonly canUndo: boolean;
+        readonly canRedo: boolean;
+    };
+    /**
+     * Fires whenever the image's transform state changes, from either
+     * direct mouse manipulation (corner / rotation handles) or a
+     * sidebar tool action (slider drag, flip button). The `source`
+     * field tells consumers which path produced the change so that
+     * tool components can decide whether to update bound display
+     * values without echoing back into the engine.
+     */
+    readonly imageTransformed: {
+        readonly angle: number;
+        readonly scaleX: number;
+        readonly scaleY: number;
+        readonly flipX: boolean;
+        readonly flipY: boolean;
+        readonly left: number;
+        readonly top: number;
+        readonly source: 'mouse' | 'sidebar';
+    };
+    /** A canvas object was activated (selected). */
+    readonly objectActivated: {
+        readonly objectType: string;
+    };
+    /** No object is currently selected. */
+    readonly objectDeactivated: void;
+    /**
+     * The layer stack changed — a shape / text layer was added,
+     * removed, reordered, or had its visibility / opacity toggled.
+     * Carries no payload: consumers re-pull `getLayers()`. (C.1)
+     */
+    readonly layersChanged: void;
+    /**
+     * The active (selected) layer changed — to another layer, or to
+     * none. `id` is the engine's stable layer id; `kind` lets the
+     * sidebar decide which style panel is relevant. Distinct from
+     * `objectActivated`, which predates the layer model and carries
+     * the raw fabric type only. (C.1)
+     */
+    readonly activeObjectChanged: {
+        readonly id: string | null;
+        readonly kind: LayerKind | null;
+    };
+    /**
+     * Raw pointer activity in SCENE coordinates (canvas space with the
+     * viewport zoom/pan factored out — the same space `getImageBounds()`
+     * and `getShapeGeometry()` report in). The annotation seam for
+     * consumers that implement their own draw-by-drag interactions
+     * (e.g. the ImageMap region authoring page): `down`->`move`->`up`
+     * drives rubber-band shapes, `dblclick` closes polygon paths.
+     * `targetLayerId` is the stamped layer under the pointer, or null
+     * on empty canvas / when hit-testing is disabled.
+     */
+    readonly scenePointer: {
+        readonly phase: 'down' | 'move' | 'up' | 'dblclick';
+        readonly x: number;
+        readonly y: number;
+        readonly targetLayerId: string | null;
+    };
+}
+type EngineEventType = keyof EngineEvents;
+type EngineEventHandler<T extends EngineEventType> = (data: EngineEvents[T]) => void;
+
+/**
+ * Engine contract for image manipulation.
+ *
+ * `FabricEngineAdapter` is the current implementation, built on
+ * fabric.js v6. The interface is the firewall between the UI shell
+ * and the rendering engine: a future implementation could target a
+ * different canvas library without touching consumers.
+ *
+ * Async semantics:
+ *   - All mutations return `Promise` so consumers can chain reliably
+ *     even when the underlying engine is partly synchronous.
+ *   - Read-only accessors (`canUndo`, `getCanvasSize`, etc.) are
+ *     synchronous because the engine's internal state is queryable
+ *     without a tick.
+ */
+interface ImageEditorEngine {
+    /**
+     * Load an image into the canvas. Replaces any existing content.
+     * Returns the loaded image's intrinsic dimensions.
+     */
+    loadImage(source: string | Blob, name?: string): Promise<Size>;
+    /**
+     * Roll back every change since the last `loadImage()`. Implemented
+     * via repeated `undo()` until the stack is empty rather than a
+     * separate "reset" semantic, so behaviour is consistent with the
+     * undo button in the UI.
+     */
+    reset(): Promise<void>;
+    /** Crop to the given rectangle (in canvas coordinates). */
+    crop(rect: Rect): Promise<void>;
+    /**
+     * Enter the engine's interactive crop UI: a draggable cropzone
+     * appears on the canvas and the user resizes / repositions it
+     * with the mouse. The actual crop operation only happens when
+     * `crop(rect)` is called against the rect returned by
+     * `getCropRect()`. Idempotent: a second call while already in
+     * crop mode is a no-op.
+     */
+    enterCropMode(): Promise<void>;
+    /**
+     * Exit the interactive crop UI without applying. The cropzone
+     * overlay is removed; the canvas state is unchanged.
+     */
+    exitCropMode(): Promise<void>;
+    /**
+     * Lock the cropzone to a fixed `width / height` ratio. `null`
+     * frees the cropzone (user can drag any rectangle). Only valid
+     * while in crop mode; outside crop mode this is a no-op.
+     */
+    setCropAspectRatio(ratio: number | null): void;
+    /**
+     * Read the current cropzone rectangle in canvas-space coordinates
+     * (the overlay's `getBoundingRect()` AABB, no viewport zoom or
+     * pan factored in). Returns `null` when not in crop mode or when
+     * the overlay has zero width or height.
+     */
+    getCropRect(): Rect | null;
+    /**
+     * Rotate by `degrees` (positive = clockwise). Targets the active
+     * non-image layer (shape / text) when one is selected, otherwise
+     * the base image (C.1c per-layer transforms).
+     */
+    rotate(degrees: number): Promise<void>;
+    /**
+     * Flip along the given axis. Targets the active non-image layer
+     * when one is selected, otherwise the base image (C.1c).
+     */
+    flip(axis: 'horizontal' | 'vertical'): Promise<void>;
+    /** Resize the canvas (and the loaded image) to `size`. */
+    resize(size: Size): Promise<void>;
+    /**
+     * Apply a filter. Idempotent: re-calling with new params updates
+     * the existing instance of that filter rather than stacking a new
+     * one. Parameter ranges are normalised — see FilterParams docblock.
+     */
+    applyFilter(name: FilterName, params?: FilterParams): Promise<void>;
+    /** Remove a previously-applied filter (no-op if not active). */
+    removeFilter(name: FilterName): Promise<void>;
+    /** True when the named filter is currently active. */
+    hasFilter(name: FilterName): boolean;
+    /**
+     * Add a shape, centred on the image, styled per `opts` (defaults
+     * fill in). The new shape becomes the active object.
+     */
+    addShape(kind: ShapeKind, opts?: Partial<ShapeOptions>): void;
+    /**
+     * Add an editable text box, centred on the image. The new text
+     * becomes the active object.
+     */
+    addText(opts?: Partial<TextOptions>): void;
+    /**
+     * The base image's scene-space bounding rect (the frame authored
+     * geometry is normalized against), or `null` before `loadImage()`.
+     */
+    getImageBounds(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Add a shape at explicit scene-space geometry (no centering).
+     * Becomes the active object; undoable like `addShape`. Returns the
+     * new layer's id so the caller can key its own metadata to it.
+     */
+    addShapeAt(geometry: ShapeGeometry, opts?: AnnotationShapeOptions): string;
+    /**
+     * Read a shape layer's current scene-space geometry, reflecting
+     * any interactive move / scale the user applied. Rects report the
+     * axis-aligned box (rotation is not representable — pair with
+     * `lockRotation`); ellipses report center + scaled radii; polygons
+     * report fully-transformed vertices. `null` for unknown ids, the
+     * base image, or non-shape layers.
+     */
+    getShapeGeometry(id: string): ShapeGeometry | null;
+    /**
+     * Toggle per-vertex editing on a POLYGON shape layer. While enabled
+     * the polygon's default scale/rotate handles are replaced by one
+     * draggable control per vertex (whole-shape dragging is locked so
+     * the vertices are the only interaction); a completed vertex drag
+     * is undoable like any other mutation. Disabling restores the
+     * default handles. Returns `false` (no-op) for unknown ids or
+     * non-polygon layers; enabling twice is idempotent.
+     */
+    setVertexEditing(id: string, enabled: boolean): boolean;
+    /**
+     * Set a layer's fill for a TRANSIENT preview tint (e.g. a live
+     * busy/free status overlay while authoring). Not undoable and not part
+     * of the shape's geometry, so it never affects what a save persists.
+     * Passing `null` restores the default annotation fill. No-op for the
+     * base image or an unknown id.
+     */
+    setLayerFill(id: string, fill: string | null): void;
+    /**
+     * Insert a new draggable vertex into the polygon `id` currently in
+     * vertex-edit mode, at the point on its outline NEAREST to the scene
+     * coordinate `(sceneX, sceneY)` — a collinear insert, so the polygon's
+     * shape is unchanged, it just gains a handle the author can then drag.
+     * The controls are rebuilt (re-indexed) and the insert is undoable.
+     * Returns `false` (no-op) if `id` is not the polygon currently in
+     * vertex-edit mode. Intended to be wired to a double-click on the
+     * outline while editing vertices.
+     */
+    addVertexAt(id: string, sceneX: number, sceneY: number): boolean;
+    /**
+     * Remove the vertex of the polygon `id` (currently in vertex-edit mode)
+     * NEAREST to the scene coordinate `(sceneX, sceneY)`, but only when the
+     * coordinate lands ON a vertex handle (within a fraction of the polygon's
+     * own size). The controls are rebuilt (re-indexed) and the removal is
+     * undoable. Returns `false` (no-op) if `id` is not the polygon in
+     * vertex-edit mode, if removing would drop below the 3-vertex minimum a
+     * polygon requires, OR if the coordinate is too far from any vertex — so
+     * a caller can route a double-click to this FIRST and fall through to
+     * {@link addVertexAt} (which projects onto the outline) when it returns
+     * `false`. Intended to be wired to a double-click on a vertex handle.
+     */
+    removeVertexAt(id: string, sceneX: number, sceneY: number): boolean;
+    /**
+     * The current layer stack, **top-most first** (so a Layers panel
+     * lists it the way every editor does). Always includes the base
+     * image as the last (bottom) entry.
+     */
+    getLayers(): LayerInfo[];
+    /** The active layer's id, or `null` when nothing is selected. */
+    getActiveLayerId(): string | null;
+    /** Select a layer by id (`null` clears selection). */
+    selectLayer(id: string | null): void;
+    /** Delete a shape / text layer (no-op for the locked base image). */
+    removeLayer(id: string): void;
+    /** Show / hide a layer. */
+    setLayerVisibility(id: string, visible: boolean): void;
+    /** Set a layer's opacity (0..1). */
+    setLayerOpacity(id: string, opacity: number): void;
+    /**
+     * Restack a layer. `up`/`down` move one step; `front`/`back` jump
+     * to the extremes. The base image is pinned to the bottom — other
+     * layers can't sink below it.
+     */
+    reorderLayer(id: string, direction: 'up' | 'down' | 'front' | 'back'): void;
+    /**
+     * Read the active object's editable style props (`fill`, `stroke`,
+     * `strokeWidth`, `opacity`, plus font props for text). Returns
+     * `null` when no object — or the base image — is selected.
+     */
+    getActiveObjectProps(): ObjectProps | null;
+    /**
+     * Apply style props to the active object (single undo command).
+     * No-op when nothing editable is selected.
+     */
+    updateActiveObject(props: ObjectProps): void;
+    /**
+     * Read the active object's fill as a UI-friendly {@link FillSpec},
+     * resolving a fabric `Gradient` back to mode + colour stops + angle
+     * so the style panels can round-trip a gradient on re-select.
+     * Returns `null` when no shape / text layer is selected. (C.1b)
+     */
+    getActiveObjectFill(): FillSpec | null;
+    /**
+     * Set the active object's fill from a {@link FillSpec}, building a
+     * fabric `Gradient` for the linear / radial modes (single undo
+     * command). No-op when nothing editable is selected. (C.1b)
+     */
+    setActiveObjectFill(spec: FillSpec): void;
+    /**
+     * The active non-image layer's rotation + flip state, so the
+     * Rotate / Flip tools can bind to the selected layer rather than
+     * the base image. Returns `null` when the base image — or nothing
+     * — is the active object (the tools fall back to image state).
+     */
+    getActiveLayerTransform(): {
+        angle: number;
+        flipX: boolean;
+        flipY: boolean;
+    } | null;
+    /**
+     * Clip the mask target to a shape (single undo command). The target
+     * is the active non-image layer when one is selected, otherwise the
+     * base image — so selecting a layer masks it, selecting nothing (or
+     * the Background) masks the photo. `shape: 'none'` clears the mask.
+     */
+    setMask(spec: MaskSpec): void;
+    /**
+     * Read the mask target's current {@link MaskSpec} so the Mask tool
+     * can seed its controls on (re)selection. Returns the default
+     * (`shape: 'none'`) when the target has no mask, or `null` when
+     * there is no target at all (no image loaded).
+     */
+    getMask(): MaskSpec | null;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /**
+     * Forget every entry currently in the redo stack.
+     *
+     * Used by the live-preview filter tools: each slider drag does an
+     * `undo()` followed by an `applyFilter()`, so the redo stack
+     * accumulates one stale entry per drag. Calling this on commit
+     * leaves the stack in the same shape it would have had if the
+     * user had jumped straight to the final value, with no preview
+     * cycle at all.
+     */
+    clearRedoStack(): void;
+    /**
+     * Whether the flattened render contains any transparency, so the
+     * save flow can force a PNG export instead of flattening a masked /
+     * transparent image onto an opaque (JPEG) background — which loses
+     * the cut-away region to opaque black (C.1d). True when the base
+     * image or any visible layer carries a mask (`clipPath`), or when
+     * the flattened pixels contain a non-opaque alpha value. Cheap for
+     * the masking case; scans pixels only as a fallback.
+     */
+    hasAlpha(): boolean;
+    /**
+     * Render the current canvas as a Blob. `format` defaults to 'png';
+     * `quality` (0..1) applies to lossy formats only.
+     */
+    export(format?: 'png' | 'jpeg' | 'webp', quality?: number): Promise<Blob>;
+    /**
+     * Synchronous data-URL export. Useful when the consumer needs the
+     * dataURL form directly (e.g., immediate <img src> assignment).
+     */
+    exportDataUrl(format?: 'png' | 'jpeg' | 'webp', quality?: number): string;
+    /** Current canvas dimensions. */
+    getCanvasSize(): Size;
+    /**
+     * Set the viewport zoom centred on the canvas. Pure rendering
+     * concern — does not modify image data, does not push to the
+     * undo stack. The exported bytes are independent of zoom level.
+     *
+     * `scale = 1` is 100% (one canvas pixel per CSS pixel). Values
+     * are clamped at the consumer level (the state service uses
+     * 0.1..5).
+     */
+    setZoom(scale: number): void;
+    /** Read the current viewport zoom. Returns 1 when at 100%. */
+    getZoom(): number;
+    /** Reset the viewport transform to the identity (zoom = 1, no pan). */
+    resetZoom(): void;
+    /**
+     * Pan the viewport by the given pixel deltas. Pure rendering;
+     * does not modify image data or push to undo. Used by the Hand
+     * tool's drag handler.
+     */
+    pan(dx: number, dy: number): void;
+    /** Current pan offset in viewport coordinates. */
+    getPanOffset(): Point;
+    /**
+     * Set the pan offset to the given absolute viewport translation,
+     * leaving the current zoom in place. Used by the state service
+     * to centre the scaled image inside the visible viewport after
+     * applying a new zoom factor.
+     */
+    setPanOffset(offset: Point): void;
+    /**
+     * Reset the pan offset to zero, leaving the current zoom in
+     * place. Distinct from `resetZoom()`, which clears both.
+     */
+    resetPan(): void;
+    /**
+     * Compute the zoom factor that fits the image into the given
+     * viewport rectangle, leaving a small margin so the image edges
+     * stay visible. Not clamped: small images upscale to fit the
+     * viewport, large images shrink to fit. The adapter computes
+     * from image dimensions vs viewport dimensions directly.
+     */
+    getFitZoom(viewportSize: Size): number;
+    /**
+     * Set the canvas cursor. fabric.js owns its own cursor state
+     * (defaultCursor / hoverCursor / moveCursor) independent of DOM
+     * CSS, so a `cursor: grab` rule on the host element is silently
+     * overridden by fabric's defaults. Used by the Hand tool to
+     * surface grab / grabbing.
+     */
+    setCursor(cursor: 'default' | 'grab' | 'grabbing' | 'crosshair'): void;
+    /**
+     * Toggle fabric's group-selection rectangle and object hit
+     * detection. Disabled when the Hand tool is active so a drag on
+     * empty canvas pans instead of drawing a marquee, and so pointer
+     * events don't get sniped by hit-tests against canvas objects.
+     */
+    setSelectionEnabled(enabled: boolean): void;
+    /**
+     * Set the canvas backstore + display dimensions to the given
+     * viewport. Owning canvas size in the adapter (rather than
+     * inheriting from a vendor's CSS auto-fit layer) is what makes
+     * viewport zoom the single, predictable scale knob: small
+     * images can upscale to fill the viewport without being clipped
+     * by the canvas backstore, and large images shrink through the
+     * same setZoom path. Recenters the loaded image on the resized
+     * canvas.
+     */
+    setCanvasDimensions(viewport: Size): void;
+    on<T extends EngineEventType>(event: T, handler: EngineEventHandler<T>): void;
+    off<T extends EngineEventType>(event: T, handler?: EngineEventHandler<T>): void;
+    /** Tear down the engine and free its DOM/canvas resources. */
+    destroy(): void;
+    /**
+     * Direct access to the underlying canvas element. Escape hatch for
+     * shells that need to hit the DOM API directly (pixel sampling,
+     * pointer-event hookup, etc.). Most shells should not need this.
+     */
+    readonly canvasElement: HTMLCanvasElement | null;
+}
+
+interface FabricEngineCreateOptions {
+    container: HTMLElement;
+}
+/**
+ * fabric.js v7 adapter for the CoolMS image editor.
+ *
+ * Mounts a fresh `<canvas>` element inside the consumer-provided
+ * container and takes ownership of canvas backstore + CSS dimensions
+ * so viewport zoom is the single source of truth for visual scale.
+ * No vendor CSS auto-fit layer in front of fabric, so small images
+ * (sub-viewport) zoom predictably and large images shrink-to-fit
+ * through the same `setZoom` path.
+ *
+ * fabric 7 flipped the FabricObject default origin from 'left'/'top'
+ * (v6) to 'center'/'center'. The crop overlay's `bounds.left/top`
+ * positioning math assumes 'left'/'top' semantics, and we keep
+ * `image.left/image.top` referring to the visual top-left corner so
+ * the snapshot/restore captureTransform path stays a no-op. Image
+ * and crop-overlay constructors below pass explicit `originX: 'left',
+ * originY: 'top'` to preserve v6 behavior bit-for-bit. The frame
+ * overlay mirrors `image.originX/originY` so it follows whatever the
+ * image uses.
+ *
+ * Use `FabricEngineAdapter.create(options)` rather than `new`. The
+ * factory wires up the canvas element and seeds initial dimensions
+ * from the container's measured size.
+ */
+declare class FabricEngineAdapter implements ImageEditorEngine {
+    private static readonly TOGGLE_FILTERS;
+    private static readonly SLIDER_FILTERS;
+    private readonly canvas;
+    private readonly canvasEl;
+    private readonly container;
+    /** The default annotation-shape fill; `setLayerFill(id, null)` restores it. */
+    private static readonly DEFAULT_SHAPE_FILL;
+    private readonly listeners;
+    private readonly commandStack;
+    private image;
+    private vertexEdit;
+    private originalSource;
+    private cropOverlay;
+    private frameOverlay;
+    private mouseTransformSnapshot;
+    /** Monotonic id source for shape / text layers. */
+    private nextLayerId;
+    /**
+     * Transform snapshot for a non-image object captured on
+     * `mouse:down`, so `object:modified` can build the inverse for
+     * undo (mirrors `mouseTransformSnapshot` but for shapes / text).
+     */
+    private objTransformSnapshot;
+    private constructor();
+    /**
+     * Build an adapter against the given container element. Creates a
+     * `<canvas>` child sized to the container and constructs a fabric
+     * Canvas around it.
+     */
+    static create(options: FabricEngineCreateOptions): Promise<FabricEngineAdapter>;
+    loadImage(source: string | Blob, name?: string): Promise<Size>;
+    reset(): Promise<void>;
+    crop(canvasSpaceRect: Rect): Promise<void>;
+    enterCropMode(): Promise<void>;
+    exitCropMode(): Promise<void>;
+    /** Toggle selectability of the annotation layers (used by crop mode). */
+    private setLayersInteractive;
+    setCropAspectRatio(ratio: number | null): void;
+    getCropRect(): Rect | null;
+    rotate(degrees: number): Promise<void>;
+    flip(axis: 'horizontal' | 'vertical'): Promise<void>;
+    resize(size: Size): Promise<void>;
+    applyFilter(name: FilterName, params?: FilterParams): Promise<void>;
+    removeFilter(name: FilterName): Promise<void>;
+    hasFilter(name: FilterName): boolean;
+    addShape(kind: ShapeKind, opts?: Partial<ShapeOptions>): void;
+    addText(opts?: Partial<TextOptions>): void;
+    getImageBounds(): Rect | null;
+    addShapeAt(geometry: ShapeGeometry, opts?: AnnotationShapeOptions): string;
+    getShapeGeometry(id: string): ShapeGeometry | null;
+    setVertexEditing(id: string, enabled: boolean): boolean;
+    /**
+     * Swap the polygon's default handles for one draggable Control per
+     * vertex — the official fabric "custom polygon controls" pattern:
+     * `positionHandler` projects `points[i]` through viewport × object
+     * transform; `actionHandler` writes the pointer back into
+     * `points[i]` (object-local, stroke-compensated) and re-anchors the
+     * polygon on a neighbouring vertex after `setDimensions()` so the
+     * shape doesn't jump while its bounding box is recomputed.
+     */
+    private enterVertexEdit;
+    private exitVertexEdit;
+    private vertexControlPosition;
+    private moveVertex;
+    /**
+     * (Re)build one draggable Control per vertex — used on entering vertex
+     * edit AND after a topology change (add/remove) so the `vertexN` controls
+     * stay index-aligned with the current `points` array.
+     */
+    private rebuildVertexControls;
+    addVertexAt(id: string, sceneX: number, sceneY: number): boolean;
+    removeVertexAt(id: string, sceneX: number, sceneY: number): boolean;
+    /** Closest point on segment `a->b` to `p` (all object-local coords). */
+    private projectOnSegment;
+    /**
+     * Replace the polygon's `points` and re-index its vertex controls,
+     * keeping one SURVIVING vertex visually fixed across the
+     * `setDimensions()` bbox recompute so the shape never jumps.
+     *
+     * `fromIndex` is the anchor vertex's index in the CURRENT points,
+     * `toIndex` its index in the NEW `pts` — the two must be the SAME
+     * vertex. For an insert (add) or the identity case both are 0 (the
+     * defaults). A removal that drops vertex 0 shifts every later vertex
+     * down one, so its surviving anchor lives at different indices before
+     * vs after — hence the explicit pair.
+     */
+    private applyVertexTopology;
+    private polygonSizeWithStroke;
+    private vertexDragStart;
+    private vertexDragEnd;
+    getLayers(): LayerInfo[];
+    getActiveLayerId(): string | null;
+    selectLayer(id: string | null): void;
+    setLayerFill(id: string, fill: string | null): void;
+    removeLayer(id: string): void;
+    setLayerVisibility(id: string, visible: boolean): void;
+    setLayerOpacity(id: string, opacity: number): void;
+    reorderLayer(id: string, direction: 'up' | 'down' | 'front' | 'back'): void;
+    getActiveObjectProps(): ObjectProps | null;
+    getActiveObjectFill(): FillSpec | null;
+    setActiveObjectFill(spec: FillSpec): void;
+    getActiveLayerTransform(): {
+        angle: number;
+        flipX: boolean;
+        flipY: boolean;
+    } | null;
+    setMask(spec: MaskSpec): void;
+    getMask(): MaskSpec | null;
+    updateActiveObject(props: ObjectProps): void;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    clearRedoStack(): void;
+    export(format?: 'png' | 'jpeg' | 'webp', quality?: number): Promise<Blob>;
+    exportDataUrl(format?: 'png' | 'jpeg' | 'webp', quality?: number): string;
+    hasAlpha(): boolean;
+    /** True when `obj` carries a fabric `clipPath` (a mask). */
+    private objectHasClip;
+    /**
+     * Render the base image plus every visible annotation layer into a
+     * single bitmap (the export-time flatten). With no annotations the
+     * fast path returns the image baked at its own resolution; with
+     * annotations we composite each object onto a canvas sized to the
+     * image's bounding box, offsetting every object by its position
+     * relative to the image (both in canvas-space px, multiplier 1).
+     *
+     * C.1 keeps transforms whole-image, so the common authoring flow
+     * (edit pixels -> annotate -> save) lands annotations at full
+     * resolution; a base image the user manually scaled with handles
+     * exports at its displayed size (a documented limitation).
+     */
+    private renderFlattened;
+    getCanvasSize(): Size;
+    setZoom(scale: number): void;
+    getZoom(): number;
+    resetZoom(): void;
+    pan(dx: number, dy: number): void;
+    getPanOffset(): Point;
+    setPanOffset(offset: Point): void;
+    resetPan(): void;
+    getFitZoom(viewportSize: Size): number;
+    setCursor(cursor: 'default' | 'grab' | 'grabbing' | 'crosshair'): void;
+    setSelectionEnabled(enabled: boolean): void;
+    setCanvasDimensions(viewport: Size): void;
+    on<T extends EngineEventType>(event: T, handler: EngineEventHandler<T>): void;
+    off<T extends EngineEventType>(event: T, handler?: EngineEventHandler<T>): void;
+    destroy(): void;
+    get canvasElement(): HTMLCanvasElement | null;
+    private requireImage;
+    /**
+     * Add a thin orange rectangle that mirrors the image's transform
+     * so the user can see exactly where the image edge is against the
+     * dark canvas background. Sent to the back so the image renders
+     * on top of the inner half of the stroke; the outer half stays
+     * visible just outside the image bounds. `strokeWidth = 2 / zoom`
+     * keeps that outer band a constant 1 visual pixel regardless of
+     * viewport zoom. Excluded from export by both convention and
+     * construction: our `export` / `exportDataUrl` paths render only
+     * the FabricImage object, not the canvas.
+     */
+    private addFrameOverlay;
+    /**
+     * Refresh the frame to mirror the image's current transform and
+     * keep the stroke at a constant 1 visual pixel. Called whenever
+     * the image moves, scales, rotates, or flips, and after viewport
+     * zoom changes (since the latter only matters for the stroke
+     * width). Hidden frame stays hidden but its geometry still
+     * updates so the next show is in sync.
+     */
+    private syncFrameOverlay;
+    private removeFrameOverlay;
+    /**
+     * Install a new FabricImage as the active image after a crop or
+     * resize replacement. Adds it to the canvas, centers it in canvas
+     * coordinates, drops any leftover viewport zoom/pan from the
+     * previous image (otherwise the new, smaller image lands
+     * off-screen because the user was zoomed into the corner of the
+     * old one), and re-emits `imageLoaded` so consumers refit the
+     * view to the new dimensions.
+     */
+    private replaceImage;
+    /**
+     * Make sure fabric's WebGL filter backend has a GL canvas large
+     * enough to hold the image's full pixel area. Fabric defaults
+     * `config.textureSize` to 4096 and constructs a 4096×4096 GL
+     * canvas; rendering a 4608×3456 image into that backend leaves
+     * a ~512 px right-edge band un-rendered (the WebGL viewport is
+     * set to image dims but the GL canvas can't hold them), which
+     * `copyGLTo2D` then reads as transparent. That surfaced as the
+     * right-side crop the user reported on Sharpen.
+     *
+     * Fix: bump `config.textureSize` to the next power-of-two that
+     * fits the image, capped at 16384, then drop the cached backend
+     * so `getFilterBackend()` re-initialises with the new tile size.
+     * The probe inside `initFilterBackend` falls back to the Canvas2D
+     * backend automatically if the GPU can't support the new size,
+     * so this is safe on low-end hardware.
+     */
+    private ensureFilterBackendFitsImage;
+    private pushCommand;
+    private resolveFilterCtor;
+    private instantiateFilter;
+    private attachVendorListeners;
+    private captureTransform;
+    private transformsEqual;
+    private emitImageTransformed;
+    /** A filled right-pointing arrow, drawn as a single polygon. */
+    private static readonly ARROW_POINTS;
+    private createShape;
+    /** A fabric fill value: a flat colour string or a `Gradient`. */
+    private resolveFill;
+    /**
+     * Build a fabric solid colour or `Gradient` from a {@link FillSpec}.
+     * Gradients use `gradientUnits: 'percentage'`, so coords are 0..1 of
+     * the object's bounding box (origin top-left) and the gradient
+     * tracks the object through resize / text reflow — fabric applies
+     * `ctx.transform(width, 0, 0, height, …)` at paint time, including
+     * the `toCanvasElement` flatten the export composites.
+     */
+    private buildFill;
+    /** Resolve a fabric fill (string or `Gradient`) back to a {@link FillSpec}. */
+    private readFill;
+    /** Best-effort solid-colour hex for the generic prop bag (gradients collapse to their first stop). */
+    private fillToHex;
+    private isGradient;
+    /** Coerce a colour-stop value to an `<input type=color>`-safe 6-digit hex. */
+    private colorStopHex;
+    private shapeLabel;
+    /**
+     * Centre `obj` on the image, stamp it as a layer, add + select it,
+     * and push an add/remove undo command. Shared by addShape/addText.
+     */
+    private placeAndAdd;
+    private stampLayer;
+    /** Every stamped layer object on the canvas (base image + extras). */
+    private layerObjects;
+    /** Drop every non-image layer (used by load / reset). */
+    private removeLayerObjects;
+    private findLayer;
+    private layerId;
+    private layerKind;
+    private layerName;
+    /** Keep the base image pinned to the canvas floor (z-index 0). */
+    private keepImageAtBack;
+    /** Notify consumers a layer changed + re-broadcast the active layer. */
+    private afterLayerMutation;
+    private emitActiveFromCanvas;
+    private captureObjectState;
+    /**
+     * The active object when it's a selectable shape / text layer (not
+     * the base image, not nothing). The rotate / flip / mask targeting
+     * keys off this: a non-null result means "operate on this layer".
+     */
+    private activeNonImageLayer;
+    /**
+     * The mask target: the active non-image layer if one is selected,
+     * else the base image (which may be `null` before any load).
+     */
+    private maskTarget;
+    private rotateLayer;
+    private flipLayer;
+    /**
+     * Build a fabric `clipPath` for `spec` against `target`'s own box.
+     * The clip is centred on the object (originX/Y = 'center', left/top
+     * = 0): fabric renders clipPaths in the object's centred local space
+     * before applying the object's own scale, so the mask tracks the
+     * object through scale / move and bakes into `toCanvasElement`.
+     * Returns `null` for `shape: 'none'` (clears the mask).
+     */
+    private buildClipPath;
+    /**
+     * Build a `Path` clip from raw SVG path `d` data, scaling its
+     * bounding box to the `cw × ch` clip box (centred via `common`).
+     * Shared by the built-in path presets and arbitrary `custom` masks
+     * (C.1d) — fabric computes the path's intrinsic bbox, and the
+     * `scaleX/Y` maps it onto the target's clip box, so any path tracks
+     * scale / move and bakes into `toCanvasElement` like the presets.
+     * Returns `null` for empty / unparseable data (clears the mask).
+     */
+    private buildPathClip;
+    private emit;
+}
+
+/**
+ * Construction options for any `ImageEditorEngine`. The container is
+ * required; everything else is optional with sensible defaults.
+ *
+ * No engine-specific knobs leak into this shape — Toast-UI-only
+ * options (selectionStyle borderColor etc.) belong on a Toast-UI-only
+ * sub-options bag if a future shell needs to thread them through. For
+ * MVP, the defaults are enough.
+ */
+interface EngineOptions {
+    /** DOM element the engine mounts its canvas into. */
+    readonly container: HTMLElement;
+    /** Initial canvas size. Defaults to the container's measured size. */
+    readonly initialSize?: Size;
+    /** Display-side cap for canvas width in CSS pixels. */
+    readonly cssMaxWidth?: number;
+    /** Display-side cap for canvas height in CSS pixels. */
+    readonly cssMaxHeight?: number;
+    /**
+     * Toast UI's anonymised usage telemetry. Off by default; flip true
+     * only with explicit user consent.
+     */
+    readonly usageStatistics?: boolean;
+}
+
+/**
+ * Lifecycle states the shell renders against.
+ *
+ * `uninitialized` — fresh service instance, no engine yet.
+ * `loading`       — engine creation or initial image load is in flight.
+ * `ready`         — engine is mounted and the image is on the canvas.
+ * `error`         — engine creation or initial load failed; `errorMessage`
+ *                   holds the user-facing reason.
+ */
+type EditorState = 'uninitialized' | 'loading' | 'ready' | 'error';
+/**
+ * Shared editor state for the in-tree shell.
+ *
+ * Scoped to the `CoolmsImageEditorComponent` instance via that
+ * component's `providers` array, so opening two editors at once would
+ * give each one its own engine, history flags, and active-tool slot.
+ *
+ * Kept deliberately thin: signals + the methods that mutate them. Tool
+ * implementations in beta.4 reach the engine through `engine()` rather
+ * than threading domain logic through this service.
+ */
+declare class ImageEditorStateService {
+    private readonly engineInstance;
+    readonly state: _angular_core.WritableSignal<EditorState>;
+    readonly canvasSize: _angular_core.WritableSignal<Size | null>;
+    readonly canUndo: _angular_core.WritableSignal<boolean>;
+    readonly canRedo: _angular_core.WritableSignal<boolean>;
+    /** Tool ID set by the right-sidebar picker. beta.3 leaves this null. */
+    readonly activeTool: _angular_core.WritableSignal<string | null>;
+    readonly errorMessage: _angular_core.WritableSignal<string | null>;
+    /**
+     * Viewport zoom level, where 1.0 = 100%. Mirrors the engine's
+     * canvas zoom; mutated through `zoomIn` / `zoomOut` / `resetZoom` /
+     * `setZoom`, never directly by consumers (the value here must
+     * stay in lockstep with what the engine actually rendered).
+     */
+    readonly currentZoom: _angular_core.WritableSignal<number>;
+    /**
+     * Fit-to-viewport zoom — the scale at which the loaded image
+     * fills the canvas-mount (with a small margin). Calculated by
+     * the canvas-mount component once it has measured its viewport,
+     * and re-calculated on container resize. Used as the target for
+     * `resetZoom()` and the full `reset()` so "back to 100%" lands
+     * the user at the same view they saw on first mount.
+     */
+    readonly fitZoom: _angular_core.WritableSignal<number>;
+    /**
+     * Hand-tool toggle. When true, mouse-down + drag on the canvas
+     * pans the viewport instead of doing nothing. The cursor swaps
+     * to grab / grabbing via canvas-mount's class bindings.
+     */
+    readonly handToolActive: _angular_core.WritableSignal<boolean>;
+    readonly imageRotation: _angular_core.WritableSignal<number>;
+    readonly imageScaleX: _angular_core.WritableSignal<number>;
+    readonly imageScaleY: _angular_core.WritableSignal<number>;
+    readonly imageFlipX: _angular_core.WritableSignal<boolean>;
+    readonly imageFlipY: _angular_core.WritableSignal<boolean>;
+    readonly imagePosition: _angular_core.WritableSignal<{
+        x: number;
+        y: number;
+    }>;
+    /**
+     * The layer stack (top-most first), mirrored from the engine's
+     * `layersChanged` event. The Layers panel binds to this. (C.1)
+     */
+    readonly layers: _angular_core.WritableSignal<LayerInfo[]>;
+    /** Active layer id, mirrored from `activeObjectChanged`. (C.1) */
+    readonly activeLayerId: _angular_core.WritableSignal<string | null>;
+    /** Active layer kind, so style panels know which controls apply. (C.1) */
+    readonly activeLayerKind: _angular_core.WritableSignal<LayerKind | null>;
+    /**
+     * The active non-image layer's transform, mirrored from the engine
+     * (C.1c). The Rotate / Flip tools read these via the
+     * `transformTarget*` computeds so a selected shape / text layer is
+     * the transform target instead of the base image.
+     */
+    readonly activeLayerAngle: _angular_core.WritableSignal<number>;
+    readonly activeLayerFlipX: _angular_core.WritableSignal<boolean>;
+    readonly activeLayerFlipY: _angular_core.WritableSignal<boolean>;
+    /** True when a non-image layer (not the Background) is the active object. */
+    private readonly targetingLayer;
+    /**
+     * The rotation / flip the Rotate + Flip tools bind to: the selected
+     * non-image layer's when one is active, else the base image's. (C.1c)
+     */
+    readonly transformTargetRotation: _angular_core.Signal<number>;
+    readonly transformTargetFlipX: _angular_core.Signal<boolean>;
+    readonly transformTargetFlipY: _angular_core.Signal<boolean>;
+    /**
+     * Image scale as a percentage rounded to a whole number. Uses the
+     * absolute scale value so a horizontally-flipped image at scale
+     * -1 reads as 100%, not -100%. Flip is reported separately.
+     */
+    readonly imageScalePercent: _angular_core.Signal<number>;
+    /** Read-only handle the toolbar and tools use to drive the engine. */
+    readonly engine: _angular_core.Signal<ImageEditorEngine | null>;
+    readonly isReady: _angular_core.Signal<boolean>;
+    /**
+     * Create the engine, load the image, and attach the listeners that
+     * keep the history-state signals in sync. Throws (and flips state to
+     * 'error') if either step fails — the shell surfaces the message
+     * through the canvas-mount overlay.
+     *
+     * The 'uninitialized' guard is what makes the service safe to call
+     * from `ngAfterViewInit`: a re-entrant call (e.g. after a hot
+     * module replace cycle in dev) is a no-op rather than a duplicate
+     * mount.
+     */
+    initializeEngine(container: HTMLElement, sourceUrl: string, filename: string): Promise<void>;
+    /**
+     * Tear down the engine and reset every signal to its starting
+     * state. Idempotent so the host can call it from `ngOnDestroy`
+     * without checking `state()` first.
+     */
+    destroyEngine(): void;
+    setActiveTool(toolId: string | null): void;
+    /**
+     * Refresh the cached canvas dimensions after an in-place
+     * operation that the engine doesn't proactively re-measure for
+     * us (Resize tool's primary use). Engine load + initial mount
+     * still write through `initializeEngine`.
+     */
+    updateCanvasSize(size: Size): void;
+    /**
+     * Viewport zoom controls. Clamped 0.05..10 (5%..1000%) — wide
+     * range to accommodate fit-zoom for very large images (a 8000px
+     * image in a 600px viewport fits at ~7%) and the occasional
+     * pixel-peeping zoom-in on small images. Step factor of 1.25
+     * matches the convention used by Photoshop, Affinity, and most
+     * desktop image editors.
+     */
+    private static readonly ZOOM_MIN;
+    private static readonly ZOOM_MAX;
+    private static readonly ZOOM_STEP;
+    setZoom(scale: number): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    resetZoom(): void;
+    /**
+     * Compute and apply the fit-to-viewport zoom for the currently
+     * loaded image. Called by canvas-mount after the engine emits
+     * `imageLoaded` and on container resize. The fabric adapter
+     * owns canvas dimensions, so the returned fit factor drives the
+     * viewport zoom directly (small images upscale beyond 1.0 to
+     * fill the viewport, large images shrink below 1.0 to fit).
+     */
+    applyFitZoom(viewportSize: Size): void;
+    /**
+     * Update the cached fit zoom without touching the live view.
+     * Used by the resize observer so a window resize while the
+     * user has manually zoomed in doesn't yank them back to fit
+     * mid-edit; the next Reset / "%" click picks up the fresh
+     * value instead.
+     */
+    recalculateFitZoom(viewportSize: Size): void;
+    toggleHandTool(): void;
+    /**
+     * Top-toolbar Reset button entry point. Restores the canvas to
+     * the pristine loaded state in one call:
+     *   - any active tool is closed (its `ngOnDestroy` runs the
+     *     tool's deactivation, e.g. `exitCropMode` for the cropper);
+     *   - the Hand tool is deactivated;
+     *   - the engine reloads the original image and clears both
+     *     undo and redo stacks;
+     *   - the viewport pan offset is zeroed and the zoom is set to
+     *     the fit-to-viewport value (matches what the user saw on
+     *     first mount, not the raw 1.0× that would shrink large
+     *     images).
+     *
+     * The order matters: tool deactivation first so a mid-edit
+     * cropper doesn't try to re-render against a stale canvas while
+     * the engine is reloading the original image.
+     */
+    reset(): Promise<void>;
+    private attachEngineListeners;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ImageEditorStateService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ImageEditorStateService>;
+}
+
+/**
+ * Three-pane shell for the CoolMS image editor.
+ *
+ * Composition: top toolbar (action commands + size badge), canvas
+ * mount (centre / left, fills remaining space), right sidebar (tool
+ * picker placeholder, 320 px). The footer (Save / Save as / Cancel)
+ * lives in the host component so the shell can later be embedded in
+ * non-dialog contexts (inline editing, side panels) where the save
+ * flow looks different.
+ *
+ * The shell owns engine lifecycle through `ImageEditorStateService`,
+ * which is provided locally so each shell instance has its own state.
+ * `engineReady` fires once the image is loaded so the host can wire up
+ * its save action against a known-good engine handle.
+ *
+ * Ordering note on `ngAfterViewInit`: the canvas-mount child uses
+ * `static: true` for its container ViewChild, so by the time this
+ * component's `ngAfterViewInit` runs the inner `<div #container>`
+ * exists. The engine adapter is created against that element and the
+ * image is loaded before `engineReady` emits — consumers never see
+ * an unloaded engine.
+ */
+declare class CoolmsImageEditorComponent implements AfterViewInit, OnDestroy {
+    sourceUrl: _angular_core.InputSignal<string>;
+    sourceFilename: _angular_core.InputSignal<string>;
+    /** Fires after the engine is created and the initial image has loaded. */
+    readonly engineReady: _angular_core.OutputEmitterRef<ImageEditorEngine>;
+    /**
+     * Fires if engine creation or initial load throws.
+     *
+     * `failed`, not `error`: an output named after a native DOM event is
+     * ambiguous in a template -- `(error)` could bind either, and which one
+     * wins is not visible to whoever reads the template.
+     */
+    readonly failed: _angular_core.OutputEmitterRef<Error>;
+    protected readonly state: ImageEditorStateService;
+    private readonly canvasMount;
+    /**
+     * Tracks teardown so an engine that finishes loading after the host
+     * dialog has already been dismissed gets cleaned up promptly. Without
+     * this guard a slow `loadImage` could leave an orphan canvas in the
+     * DOM after `ngOnDestroy`.
+     */
+    private destroyed;
+    constructor();
+    /**
+     * Public escape hatch the host calls before `engine.export()` to
+     * make sure no tool is mid-edit (e.g., user forgot to Apply a
+     * crop). Setting `activeTool` to `null` destroys the properties
+     * component, whose `ngOnDestroy` runs the tool's deactivation
+     * (e.g., `exitCropMode()`) — so the export captures clean canvas
+     * pixels with no overlay.
+     *
+     * The adapter's `exportDataUrl()` also defensively calls
+     * `stopDrawingMode()`, but doing it here too makes the
+     * higher-level intent obvious in the host's save flow.
+     */
+    deactivateActiveTool(): void;
+    /**
+     * Public hook the host calls after an intentional dialog size
+     * change (fullscreen toggle). Delegates to the canvas mount which
+     * re-syncs the fabric canvas dimensions, recalculates fit zoom,
+     * and re-applies it so the image stays centred. The
+     * ResizeObserver inside canvas-mount stays conservative for
+     * casual window resizes (preserves manual zoom).
+     */
+    refit(): void;
+    ngAfterViewInit(): Promise<void>;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CoolmsImageEditorComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CoolmsImageEditorComponent, "coolms-image-editor", never, { "sourceUrl": { "alias": "sourceUrl"; "required": true; "isSignal": true; }; "sourceFilename": { "alias": "sourceFilename"; "required": true; "isSignal": true; }; }, { "engineReady": "engineReady"; "failed": "failed"; }, never, never, true, never>;
+}
+
+/**
+ * Wire-shape types for the CDK Dialog host.
+ *
+ * Discriminated union (`context: 'media' | 'vfs'`) so the host's
+ * save flow can route to the correct backend endpoint without the
+ * caller having to know which one. Each branch carries exactly the
+ * fields that branch needs:
+ *
+ *   - **Media context** — the asset is a registered `MediaAsset`,
+ *     so save flows through Media's APIs (`POST /media/{id}/replace`
+ *     for overwrite, `POST /media/upload` for save-as-new). The
+ *     asset's `path` carries the VFS location; we derive the parent
+ *     directory from it for the save-as-new target.
+ *
+ *   - **VFS context** — the file is a plain VFS file with no
+ *     MediaAsset record (e.g., a theme asset, a template image).
+ *     Save flows through VFS's binary endpoint
+ *     (`POST /vfs/files/binary`). `canWrite` gates the Save button:
+ *     read-only files allow Save as (creates a new file in the
+ *     parent directory) but not Save (would overwrite the source).
+ */
+type CoolmsImageEditorHostData = CoolmsImageEditorMediaContext | CoolmsImageEditorVfsContext;
+interface CoolmsImageEditorMediaContext {
+    readonly context: 'media';
+    readonly asset: {
+        /** Maps to `MediaAsset.id`; backend resolves the VFS node from it. */
+        readonly uuid: string;
+        /** Source URL the engine loads via `loadImage(url)`. */
+        readonly originalUrl: string;
+        /** Display label in the dialog header and default save-as filename. */
+        readonly filename: string;
+        /** Picks the export format (source MIME wins per the existing contract). */
+        readonly mimeType: string;
+        /**
+         * Materialised VFS path of the asset (e.g., `/media/uploads/photo.jpg`).
+         * The save-as-new flow derives the target directory from this — the
+         * new asset lands in the same collection as the source. Optional
+         * because `MediaAssetDto.path` can be null for fresh upload responses;
+         * callers set this when they have it (the editor falls back to
+         * `/media/uploads` when absent).
+         */
+        readonly path?: string | null;
+        /** Pre-load dimensions surfaced in the header before the engine reports its own. */
+        readonly dimensions: {
+            readonly width: number;
+            readonly height: number;
+        } | null;
+    };
+    /** BCP-47 locale; held for future locale work, beta.X doesn't read it. */
+    readonly locale?: string;
+}
+interface CoolmsImageEditorVfsContext {
+    readonly context: 'vfs';
+    readonly node: {
+        /** Absolute VFS path of the file. */
+        readonly path: string;
+        /** Caller's effective write permission on the file (mirrors `VfsNodeDto.permissions.write`). */
+        readonly canWrite: boolean;
+        /** URL the engine loads via `loadImage(url)`. */
+        readonly sourceUrl: string;
+        /** Display label in the dialog header and default save-as filename. */
+        readonly filename: string;
+        /** Picks the export format. */
+        readonly mimeType: string;
+        /** Parent directory; the save-as-new flow joins `${parentPath}/${newName}`. */
+        readonly parentPath: string;
+        /** Optional dimensions; null when not available pre-load. */
+        readonly dimensions?: {
+            readonly width: number;
+            readonly height: number;
+        } | null;
+    };
+}
+type CoolmsImageEditorHostResult = {
+    readonly kind: 'cancelled';
+} | {
+    readonly kind: 'saved';
+    readonly mode: 'overwrite' | 'save_as_new';
+    /** Set on the Media context. */
+    readonly assetUuid?: string;
+    /** Set on the VFS context. */
+    readonly vfsPath?: string;
+};
+
+type HostState = 'preparing' | 'editing' | 'saving' | 'error';
+/**
+ * CDK Dialog host wrapping `CoolmsImageEditorComponent`.
+ *
+ * Save flow (discriminated context):
+ *
+ *   Media context:
+ *     Save  -> OverwriteConfirm -> POST /api/v1/media/{id}/replace
+ *     SaveAs -> SaveAs prompt   -> POST /api/v1/vfs/files/binary (new file under
+ *                               the source collection; auto-promoted to an asset)
+ *
+ *   VFS context:
+ *     Save  -> OverwriteConfirm -> POST /api/v1/vfs/files/binary (overwrite=true)
+ *     SaveAs -> SaveAs prompt   -> POST /api/v1/vfs/files/binary (overwrite=false)
+ *
+ *   Cancel -> close with `{ kind: 'cancelled' }` in either context.
+ *
+ * Save button gating: in the VFS context, `canWrite=false` disables
+ * Save (overwriting a read-only file would 403 anyway) but Save as
+ * stays enabled — the user can always save a copy if they have
+ * write permission on the parent directory.
+ *
+ * Failures stay non-fatal: the dialog stays open with state set back
+ * to `editing` so the author can retry, and a toast carries a
+ * descriptive message (status code -> friendly label, or `.message`
+ * fallback). The engine remains live throughout.
+ */
+declare class CoolmsImageEditorHostComponent implements OnInit, OnDestroy {
+    private readonly cdkDialog;
+    private readonly dialogRef;
+    private readonly editService;
+    private readonly toast;
+    private readonly http;
+    private readonly esc;
+    private readonly confirm;
+    private readonly unsaved;
+    private readonly destroyRef;
+    protected readonly data: CoolmsImageEditorHostData;
+    readonly state: _angular_core.WritableSignal<HostState>;
+    readonly errorMessage: _angular_core.WritableSignal<string | null>;
+    /**
+     * Object URL fed into the embedded shell. Resolved asynchronously in
+     * `ngOnInit`: VFS sources go through HttpClient (so the auth interceptor
+     * attaches the Bearer token) and become a `blob:` URL the engine can
+     * load via a regular `<img>` element. Media sources are public, so the
+     * original URL passes through unchanged.
+     */
+    readonly resolvedSourceUrl: _angular_core.WritableSignal<string | null>;
+    /** Tracks the blob: URL we own so `ngOnDestroy` can revoke it. */
+    private ownedObjectUrl;
+    /**
+     * Captured the moment the shell finishes loading the image. Save
+     * actions check this through the `engineReadyOk` signal so the
+     * Save buttons only enable once an engine handle is available.
+     */
+    private engine;
+    private readonly shell?;
+    readonly engineReadyOk: _angular_core.WritableSignal<boolean>;
+    readonly isSaving: _angular_core.Signal<boolean>;
+    /** Save (overwrite) is gated on engine readiness AND, for VFS context, write permission. */
+    readonly canSave: _angular_core.Signal<boolean>;
+    /** Save as is gated only on engine readiness — even read-only sources can be saved as new. */
+    readonly canSaveAs: _angular_core.Signal<boolean>;
+    readonly canClose: _angular_core.Signal<boolean>;
+    /** Filename header label and default save-as name. */
+    readonly filename: _angular_core.Signal<string>;
+    /** Source MIME, drives export format. */
+    readonly mimeType: _angular_core.Signal<string>;
+    readonly dimensionsLabel: _angular_core.Signal<string>;
+    /**
+     * CSS-only fullscreen mode, mirroring viewer-modal's pattern.
+     * Toggle from the header button or by dblclicking a non-interactive
+     * area of the host. ESC exits fullscreen via the EscCoordinator
+     * stack so it composes cleanly with any future dialog-level ESC
+     * handlers; the host opens with CDK `disableClose: true`, so the
+     * dialog itself never closes on ESC — only the X / Cancel buttons
+     * exit the editor.
+     */
+    readonly isFullscreen: _angular_core.WritableSignal<boolean>;
+    get fullscreenClass(): boolean;
+    toggleFullscreen(): void;
+    /**
+     * Double-click anywhere on the dialog toggles fullscreen, EXCEPT
+     * on interactive controls and the editor canvas. The canvas is
+     * the primary work surface and fabric.js may bind its own
+     * dblclick semantics (object enter, text edit, etc.); excluding
+     * it keeps that path clear.
+     */
+    protected onDblClick(event: MouseEvent): void;
+    constructor();
+    ngOnInit(): Promise<void>;
+    ngOnDestroy(): void;
+    onEngineReady(engine: ImageEditorEngine): void;
+    onShellError(err: Error): void;
+    onSave(): Promise<void>;
+    onSaveAs(): Promise<void>;
+    /**
+     *  `canClose()` only ever meant "not mid-save" -- there was no dirty
+     * concept here at all, so a crop, a rotate and three filters were
+     * thrown away by Cancel without a word.
+     *
+     * `engine.canUndo()` is the dirty flag we would otherwise have had to
+     * invent: it is true exactly when the user has done something undoable,
+     * and it goes back to false if they undo their way to the start.
+     */
+    onCancel(): void;
+    /** The engine's undo depth IS "has anything been edited". */
+    private hasEdits;
+    private executeSave;
+    private saveMedia;
+    private saveVfs;
+    /**
+     * Pull a user-readable message out of whatever the HTTP layer
+     * threw at us. Angular's `HttpErrorResponse` implements the
+     * `Error` interface but doesn't extend the class, so a plain
+     * `instanceof Error` check misses it and we'd fall through to
+     * "unknown error".
+     */
+    private describeError;
+    /**
+     * Export format. Content wins over source: when the flattened image
+     * has any transparency (a mask / clipPath cut-out, or a transparent
+     * source) we force PNG, because flattening it onto an opaque JPEG
+     * loses the cut-away region to opaque black (the C.1d fix — masked
+     * Save-as previously baked black corners). Otherwise it follows the
+     * source MIME (PNG stays PNG, everything else -> JPEG, the two formats
+     * the underlying canvas reliably encodes).
+     */
+    private deriveFormat;
+    /** Whether the current edit has transparency the export must preserve. */
+    private contentWantsPng;
+    /**
+     * Normalise a filename's extension to match the export format, so a
+     * forced-PNG save (transparency preserved) doesn't keep a `.jpg`
+     * name. `jpg`/`jpeg` both satisfy the JPEG format.
+     */
+    private ensureExtension;
+    private deriveSaveAsName;
+    private parentDir;
+    private joinPath;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CoolmsImageEditorHostComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CoolmsImageEditorHostComponent, "coolms-image-editor-host", never, {}, {}, never, never, true, never>;
+}
+
+export { CoolmsImageEditorComponent, CoolmsImageEditorHostComponent, FabricEngineAdapter, ImageEditorStateService };
+export type { AnnotationShapeOptions, Bounds, CoolmsImageEditorHostData, CoolmsImageEditorHostResult, EditorState, EngineEventHandler, EngineEventType, EngineEvents, EngineOptions, FilterName, FilterParams, ImageEditorEngine, Point, Rect, ShapeGeometry, Size };