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

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

@@ -1,38 +1,36 @@
-import * as _angular_core from '@angular/core';
-import { AfterViewInit, OnDestroy, OnInit } from '@angular/core';
-
+import * as i0 from "@angular/core";
+import { AfterViewInit, InjectionToken, 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
+ * 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;
+  readonly x: number;
+  readonly y: number;
 }
 interface Size {
-    readonly width: number;
-    readonly height: number;
+  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;
+  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;
+  readonly minWidth: number;
+  readonly minHeight: number;
+  readonly maxWidth: number;
+  readonly maxHeight: number;
 }
-
 /**
  * Filter contract for the engine.
  *
@@ -57,14 +55,13 @@ type FilterName = 'brightness' | 'contrast' | 'saturation' | 'sepia' | 'grayscal
  * `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;
+  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).
  *
@@ -74,11 +71,11 @@ interface FilterParams {
  * 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
+ * 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
+ * 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.
  */
@@ -87,51 +84,51 @@ 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
+ * 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: 'rect';
+  rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
 } | {
-    kind: 'ellipse';
-    center: {
-        x: number;
-        y: number;
-    };
-    rx: number;
-    ry: number;
+  kind: 'ellipse';
+  center: {
+    x: number;
+    y: number;
+  };
+  rx: number;
+  ry: number;
 } | {
-    kind: 'polygon';
-    points: {
-        x: number;
-        y: 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
+ * - `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;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+  name?: string;
+  lockRotation?: boolean;
+  lockNonUniformScaling?: boolean;
 }
 /**
  * How a shape / text layer is filled (C.1b).
@@ -149,10 +146,10 @@ type FillType = 'solid' | 'linear' | 'radial';
  * (0 = left->right, 90 = top->bottom) and only meaningful for `linear`.
  */
 interface FillSpec {
-    type: FillType;
-    color: string;
-    color2: string;
-    angle: number;
+  type: FillType;
+  color: string;
+  color2: string;
+  angle: number;
 }
 /**
  * A read-only view of one layer, surfaced to the Layers panel. The
@@ -160,57 +157,63 @@ interface FillSpec {
  * 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;
+  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;
+  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;
+  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
+ * `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>;
+declare const DEFAULT_SHAPE_OPTIONS: ShapeOptions;
+/** Starting fill for the Shapes / Text tools (solid, blue accent). (C.1b) */
+declare const DEFAULT_FILL_SPEC: FillSpec;
+declare const DEFAULT_TEXT_OPTIONS: TextOptions;
+/** Font families offered in the Text tool (web-safe set). */
+declare const TEXT_FONT_FAMILIES: readonly ["Arial", "Helvetica", "Times New Roman", "Georgia", "Courier New", "Verdana", "Trebuchet MS", "Impact"];
 /**
  * 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
+ * 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
@@ -227,101 +230,98 @@ type MaskShape = 'none' | 'rect' | 'rounded' | 'ellipse' | 'triangle' | 'star' |
  *               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
+ *               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;
+  shape: MaskShape;
+  inset: number;
+  radius: number;
+  svgPath?: string;
 }
-
+/** Starting mask for the Mask tool (no clip). (C.1c) */
+declare const DEFAULT_MASK_SPEC: MaskSpec;
 /**
- * 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.
+ * SVG path data for the path-preset masks, normalised to a 0..100 box.
+ * The engine scales each to the target's clip box. (C.1c)
  */
-
+declare const MASK_PATHS: Readonly<Record<'star' | 'heart' | 'hexagon', string>>;
 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;
-    };
+  /** 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.
  *
@@ -338,337 +338,336 @@ type EngineEventHandler<T extends EngineEventType> = (data: EngineEvents[T]) =>
  *     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;
+  /**
+   * 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;
+  container: HTMLElement;
 }
 /**
  * fabric.js v7 adapter for the CoolMS image editor.
@@ -694,323 +693,321 @@ interface FabricEngineCreateOptions {
  * 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;
+export 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 x 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 4096x4096 GL
+   * canvas; rendering a 4608x3456 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 x 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
+ * 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;
+  /** 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`
+ * `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';
@@ -1025,170 +1022,172 @@ type EditorState = 'uninitialized' | 'loading' | 'ready' | 'error';
  * 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>;
+export declare class ImageEditorStateService {
+  private readonly engineInstance;
+  readonly state: import("@angular/core").WritableSignal<EditorState>;
+  readonly canvasSize: import("@angular/core").WritableSignal<Size | null>;
+  readonly canUndo: import("@angular/core").WritableSignal<boolean>;
+  readonly canRedo: import("@angular/core").WritableSignal<boolean>;
+  /** The active tool's id, set from the tool rail or a tool's shortcut; null when none is. */
+  readonly activeTool: import("@angular/core").WritableSignal<string | null>;
+  readonly errorMessage: import("@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: import("@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: import("@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: import("@angular/core").WritableSignal<boolean>;
+  readonly imageRotation: import("@angular/core").WritableSignal<number>;
+  readonly imageScaleX: import("@angular/core").WritableSignal<number>;
+  readonly imageScaleY: import("@angular/core").WritableSignal<number>;
+  readonly imageFlipX: import("@angular/core").WritableSignal<boolean>;
+  readonly imageFlipY: import("@angular/core").WritableSignal<boolean>;
+  readonly imagePosition: import("@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: import("@angular/core").WritableSignal<LayerInfo[]>;
+  /** Active layer id, mirrored from `activeObjectChanged`. (C.1) */
+  readonly activeLayerId: import("@angular/core").WritableSignal<string | null>;
+  /** Active layer kind, so style panels know which controls apply. (C.1) */
+  readonly activeLayerKind: import("@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: import("@angular/core").WritableSignal<number>;
+  readonly activeLayerFlipX: import("@angular/core").WritableSignal<boolean>;
+  readonly activeLayerFlipY: import("@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: import("@angular/core").Signal<number>;
+  readonly transformTargetFlipX: import("@angular/core").Signal<boolean>;
+  readonly transformTargetFlipY: import("@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: import("@angular/core").Signal<number>;
+  /** Read-only handle the toolbar and tools use to drive the engine. */
+  readonly engine: import("@angular/core").Signal<ImageEditorEngine | null>;
+  readonly isReady: import("@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.0x 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: i0.ɵɵFactoryDeclaration<ImageEditorStateService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
-
 /**
- * Three-pane shell for the CoolMS image editor.
+ * 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)
+ * Composition: top toolbar (action commands + size badge); below it the
+ * tool rail on the left (the tools in their groups, with names or as
+ * icons), the canvas mount (fills the remaining space), and the
+ * properties panel on the right (the active tool's, or the image's own
+ * when no tool is active). A tool's shortcut selects it while the editor
+ * has the keyboard. 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.
@@ -1202,60 +1201,156 @@ declare class ImageEditorStateService {
  * `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
+ * 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>;
+export declare class CoolmsImageEditorComponent implements AfterViewInit, OnDestroy {
+  sourceUrl: import("@angular/core").InputSignal<string>;
+  sourceFilename: import("@angular/core").InputSignal<string>;
+  /** Fires after the engine is created and the initial image has loaded. */
+  readonly engineReady: import("@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: import("@angular/core").OutputEmitterRef<Error>;
+  protected readonly state: ImageEditorStateService;
+  private readonly registry;
+  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>;
+  /**
+   * Delete on the selected shape or text layer removes it (one undoable step, as the Layers panel's delete). With
+   * nothing selected, or the base image selected, it does nothing. True when it removed a layer.
+   */
+  onKeydown(event: KeyboardEvent): boolean;
+  ngOnDestroy(): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<CoolmsImageEditorComponent, never>;
+  static ɵcmp: i0.ɵɵ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>;
+}
+/**
+ * The image editor's own text: keys, and the base catalogue that holds their English. A host translates by handing the
+ * editor a `Translator`; one that does not hear a key answers what the base catalogue holds, never the key.
+ *
+ * Imports nothing outside `src/core/` (the lint rule for this directory refuses it).
+ */
+/** Answers a key's text, `%name%` placeholders filled from `params`. */
+type Translator = (key: string, params?: Readonly<Record<string, string | number>>) => string;
+export declare const IMAGE_EDITOR_MESSAGES: Readonly<Record<string, string>>;
+/** Fills `%name%` placeholders; a placeholder with no value is left as it is. */
+declare function fill(text: string, params?: Readonly<Record<string, string | number>>): string;
+/** The base catalogue's translator: a key it does not hold answers the key itself, so a gap shows in development. */
+export declare const baseTranslator: Translator;
+/**
+ * A host's catalogue in front of the base one: a key the host does not hold, or holds blank, answers the base
+ * catalogue's English. A partial translation degrades one message at a time, never to a key or an empty label.
+ */
+export declare function catalogueTranslator(messages: Readonly<Record<string, string>>): Translator;
+/**
+ * The image editor's tools as data, with no framework: what a tool is called, where it sits on the rail, and which key
+ * selects it. An Angular or React host maps a tool's id to its own properties component; nothing here names one.
+ *
+ * Imports nothing outside `src/core/` (the lint rule for this directory refuses it).
+ */
+/** The rail's groups, in the order they are drawn. */
+type ToolGroup = 'transform' | 'insert' | 'filter' | 'layers';
+declare const TOOL_GROUPS: readonly {
+  readonly id: ToolGroup;
+  readonly labelKey: string;
+}[];
+interface ToolDefinition {
+  readonly id: string;
+  /** The tool's name, as a message key (`imageEditor.tool.<id>`). */
+  readonly labelKey: string;
+  /** A Bootstrap Icons class. */
+  readonly icon: string;
+  readonly group: ToolGroup;
+  /** Its place within the group, smallest first. */
+  readonly order: number;
+  /** One printable key that selects the tool while the editor has the keyboard, e.g. `c`. */
+  readonly shortcut?: string;
 }
-
+/** How the rail draws its tools: with their names, or as icons whose names show as tooltips. */
+type RailMode = 'labels' | 'icons';
+export declare const DEFAULT_RAIL_MODE: RailMode;
+/** A stored preference read back: anything but a known mode is the default. */
+export declare function railModeFrom(stored: unknown): RailMode;
+/** The tools of each group, groups in rail order and tools by `order` then id; empty groups left out. */
+declare function groupTools<T extends ToolDefinition>(tools: readonly T[]): {
+  group: ToolGroup;
+  labelKey: string;
+  tools: T[];
+}[];
+/**
+ * The tool a key selects: an unmodified printable key equal to a tool's shortcut (case ignored), or null. A key with
+ * Ctrl, Alt or Meta is never a tool's: those belong to the editor's commands and the browser.
+ */
+declare function toolForKey<T extends ToolDefinition>(tools: readonly T[], event: {
+  readonly key: string;
+  readonly ctrlKey: boolean;
+  readonly altKey: boolean;
+  readonly metaKey: boolean;
+}): T | null;
+/**
+ * The editor's text. A host provides its own translator (the platform's catalogues, say); without one the editor speaks
+ * the base catalogue's English (`core/messages.ts`).
+ */
+export declare const IMAGE_EDITOR_TRANSLATOR: InjectionToken<Translator>;
+/** Where the rail's mode is remembered. The admin keeps it in the person's preferences, so it follows them. */
+interface RailModeStore {
+  /** The mode last chosen, or null when none was. */
+  read(): RailMode | null;
+  write(mode: RailMode): void;
+}
+/** Remembered for this page load only: what a host without preferences gets. */
+export declare function sessionRailModeStore(): RailModeStore;
+export declare const IMAGE_EDITOR_RAIL_MODE: InjectionToken<RailModeStore>;
 /**
  * Wire-shape types for the CDK Dialog host.
  *
@@ -1264,13 +1359,13 @@ declare class CoolmsImageEditorComponent implements AfterViewInit, OnDestroy {
  * caller having to know which one. Each branch carries exactly the
  * fields that branch needs:
  *
- *   - **Media context** — the asset is a registered `MediaAsset`,
+ *   - **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
+ *   - **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:
@@ -1279,67 +1374,88 @@ declare class CoolmsImageEditorComponent implements AfterViewInit, OnDestroy {
  */
 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;
+  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)` when no `sourceUrl` is given. */
+    readonly originalUrl: string;
+    /**
+     * Where the asset's own bytes are read with their version (the response's ETag), as for a file: the version a
+     * replace names as If-Match is the version of the pixels opened, from that one read (2026-10-15). Without it
+     * the image is shown from `originalUrl`, which names no version, and Save is off: the edits go to a new image.
+     */
+    readonly sourceUrl?: 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;
-    };
+  readonly context: 'vfs';
+  readonly node: {
+    /** Absolute VFS path of the file. */
+    readonly path: string;
+    /** The file's node id: the host's file watch follows it to say when it changes or goes elsewhere. */
+    readonly id?: string;
+    /** Caller's effective write permission on the file (mirrors `VfsNodeDto.permissions.write`). */
+    readonly canWrite: boolean;
+    /**
+     * Offered when `canWrite` is false: what Save does INSTEAD of being
+     * dead (the elevation client requirement, point 2). The caller asks
+     * the server for elevation and resolves true when the session has
+     * it; the host then treats the file as writable and saves. Absent,
+     * Save is disabled as before. The host decides nothing itself.
+     */
+    readonly requestWrite?: () => Promise<boolean>;
+    /**
+     * Where the file's own bytes are read, and with them their version (the response's ETag): the version an
+     * overwrite names as If-Match is the version of the pixels the editor opened, from that one read -- a file
+     * changed after it was listed is edited as it is now, and a copy served from a cache carries its own older
+     * version, so its save is refused (412), never written over the newer file (2026-10-15). A read that names no
+     * version leaves Save off: the edits can go to a new image only.
+     */
+    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: '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;
+  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`.
@@ -1359,7 +1475,7 @@ type HostState = 'preparing' | 'editing' | 'saving' | 'error';
  *
  * 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
+ * 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
@@ -1367,122 +1483,153 @@ type HostState = 'preparing' | 'editing' | 'saving' | 'error';
  * 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>;
+/**
+ * The format Save writes a source back as, or null when Save may not overwrite it: only PNG and
+ * JPEG, which the editor encodes as themselves. GIF (animated or not), SVG, TIFF, HEIC, BMP and WebP -- until its export
+ * is verified in every supported browser -- have Save as only: overwriting them would put PNG or JPEG bytes under their
+ * name, and an animation or vectors would be lost.
+ */
+declare function writtenBackAs(mimeType: string): 'png' | 'jpeg' | null;
+export 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;
+  /**
+   * The file was changed or deleted elsewhere while the editor is open (2026-10-14: "the editor says so, from the VFS
+   * change event"). Said above the canvas; Save then answers 412 / 404 and goes to "Save as".
+   */
+  protected readonly changedElsewhere: import("@angular/core").WritableSignal<"changed" | "deleted" | null>;
+  readonly state: import("@angular/core").WritableSignal<HostState>;
+  readonly errorMessage: import("@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: import("@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: import("@angular/core").WritableSignal<boolean>;
+  readonly isSaving: import("@angular/core").Signal<boolean>;
+  /**
+   * Set once the caller's `requestWrite` resolved true: the server elevated
+   * the session, so the flag it computed before no longer describes it.
+   */
+  private readonly writeGranted;
+  /** Whether the VFS file is writable: the flag, or an elevation granted since. */
+  private readonly canWrite;
+  /**
+   * Save (overwrite) is gated on engine readiness AND, for VFS context,
+   * write permission -- unless the caller offered `requestWrite`, in which
+   * case the button stays live and asks for elevation instead of sitting
+   * dead (the control stays live and the server decides).
+   */
+  readonly canSave: import("@angular/core").Signal<boolean>;
+  /** The version of the bytes the editor opened: the ETag of the read that delivered them. */
+  private readonly readVersion;
+  private readonly canRequestWrite;
+  /** Save as is gated only on engine readiness -- even read-only sources can be saved as new. */
+  readonly canSaveAs: import("@angular/core").Signal<boolean>;
+  readonly canClose: import("@angular/core").Signal<boolean>;
+  /** Filename header label and default save-as name. */
+  readonly filename: import("@angular/core").Signal<string>;
+  /** Source MIME, drives export format. */
+  readonly mimeType: import("@angular/core").Signal<string>;
+  /** Whether Save may overwrite the source: the editor writes it back in its own format. */
+  readonly savesInItsOwnFormat: import("@angular/core").Signal<boolean>;
+  /** Why Save is off for this format, said on the button; null when it is not the format. */
+  readonly saveFormatNote: import("@angular/core").Signal<"Save writes an image back only as PNG or JPEG, in its own format. Use Save as for this one." | null>;
+  readonly dimensionsLabel: import("@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: import("@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: i0.ɵɵFactoryDeclaration<CoolmsImageEditorHostComponent, never>;
+  static ɵcmp: i0.ɵɵ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 };
+/** The version an ETag names: `"abc"` and `W/"abc"` are both `abc`; no ETag, no version. */
+declare function versionOf(etag: string | null): string | null;
+export type { AnnotationShapeOptions, Bounds, CoolmsImageEditorHostData, CoolmsImageEditorHostResult, EditorState, EngineEventHandler, EngineEventType, EngineEvents, EngineOptions, FilterName, FilterParams, ImageEditorEngine, Point, RailMode, RailModeStore, Rect, ShapeGeometry, Size, ToolDefinition, ToolGroup, Translator };