@pixerate/editor 0.23.0 → 0.25.0

package/dist/image-editor/index.d.ts

@@ -1,3 +1,143 @@
+import { b as LoadReport, J as JsonObject, f as MigrationStep } from '../migrate-iTlm3a8h.js';
+import { A as AgentToolProvider, a as AgentTool } from '../registry-BDe-vlv3.js';
+import '../schema-DYDGdYL9.js';
+
+/**
+ * Photoshop blend modes on straight (non-premultiplied) 0..1 colours.
+ *
+ * Formulas follow the W3C Compositing / ISO 32000 definitions, with Photoshop's variants where
+ * they differ (Soft Light, Vivid / Linear / Pin Light, Hard Mix, Linear Burn / Dodge, Subtract,
+ * Divide, Darker / Lighter Color), and the hardened `ClipColor` for the non-separable modes.
+ */
+type BlendMode = 'normal' | 'darken' | 'multiply' | 'color-burn' | 'linear-burn' | 'darker-color' | 'lighten' | 'screen' | 'color-dodge' | 'linear-dodge' | 'lighter-color' | 'overlay' | 'soft-light' | 'hard-light' | 'vivid-light' | 'linear-light' | 'pin-light' | 'hard-mix' | 'difference' | 'exclusion' | 'subtract' | 'divide' | 'hue' | 'saturation' | 'color' | 'luminosity';
+interface BlendModeInfo {
+    id: BlendMode;
+    label: string;
+    /** Canvas `globalCompositeOperation` with the same maths, when there is one. */
+    canvas: GlobalCompositeOperation | null;
+}
+/** Every blend mode, in Photoshop's menu order. */
+declare const BLEND_MODES: readonly BlendModeInfo[];
+declare function isBlendMode(value: unknown): value is BlendMode;
+/** A stored blend mode, or `normal` for a missing / unknown value. */
+declare function normalizeBlendMode(value: unknown): BlendMode;
+/**
+ * The canvas composite operation that implements `mode` exactly, or `null` when the canvas has
+ * none (draw through {@link blendImageData} instead).
+ */
+declare function canvasCompositeOperation(mode: BlendMode | undefined): GlobalCompositeOperation | null;
+/** Whether a mode works on whole colours (hue, saturation, colour, luminosity, darker / lighter colour). */
+declare function isSeparableBlendMode(mode: BlendMode): boolean;
+/** Separable blend function `B(cb, cs)` of one channel. Non-separable modes return `cs`. */
+declare function blendChannel(mode: BlendMode, cb: number, cs: number): number;
+type Rgb$1 = [number, number, number];
+type Rgba = [number, number, number, number];
+/** Luminosity of the non-separable modes (W3C / ISO 32000 weights). */
+declare function blendLum(c: readonly number[]): number;
+/** `c` with its luminosity moved to `l`, clipped back into gamut towards grey (SetLum + ClipColor). */
+declare function setLum(c: readonly number[], l: number): Rgb$1;
+/** `B(Cb, Cs)` of a whole colour, including the non-separable modes. */
+declare function blendRgb(mode: BlendMode, cb: readonly number[], cs: readonly number[]): Rgb$1;
+/**
+ * Composites a straight-alpha `source` over a straight-alpha `backdrop` (both RGBA in 0..1) with a
+ * blend mode and an extra `alpha` (opacity), using the W3C general formula:
+ * `αo = αs + αb(1 − αs)`, `αo·Co = (1 − αs)·αb·Cb + (1 − αb)·αs·Cs + αs·αb·B(Cb, Cs)`.
+ */
+declare function blendPixel(mode: BlendMode, backdrop: readonly number[], source: readonly number[], alpha?: number): Rgba;
+/**
+ * Blends `source` into `backdrop` in place (8-bit straight RGBA of the same size) with
+ * {@link blendPixel}. The scalar fallback for modes the canvas cannot composite.
+ */
+declare function blendImageData(backdrop: ImageData, source: ImageData, mode: BlendMode, alpha?: number): void;
+
+/**
+ * A selection: one 8-bit coverage value per image pixel (0 = not selected, 255 = fully
+ * selected), row-major over the whole source image in natural pixels — the same space as the
+ * crop box and annotations. Soft values are partial selection (feathered or anti-aliased edges).
+ *
+ * Treat a mask as immutable: every operation returns a new one, so history entries can share
+ * them without copying.
+ */
+interface SelectionMask {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8Array;
+    /** Bounding box of the non-zero coverage, or `null` when nothing is selected. */
+    readonly bounds: CropBox | null;
+}
+/** How a new selection combines with the current one. */
+type SelectionMode = 'replace' | 'add' | 'subtract' | 'intersect';
+declare const SELECTION_MODES: readonly SelectionMode[];
+declare function isSelectionMode(value: unknown): value is SelectionMode;
+/** Parses `replace|add|subtract|intersect`; anything else is `replace`. */
+declare function parseSelectionMode(value: unknown): SelectionMode;
+/** RGBA pixels, 8 bits per channel, straight alpha (an `ImageData` qualifies). */
+interface PixelBuffer {
+    width: number;
+    height: number;
+    data: ArrayLike<number>;
+}
+/** Serialized selection: a run-length encoding of the 8-bit coverage. */
+interface SerializedSelection {
+    width: number;
+    height: number;
+    /** `r1:` + base64 of (value byte, LEB128 run length) pairs. */
+    rle: string;
+}
+/** Bounding box of non-zero bytes. */
+declare function computeSelectionBounds(width: number, height: number, data: ArrayLike<number>): CropBox | null;
+/** Wraps coverage bytes (taken over, not copied) as a selection, computing its bounds. */
+declare function createSelectionMask(width: number, height: number, data?: Uint8Array): SelectionMask;
+/** Select › All. */
+declare function fullSelection(width: number, height: number): SelectionMask;
+declare function isSelectionEmpty(mask: SelectionMask | null | undefined): boolean;
+/** Coverage at a pixel, 0..1 (0 outside the image). */
+declare function selectionValueAt(mask: SelectionMask, x: number, y: number): number;
+/** 8-bit value of a coverage (clamped and rounded; NaN → 0). */
+declare function coverageToByte(v: number): number;
+/** A selection from 0..1 coverage. */
+declare function selectionFromCoverage(width: number, height: number, coverage: ArrayLike<number>): SelectionMask;
+/** The selection's coverage as 0..1 floats. */
+declare function selectionToCoverage(mask: SelectionMask): Float32Array;
+/** Number of fully-or-partly selected pixels, weighted by coverage (Σ coverage). */
+declare function selectionArea(mask: SelectionMask | null | undefined): number;
+/**
+ * Combines `next` with `prev` by `mode` (8-bit, exact: combining a mask with itself is a no-op).
+ * Add is the maximum, Subtract `max(prev − next, 0)`, Intersect the minimum. A missing `prev`
+ * reads as nothing selected. Returns `null` when nothing remains selected.
+ */
+declare function combineSelections(prev: SelectionMask | null | undefined, next: SelectionMask, mode: SelectionMode): SelectionMask | null;
+/** Select › Inverse. */
+declare function invertSelection(mask: SelectionMask): SelectionMask;
+/** Bilinear resample to another size (e.g. an AI mask returned at a different resolution). */
+declare function resizeSelection(mask: SelectionMask, width: number, height: number): SelectionMask;
+type SelectionChannel = 'alpha' | 'luminance' | 'red' | 'green' | 'blue';
+/**
+ * A selection from an image: by default its luminance (white = selected, the usual convention
+ * of segmentation masks), or one channel. Partly transparent pixels count as black for
+ * luminance, so a mask PNG with transparency works either way.
+ */
+declare function selectionFromPixels(pixels: PixelBuffer, options?: {
+    channel?: SelectionChannel;
+    invert?: boolean;
+    threshold?: number;
+}): SelectionMask;
+/** The selection as RGBA pixels: grey (white = selected, opaque) or white with coverage as alpha. */
+declare function selectionToPixels(mask: SelectionMask, as?: 'gray' | 'alpha'): {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+/** Run-length encodes coverage bytes: `r1:` + base64 of (value, LEB128 run length) pairs. */
+declare function encodeSelectionRle(data: Uint8Array): string;
+/** Decodes {@link encodeSelectionRle}; throws unless the runs cover exactly `length` bytes. */
+declare function decodeSelectionRle(rle: string, length: number): Uint8Array;
+declare function serializeSelection(mask: SelectionMask): SerializedSelection;
+/** Restores a {@link SerializedSelection}; throws on damaged data. */
+declare function deserializeSelection(value: unknown): SelectionMask;
+/** A short, stable hash of a string or bytes (FNV-1a, 32-bit, hex) for cache keys. */
+declare function hashMaskContent(content: string | Uint8Array): string;
+
 interface ImageDimensions {
     width: number;
     height: number;
@@ -38,7 +178,157 @@ interface ImageAdjustments {
      * versions existed look exactly as they did. See `normalizeProcessVersion`.
      */
     process?: 1 | 2;
+    /**
+     * Non-destructive adjustment layers, evaluated bottom (first) to top (last) after the base
+     * adjustments above, on the encoded sRGB result. Missing or empty: no layers (edits saved
+     * before layers existed render exactly as before).
+     */
+    layers?: AdjustmentLayer[];
+}
+type AdjustmentKind = 'curves' | 'levels' | 'hueSaturation' | 'vibrance' | 'colorBalance' | 'blackWhite' | 'invert' | 'posterize' | 'threshold' | 'photoFilter';
+/** A Curves point; `input` and `output` are levels, 0..255. */
+interface CurvePoint {
+    input: number;
+    output: number;
+}
+/** Curves: each channel's curve first, then the master (composite) curve, as in Photoshop. */
+interface CurvesParams {
+    master: CurvePoint[];
+    red: CurvePoint[];
+    green: CurvePoint[];
+    blue: CurvePoint[];
+}
+/** One Levels record. Black / white points are levels (0..255); `gamma` is the midtone slider (0.1..9.99). */
+interface LevelsChannel {
+    inBlack: number;
+    inWhite: number;
+    gamma: number;
+    outBlack: number;
+    outWhite: number;
+}
+/** Levels: each channel's record first, then the master record, as in Photoshop. */
+interface LevelsParams {
+    master: LevelsChannel;
+    red: LevelsChannel;
+    green: LevelsChannel;
+    blue: LevelsChannel;
+}
+/** One of Hue/Saturation's six colour ranges (reds, yellows, greens, cyans, blues, magentas). */
+interface HueRange {
+    /** Hue shift in degrees (-180..180). */
+    hue: number;
+    /** Saturation change in percent (-100..100). */
+    saturation: number;
+    /** Lightness change in percent (-100..100). */
+    lightness: number;
+    /** Hue degrees where the range starts fading in, is fully on, starts fading out and ends (may wrap). */
+    bounds: [number, number, number, number];
+}
+interface HueSaturationParams {
+    /** Master hue shift in degrees (-180..180), or the hue when colorizing (0..360). */
+    hue: number;
+    /** Percent, -100..100 (0..100 when colorizing). */
+    saturation: number;
+    /** Percent, -100..100. */
+    lightness: number;
+    colorize: boolean;
+    /** Six ranges: reds, yellows, greens, cyans, blues, magentas. */
+    ranges: HueRange[];
+}
+interface VibranceParams {
+    /** -100..100 */
+    vibrance: number;
+    /** -100..100 */
+    saturation: number;
+}
+/** Cyan–red, magenta–green, yellow–blue sliders, -100..100 each. */
+type ColorBalanceTone = [number, number, number];
+interface ColorBalanceParams {
+    shadows: ColorBalanceTone;
+    midtones: ColorBalanceTone;
+    highlights: ColorBalanceTone;
+    preserveLuminosity: boolean;
+}
+/** Black & White: percent weights of the six colours (Photoshop defaults 40 60 40 60 20 80). */
+interface BlackWhiteParams {
+    reds: number;
+    yellows: number;
+    greens: number;
+    cyans: number;
+    blues: number;
+    magentas: number;
+    /** Tint colour (`#rrggbb`), applied like the Color blend mode, or `null` for none. */
+    tint: string | null;
+}
+interface PhotoFilterParams {
+    /** Filter colour, `#rrggbb`. */
+    color: string;
+    /** Percent, 0..100. */
+    density: number;
+    preserveLuminosity: boolean;
+}
+interface PosterizeParams {
+    /** 2..255 */
+    levels: number;
+}
+interface ThresholdParams {
+    /** 1..255: luma at or above it becomes white. */
+    level: number;
+}
+type InvertParams = Record<string, never>;
+interface AdjustmentParamsMap {
+    curves: CurvesParams;
+    levels: LevelsParams;
+    hueSaturation: HueSaturationParams;
+    vibrance: VibranceParams;
+    colorBalance: ColorBalanceParams;
+    blackWhite: BlackWhiteParams;
+    invert: InvertParams;
+    posterize: PosterizeParams;
+    threshold: ThresholdParams;
+    photoFilter: PhotoFilterParams;
+}
+interface AdjustmentLayerBase {
+    id: string;
+    /** Optional display name. */
+    name?: string;
+    enabled: boolean;
+    /** 0..1 */
+    opacity: number;
+    /** How the adjusted colour is blended over the layers below. */
+    blend: BlendMode;
+    /**
+     * Optional layer mask (natural image pixels): where it is 0 the layer has no effect. Missing:
+     * the layer applies everywhere (layers saved before masks existed are unchanged).
+     */
+    mask?: AdjustmentLayerMask;
 }
+/**
+ * A layer mask: 8-bit coverage of the source image, run-length encoded (see
+ * `encodeSelectionRle`), plus non-destructive density and feather.
+ */
+interface AdjustmentLayerMask {
+    width: number;
+    height: number;
+    /** `r1:` run-length encoding of the mask bytes. */
+    rle: string;
+    /** 0..1 (missing = 1). */
+    density?: number;
+    /** Gaussian σ in pixels (missing = 0). */
+    feather?: number;
+    /** `false` keeps the mask but ignores it. */
+    enabled?: boolean;
+}
+/** A non-destructive adjustment layer (Photoshop's Layer › New Adjustment Layer). */
+type AdjustmentLayer = {
+    [K in AdjustmentKind]: AdjustmentLayerBase & {
+        kind: K;
+        params: AdjustmentParamsMap[K];
+    };
+}[AdjustmentKind];
+type AdjustmentLayerOf<K extends AdjustmentKind> = Extract<AdjustmentLayer, {
+    kind: K;
+}>;
 interface DepthMaskOptions {
     enabled: boolean;
     maskSource: string | null;
@@ -55,6 +345,8 @@ interface BaseAnnotation {
     y: number;
     rotation?: number;
     opacity?: number;
+    /** Blend mode the annotation is drawn with (default `normal`). */
+    blend?: BlendMode;
 }
 interface PenAnnotation extends BaseAnnotation {
     type: 'pen';
@@ -123,14 +415,27 @@ interface ImageEditorState {
     zoom: number;
     pan: ImagePoint;
     isOriginalCompared: boolean;
+    /**
+     * The active selection (8-bit coverage over the source image), or null/missing when nothing is
+     * selected. Recorded in undo history and saved as `selection` in `toJSON()`.
+     */
+    selection?: SelectionMask | null;
+    /** Quick Mask view: tint the unselected area instead of drawing marching ants (view state). */
+    quickMask?: boolean;
 }
 interface SerializedImageEditorState {
-    version: 1;
+    /**
+     * Schema version. `2` adds `adjustments.layers`; states without layers are still written as
+     * `1` so they round-trip unchanged. See `migrateSerializedImageEditorState`.
+     */
+    version: 1 | 2;
     crop: CropBox | null;
     transform: ImageTransform;
     adjustments: ImageAdjustments;
     depthMask: DepthMaskOptions;
     annotations: Annotation[];
+    /** The active selection, run-length encoded. Missing when nothing is selected. */
+    selection?: SerializedSelection;
 }
 interface ExportOptions {
     format?: 'image/png' | 'image/jpeg' | 'image/webp';
@@ -163,13 +468,15 @@ interface ImageEditorAIHooks {
 
 /**
  * Applies color and tone adjustments (brightness, contrast, saturation, exposure, temperature, tint,
- * opacity, blur) directly to the pixel data of an ImageData buffer.
+ * opacity, then any adjustment `layers`, then blur) directly to the pixel data of an ImageData buffer.
  *
  * `adjustments.process` selects the rendering: `2` is the linear-light pipeline
  * ({@link applyProcess2Adjustments}); anything else (including a missing value, as in edits saved
  * before process versions existed) is the frozen legacy rendering ({@link applyLegacyAdjustments}).
  */
-declare function applyAdjustments(imageData: ImageData, adjustments: ImageAdjustments): void;
+declare function applyAdjustments(imageData: ImageData, adjustments: ImageAdjustments, options?: {
+    layerMasks?: ReadonlyMap<string, ArrayLike<number>>;
+}): void;
 /**
  * Process 1: the original 8-bit gamma-space rendering, clamping after every step. Frozen so
  * that edits saved without a `process` look exactly as they always have. `tint` is ignored.
@@ -304,6 +611,47 @@ declare function buildToneLut(contrast: number, brightness: number, headroom?: n
 /** Linearly interpolated lookup into a LUT from {@link buildToneLut}. */
 declare function sampleToneLut(lut: Float32Array, headroom: number, y: number): number;
 
+/** Display bins of a histogram. */
+declare const HISTOGRAM_BINS = 256;
+interface ImageHistogram {
+    /** 256-bin counts per channel. */
+    red: Uint32Array;
+    green: Uint32Array;
+    blue: Uint32Array;
+    /** 256-bin counts of Rec.709 luma `round(0.2126 R + 0.7152 G + 0.0722 B)` of the encoded values. */
+    luminance: Uint32Array;
+    /** Visible pixels counted (alpha > 0). Each counts once, partially transparent ones included. */
+    samples: number;
+    /** Fully transparent pixels, excluded from every bin. */
+    transparent: number;
+    /** Per channel (R, G, B): visible pixels at exactly 0. */
+    shadows: [number, number, number];
+    /** Per channel (R, G, B): visible pixels at exactly 255. */
+    highlights: [number, number, number];
+    /** Largest bin count over R, G, B and luminance (for scaling a plot). */
+    max: number;
+}
+interface PixelSource {
+    data: ArrayLike<number>;
+    width?: number;
+    height?: number;
+}
+/**
+ * Per-channel and luminance histograms of straight 8-bit RGBA pixels (an `ImageData` or anything
+ * with `data`), with clipping counts at the exact endpoints. Transparent pixels cannot add
+ * phantom peaks: they are counted separately and excluded.
+ */
+declare function computeHistogram(imageData: PixelSource): ImageHistogram;
+type HistogramChannel = 'red' | 'green' | 'blue' | 'luminance';
+/**
+ * An SVG path (`M … Z`) of one channel scaled into a `width` × `height` box, bins left to right,
+ * counts up from the bottom. `scale: 'sqrt'` (default) keeps small populations visible.
+ */
+declare function histogramPath(histogram: ImageHistogram, channel: HistogramChannel, width: number, height: number, options?: {
+    scale?: 'linear' | 'sqrt';
+    max?: number;
+}): string;
+
 interface RenderOptions {
     viewportWidth?: number;
     viewportHeight?: number;
@@ -312,6 +660,15 @@ interface RenderOptions {
     interactive?: boolean;
     draftAnnotation?: Annotation | null;
     draftCrop?: CropBox | null;
+    /**
+     * How the active selection is shown: marching ants (default when there is a selection),
+     * a Quick Mask tint over the unselected area (default when `state.quickMask`), or not at all.
+     */
+    selectionDisplay?: 'ants' | 'quickMask' | 'none';
+    /** Dash offset of the marching ants in screen pixels (animate it to make them march). */
+    antsOffset?: number;
+    /** A selection being drawn (e.g. a lasso), shown as a dashed outline in natural pixels. */
+    draftSelectionPath?: ImagePoint[] | null;
 }
 /**
  * Image Cache to avoid refetching HTMLImageElement objects repeatedly during re-renders.
@@ -331,6 +688,13 @@ declare class ImageEditorRenderer {
     imageCache: ImageCache;
     private cachedBaseCanvas;
     private cachedBaseKey;
+    /**
+     * Histogram of the last viewport base render (after adjustments and layers, before
+     * annotations); `null` until a render with pixel access has happened.
+     */
+    previewHistogram: ImageHistogram | null;
+    /** Called whenever the viewport base image is re-rendered with the new histogram. */
+    onPreviewHistogram?: (histogram: ImageHistogram | null) => void;
     private sourceIds;
     private nextSourceId;
     /**
@@ -346,11 +710,26 @@ declare class ImageEditorRenderer {
      * and the depth mask (which receives the identical transform so it stays aligned).
      */
     private renderBaseImage;
+    private quickMaskCache;
+    private outlineCache;
+    /** Rubylith over the unselected area, drawn in natural image space. */
+    private drawQuickMask;
+    /** Marching ants: a white line under a black dashed one, one screen pixel wide. */
+    private drawAnts;
+    private drawDraftPath;
     private getSourceId;
     /**
      * Draws an individual annotation onto the canvas.
      */
     drawAnnotation(ctx: CanvasRenderingContext2D, ann: Annotation): Promise<void>;
+    /**
+     * Scalar fallback for blend modes the canvas cannot composite (Photoshop soft light, linear /
+     * vivid / pin light, hard mix, subtract, divide, darker / lighter colour, linear burn / dodge):
+     * draws the annotation on a same-size layer with the same transform, blends it into a copy of
+     * the target's pixels with `blendImageData`, and copies the result back inside the current clip.
+     */
+    private drawAnnotationBlended;
+    private drawAnnotationContent;
     /**
      * Draws selection box around active annotation.
      */
@@ -380,16 +759,400 @@ declare class ImageEditorRenderer {
     renderMask(state: ImageEditorState, options?: {
         useAnnotations?: boolean;
         useCrop?: boolean;
+        useSelection?: boolean;
     }): Promise<HTMLCanvasElement>;
     private drawAnnotationMask;
 }
 
+interface ShapeSelectionOptions {
+    /** Partial coverage along the edge (default true). */
+    antiAlias?: boolean;
+}
+/**
+ * Even-odd polygon coverage over a `width × height` image: exact horizontal coverage on 4
+ * sub-rows per pixel row (1 without anti-aliasing, where a pixel is in when its centre is).
+ * Each sub-row only tests the edges that cross it (an active edge list over edges sorted by
+ * their top), so the cost is about pixels + edges × rows they span.
+ */
+declare function polygonCoverage(points: readonly ImagePoint[], width: number, height: number, antiAlias?: boolean): Float32Array;
+/** Lasso / polygonal lasso: an even-odd polygon in natural image pixels. */
+declare function polygonSelection(width: number, height: number, points: readonly ImagePoint[], options?: ShapeSelectionOptions): SelectionMask;
+/** Normalises a rectangle with a negative width or height. */
+declare function normalizeRect(rect: CropBox): CropBox;
+/** Rectangular marquee. Fractional edges get partial coverage when anti-aliased. */
+declare function rectSelection(width: number, height: number, rect: CropBox, options?: ShapeSelectionOptions): SelectionMask;
+/** The ellipse inscribed in `rect` as a polygon fine enough that its chords stay within 0.05 px. */
+declare function ellipsePoints(rect: CropBox): ImagePoint[];
+/** Elliptical marquee inscribed in `rect`. */
+declare function ellipseSelection(width: number, height: number, rect: CropBox, options?: ShapeSelectionOptions): SelectionMask;
+
+/** How the magic wand measures colour difference. */
+type ColorDistance = 'rgb' | 'perceptual';
+interface MagicWandOptions {
+    /**
+     * 0..255. `rgb`: the largest per-channel difference in levels (alpha included), as
+     * Photoshop's wand. `perceptual`: CIE76 ΔE*ab, with 255 ≙ ΔE 100. Default 32.
+     */
+    tolerance?: number;
+    /** Only the 4-connected region around the seed (default true); otherwise every similar pixel. */
+    contiguous?: boolean;
+    /** Soft one-pixel fringe on the edge (default true). */
+    antiAlias?: boolean;
+    /** Default `rgb`. */
+    distance?: ColorDistance;
+}
+/** CIE Lab (D65) of an 8-bit sRGB colour. */
+declare function srgb8ToLab(r: number, g: number, b: number): [number, number, number];
+/**
+ * Magic wand: pixels similar to the seed pixel. Contiguous mode is a scanline span fill with an
+ * explicit stack (fill a run, then scan the rows above and below it for new runs), so it is
+ * linear in the pixels visited and never recurses. An empty selection when the seed is outside.
+ */
+declare function magicWand(pixels: PixelBuffer, seed: ImagePoint, options?: MagicWandOptions): SelectionMask;
+/** One Color Range sample: a colour (0..255 levels or `#rrggbb`) and, optionally, where it was picked. */
+interface ColorRangeSample {
+    color: readonly [number, number, number] | string;
+    at?: ImagePoint;
+}
+interface ColorRangeOptions {
+    /** 0..200 levels (default 40): coverage falls off linearly to 0 at `fuzziness + 1` levels. */
+    fuzziness?: number;
+    /**
+     * Localized Color Clusters: a sample with a position also fades with distance from it,
+     * reaching 0 at this many pixels.
+     */
+    localized?: number;
+}
+/**
+ * Select › Color Range › Sampled Colors: each pixel takes its best match over the samples; a
+ * match falls off linearly with the largest per-channel difference, `1 − d / (fuzziness + 1)`.
+ * Transparent pixels are never selected.
+ */
+declare function colorRange(pixels: PixelBuffer, samples: readonly ColorRangeSample[], options?: ColorRangeOptions): SelectionMask;
+type ToneRangePreset = 'shadows' | 'midtones' | 'highlights';
+/** Luma bounds (0..255, Rec. 601) of the tonal presets. */
+declare const TONE_RANGE_PRESETS: Record<ToneRangePreset, [number, number]>;
+/**
+ * Select › Color Range › Shadows / Midtones / Highlights: pixels whose luma lies in `lo..hi` are
+ * selected; outside, selection falls off linearly to 0 over `falloff` levels.
+ */
+declare function toneRange(pixels: PixelBuffer, range: ToneRangePreset | readonly [number, number], falloff?: number): SelectionMask;
+/**
+ * Select › Color Range › Reds … Magentas (`center` 0, 60, …, 300°): closeness of hue (full at
+ * the centre, none 60° away) × chroma × (2 − max), so neutrals are never selected.
+ */
+declare function hueRange(pixels: PixelBuffer, center: number): SelectionMask;
+
+/** Distance reported for every pixel when there is no seed at all. */
+declare const EMPTY_DISTANCE = 10000000000;
+/**
+ * Exact Euclidean distance from every pixel centre to the nearest seed pixel centre (row-major
+ * `inside`, non-zero = seed): nearest seeds along columns, then the lower envelope of parabolas
+ * along rows (Felzenszwalb & Huttenlocher). Linear in the pixel count.
+ */
+declare function distanceTransform(inside: ArrayLike<number | boolean>, width: number, height: number): Float32Array;
+/** Grows coverage (0..1) by `r` pixels: covered when the nearest selected centre is ≤ r away (fractional r → partial). */
+declare function expandCoverage(m: ArrayLike<number>, w: number, h: number, r: number): Float32Array;
+/** Shrinks coverage by `r` pixels (expands the inverse). */
+declare function contractCoverage(m: ArrayLike<number>, w: number, h: number, r: number): Float32Array;
+/**
+ * Select › Modify › Border: a soft band `2r` wide centred on the edge. A pixel `D` away (centre
+ * to centre) from the nearest pixel on the other side of the edge is selected `1 − (D − 1) / r`.
+ */
+declare function borderCoverage(m: ArrayLike<number>, w: number, h: number, r: number): Float32Array;
+/**
+ * Select › Modify › Smooth: box average of radius `round(r)` with replicated edges, then
+ * re-thresholded at ½ — specks drop, corners round, straight edges stay hard.
+ */
+declare function smoothCoverage(m: ArrayLike<number>, w: number, h: number, r: number): Float32Array;
+/** Above this σ a Gaussian is approximated by three box passes (cost independent of σ). */
+declare const DIRECT_GAUSSIAN_MAX_SIGMA = 8;
+type Edge = 'zero' | 'clamp';
+/**
+ * Separable Gaussian blur of a single-channel float image. `edge` `zero` treats pixels beyond
+ * the image as 0 (selection feather), `clamp` replicates the border (mask refinement). σ up to
+ * {@link DIRECT_GAUSSIAN_MAX_SIGMA} is convolved directly; wider blurs use three box passes, so
+ * the cost per pixel never grows with σ.
+ */
+declare function gaussianBlur(src: ArrayLike<number>, w: number, h: number, sigma: number, edge?: Edge): Float32Array;
+/** Select › Modify › Feather: Gaussian blur with σ = radius (as Photoshop), zero beyond the image. */
+declare function featherCoverage(m: ArrayLike<number>, w: number, h: number, radius: number): Float32Array;
+/** Grey dilation (`grow`) or erosion with a square of radius `r`, separable, O(1) per pixel. */
+declare function greyMorphology(src: ArrayLike<number>, w: number, h: number, r: number, grow: boolean): Float32Array;
+/**
+ * Grows (positive) or shrinks (negative) soft coverage by a fractional distance: whole pixels
+ * use one morphology, the remainder blends with the next pixel, so 0.3 px differs from 1 px.
+ */
+declare function shiftCoverage(src: ArrayLike<number>, w: number, h: number, amount: number): Float32Array;
+type SelectionModifyOp = 'grow' | 'shrink' | 'feather' | 'border' | 'smooth';
+declare const SELECTION_MODIFY_OPS: readonly SelectionModifyOp[];
+/** Select › Modify (grow = Expand, shrink = Contract, feather, border, smooth) by `radius` pixels. */
+declare function modifySelection(mask: SelectionMask, op: SelectionModifyOp, radius: number): SelectionMask;
+
+/**
+ * Refine Edge / Select and Mask parameters (Photoshop's units). Refinement is edge-aware: within
+ * `radius` pixels of the mask's edge the coverage is re-estimated from the image with a colour
+ * guided filter (He et al.), so a coarse or misaligned mask (e.g. an AI segmentation) follows
+ * the real edges of the image.
+ */
+interface RefineEdgeParams {
+    /** Edge-detection band radius in pixels (0 = no edge detection). */
+    radius?: number;
+    /** Narrow the band where the image edge is sharp (hair stays soft, hard edges stay hard). */
+    smartRadius?: boolean;
+    /** 0..100: rounds jagged edges. */
+    smooth?: number;
+    /** Pixels of Gaussian softening. */
+    feather?: number;
+    /** 0..100: hardens soft edges. */
+    contrast?: number;
+    /** −100..100: moves the edge out (positive) or in; 100 % is `max(radius, 4)` pixels. */
+    shiftEdge?: number;
+}
+declare const DEFAULT_REFINE_EDGE_PARAMS: Required<RefineEdgeParams>;
+/** Guided-filter regulariser (colour guide, samples in 0..1). */
+declare const GUIDED_FILTER_EPS = 0.0001;
+/** Clamped, complete parameters. */
+declare function normalizeRefineEdgeParams(p?: RefineEdgeParams): Required<RefineEdgeParams>;
+/** Pixels around the mask's content that refinement can read or write. */
+declare function refineEdgeHalo(params?: RefineEdgeParams): number;
+/** Box mean of radius `r` (window clipped to the image, divided by its pixel count). O(1) per pixel. */
+declare function boxMean(src: ArrayLike<number>, w: number, h: number, r: number): Float32Array;
+/**
+ * Guided filter with a colour guide (He et al., Eq. 19–21: `a_k = (Σ_k + εU)⁻¹ cov_k(I, p)`):
+ * filters `p` so that it is locally a linear function of the guide's colour, which makes the
+ * output's edges follow the guide's edges. `guide` is three planes of 0..1 values.
+ */
+declare function guidedFilterColor(guide: readonly [Float32Array, Float32Array, Float32Array], p: Float32Array, w: number, h: number, r: number, eps?: number): Float32Array;
+/**
+ * Per-pixel transition width (pixels) of the guide's luminance: local range over local maximum
+ * gradient in a window of radius `r` (a sharp step gives about 2, a ramp of width L about L).
+ */
+declare function edgeWidth(guide: readonly [Float32Array, Float32Array, Float32Array], w: number, h: number, r: number): Float32Array;
+/**
+ * Refines soft coverage `m` (`w × h`, 0..1) with `guide` (three 0..1 planes, required when
+ * `radius > 0`): edge-aware re-estimation in a band around the edge, then smooth, feather,
+ * contrast and shift edge, in that order.
+ */
+declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams): Float32Array;
+/** Three 0..1 planes of a window of an RGBA buffer. */
+declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float32Array, Float32Array, Float32Array];
+/**
+ * Refine Edge on a selection (or a coarse AI mask loaded as one) against `pixels` (the image,
+ * same size). Work is confined to the mask's bounds grown by {@link refineEdgeHalo}, so a small
+ * selection on a large image stays cheap.
+ */
+declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams): SelectionMask;
+
+type CropHandle = 'nw' | 'ne' | 'se' | 'sw' | 'n' | 's' | 'e' | 'w' | 'inside' | null;
+interface ViewportMetrics {
+    vpWidth: number;
+    vpHeight: number;
+    centerX: number;
+    centerY: number;
+    baseW: number;
+    baseH: number;
+    fitScale: number;
+    renderW: number;
+    renderH: number;
+    totalScale: number;
+    imageRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    cropRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}
+/**
+ * A complete description of the natural-image -> target mapping (see module comment).
+ */
+interface ImageProjection {
+    /** Visible region in natural image pixels (crop box or full image). */
+    region: CropBox;
+    /** Rotation in degrees, normalised to [0, 360). */
+    angle: number;
+    flipH: boolean;
+    flipV: boolean;
+    /** Uniform scale from image pixels to target pixels. */
+    scale: number;
+    /** Target-space point that the centre of `region` maps to. */
+    originX: number;
+    originY: number;
+}
+/** Normalises any rotation in degrees to [0, 360). */
+declare function normalizeAngle(degrees: number): number;
+/** Whether the rotation swaps the displayed width and height. */
+declare function isQuarterTurnSwapped(transform: Pick<ImageTransform, 'rotate'>): boolean;
+/** Size of a region once rotated (bounding box for arbitrary angles). */
+declare function getRotatedSize(width: number, height: number, transform: Pick<ImageTransform, 'rotate'>): {
+    width: number;
+    height: number;
+};
+/** Maps a natural-image point to target space. */
+declare function projectImagePoint(pt: ImagePoint, p: ImageProjection): ImagePoint;
+/** Exact inverse of {@link projectImagePoint}. */
+declare function unprojectCanvasPoint(pt: ImagePoint, p: ImageProjection): ImagePoint;
+/**
+ * Applies the projection to a 2D context so that subsequent drawing in natural image
+ * pixels lands exactly where {@link projectImagePoint} says it does.
+ */
+declare function applyImageProjectionToContext(ctx: Pick<CanvasRenderingContext2D, 'translate' | 'scale' | 'rotate'>, p: ImageProjection): void;
+/** Projects an image-space rectangle and returns its target-space bounding box. */
+declare function projectImageRect(rect: CropBox, p: ImageProjection): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Clamps a crop box to the image bounds. */
+declare function clampCropToImage(crop: CropBox, width: number, height: number): CropBox;
+/**
+ * Returns the natural-image -> canvas projection used by the interactive viewport.
+ */
+declare function getViewportProjection(state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean, cropOverride?: CropBox | null): ImageProjection;
+/**
+ * Calculates current viewport projection metrics for canvas <-> image coordinate mapping.
+ * `cropRect` is the on-screen (rotated/flipped) rectangle of the crop box.
+ */
+declare function getViewportMetrics(state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean, cropOverride?: CropBox | null): ViewportMetrics;
+/**
+ * Converts a point on the canvas (in internal canvas pixel space) to natural image pixel
+ * space, accounting for zoom, pan, fit scale, crop offset, rotation and flips.
+ */
+declare function canvasToImagePoint(canvasPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean): ImagePoint;
+/**
+ * Converts a point in natural image pixel space to internal canvas pixel space.
+ * Exact inverse of {@link canvasToImagePoint}.
+ */
+declare function imageToCanvasPoint(imgPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean): ImagePoint;
+/**
+ * Converts a crop handle in screen orientation to the equivalent edge/corner of the crop
+ * box in natural image space, or the reverse with `toScreen = true`.
+ */
+declare function mapCropHandle(handle: CropHandle, transform: ImageTransform, toScreen?: boolean): CropHandle;
+/**
+ * Hit-tests the crop box and its corner/edge handles given a canvas point.
+ * The returned handle names the edge/corner of the crop box in natural image space
+ * (what {@link calculateCropDrag} expects); use `getCropCursor(handle, state.transform)`
+ * to obtain the matching on-screen cursor.
+ */
+declare function hitTestCrop(canvasPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, handleThreshold?: number, cropOverride?: CropBox | null): CropHandle;
+/**
+ * Returns CSS cursor style corresponding to a crop handle. Pass the current transform when
+ * the handle comes from {@link hitTestCrop} (image space) so the cursor matches the
+ * on-screen orientation under rotation/flip.
+ */
+declare function getCropCursor(handle: CropHandle, transform?: ImageTransform): string;
+/**
+ * Calculates updated crop rectangle given a drag interaction.
+ */
+declare function calculateCropDrag(startCrop: CropBox, handle: CropHandle, startImgPt: ImagePoint, currentImgPt: ImagePoint, imgWidth: number, imgHeight: number, aspectRatio?: number | null, transform?: ImageTransform): CropBox;
+/**
+ * Calculates bounding box of an annotation.
+ */
+declare function getAnnotationBounds(ann: Annotation): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Hit tests if a point in image space is within an annotation's bounds.
+ */
+declare function hitTestAnnotation(imgPt: ImagePoint, ann: Annotation, padding?: number): boolean;
+
+/** Properties of a layer mask that leave its pixels intact (Photoshop's Properties › Masks). */
+interface LayerMaskProps {
+    /** 0..1 (default 1): at 0.5 the masked-out areas still get half of the adjustment. */
+    density?: number;
+    /** Gaussian feather σ in pixels, 0..1000 (default 0). */
+    feather?: number;
+    /** Disabled masks are kept but ignored (the layer applies everywhere). Default true. */
+    enabled?: boolean;
+}
+/**
+ * A clean layer mask from stored data, or `null` when it is unusable. Defaults are left out
+ * (density 1, feather 0, enabled), so a plain mask serializes as `{width, height, rle}`. The
+ * RLE is only decoded when rendering.
+ */
+declare function normalizeLayerMask(raw: unknown): AdjustmentLayerMask | null;
+/** A layer mask holding the selection's pixels (Add Layer Mask › Reveal Selection). */
+declare function layerMaskFromSelection(selection: SelectionMask, props?: LayerMaskProps): AdjustmentLayerMask;
+/** Applies property changes; `undefined` fields keep their value. */
+declare function updateLayerMaskProps(mask: AdjustmentLayerMask, props: LayerMaskProps): AdjustmentLayerMask;
+/** The mask's pixels as a selection (Load Selection from mask), or `null` when the data is damaged. */
+declare function decodeLayerMask(mask: AdjustmentLayerMask): SelectionMask | null;
+/** Cache key of everything about a mask that changes pixels. */
+declare function layerMaskKey(mask: AdjustmentLayerMask | undefined): string;
+/**
+ * The mask's effective coverage (0..1, mask resolution): feathered (σ = feather, borders
+ * replicated), then density applied as `1 − density·(1 − v)`. `null` for a disabled or damaged
+ * mask, meaning "no mask".
+ */
+declare function layerMaskCoverage(mask: AdjustmentLayerMask): Float32Array | null;
+/**
+ * Resamples mask coverage (natural-image aligned, any resolution) into a target raster drawn
+ * through `projection` (the base canvas of the renderer: crop, rotation, flips): each target
+ * pixel centre is unprojected to natural pixels and sampled bilinearly.
+ */
+declare function projectMaskCoverage(coverage: Float32Array, maskWidth: number, maskHeight: number, naturalWidth: number, naturalHeight: number, projection: ImageProjection, targetWidth: number, targetHeight: number): Float32Array;
+/**
+ * Per-layer mask coverage for a render target, keyed by layer id; `undefined` when no layer has
+ * an enabled, valid mask (so mask-free stacks take the exact same path as before).
+ */
+declare function buildLayerMaskPlanes(layers: readonly AdjustmentLayer[] | undefined, naturalWidth: number, naturalHeight: number, projection: ImageProjection, targetWidth: number, targetHeight: number): Map<string, Float32Array> | undefined;
+
+/** Latest serialized schema version (`2`: adjustment layers). */
+declare const IMAGE_EDITOR_SCHEMA_VERSION: 2;
+/** Changes to an adjustment layer; `params` is merged into the current parameters. */
+interface AdjustmentLayerUpdate<K extends AdjustmentKind = AdjustmentKind> {
+    params?: Partial<AdjustmentParamsMap[K]>;
+    enabled?: boolean;
+    opacity?: number;
+    blend?: BlendMode;
+    name?: string;
+    /** A layer mask, or `null` to remove it. */
+    mask?: AdjustmentLayerMask | null;
+}
+/** Options shared by the selection commands. */
+interface SelectionCommandOptions {
+    /** How the result combines with the current selection (default `replace`). */
+    mode?: SelectionMode;
+    /** Feather the new shape by this many pixels before combining (default 0). */
+    feather?: number;
+}
+/** Where the selection tools read colours from. */
+interface SampleOptions {
+    /** Sample the adjusted image (base adjustments and layers) instead of the source pixels. */
+    sampleMerged?: boolean;
+    /** Pixels to use instead of reading the source image (natural size, RGBA). */
+    pixels?: PixelBuffer;
+}
+/** A new adjustment layer: its kind plus optional initial values. */
+interface AdjustmentLayerInit<K extends AdjustmentKind = AdjustmentKind> extends AdjustmentLayerUpdate<K> {
+    kind: K;
+    id?: string;
+}
 declare const DEFAULT_ADJUSTMENTS: ImageAdjustments;
 /**
  * Fills in defaults for stored adjustments. A stored object without `process` was saved before
  * process versions existed and keeps the legacy rendering.
  */
 declare function normalizeStoredAdjustments(stored: Partial<ImageAdjustments> | undefined | null): ImageAdjustments;
+/**
+ * Brings a stored editor state of any schema version to the current shape. Version 1 (and a
+ * missing version) has no adjustment layers; everything else is unchanged, so old states load
+ * and render exactly as before.
+ */
+declare function migrateSerializedImageEditorState(data: Partial<SerializedImageEditorState> & {
+    version?: number;
+}): SerializedImageEditorState;
 declare const DEFAULT_TRANSFORM: ImageTransform;
 declare const DEFAULT_DEPTH_MASK: DepthMaskOptions;
 /**
@@ -401,12 +1164,16 @@ declare class ImageEditorController {
     private renderer;
     private imageElement;
     private listeners;
+    private histogramListeners;
     private onStateChange?;
     private undoStack;
     private redoStack;
     private maxHistoryDepth;
     private isApplyingHistory;
     private initialSnapshot;
+    /** Pixels the selection tools sample (host-provided or read back from the source). */
+    private samplePixels;
+    private samplePixelsOverride;
     constructor(options?: ImageEditorOptions);
     /**
      * Loads a new source image and makes it the baseline that `reset()` returns to.
@@ -443,7 +1210,111 @@ declare class ImageEditorController {
      * rendering process (one undo step). Returns false when already current.
      */
     upgradeProcess(): boolean;
+    /** Resets the base sliders (latest process). Adjustment layers are kept; see `clearAdjustmentLayers`. */
     resetAdjustments(): void;
+    /** The adjustment layers, bottom (first) to top (last). */
+    getAdjustmentLayers(): AdjustmentLayer[];
+    getAdjustmentLayer(id: string): AdjustmentLayer | undefined;
+    private setLayers;
+    /**
+     * Adds an adjustment layer on top (or at `index`, 0 = bottom) as one undo step and returns
+     * its id. `kind` alone gives neutral parameters.
+     */
+    addAdjustmentLayer<K extends AdjustmentKind>(init: K | AdjustmentLayerInit<K>, index?: number): string;
+    /**
+     * Updates a layer (`params` merged into the current ones, then normalised). Pass
+     * `commitToHistory = false` for the moves of a drag after recording its start once.
+     * Returns false for an unknown id.
+     */
+    updateAdjustmentLayer(id: string, update: AdjustmentLayerUpdate, commitToHistory?: boolean): boolean;
+    /** Removes a layer as one undo step. Returns false for an unknown id. */
+    removeAdjustmentLayer(id: string): boolean;
+    /** Moves a layer to `toIndex` (0 = bottom) as one undo step. Returns false if nothing moved. */
+    moveAdjustmentLayer(id: string, toIndex: number): boolean;
+    /** Shows or hides a layer (flips it without `enabled`) as one undo step. */
+    toggleAdjustmentLayer(id: string, enabled?: boolean): boolean;
+    /** Removes every adjustment layer as one undo step. */
+    clearAdjustmentLayers(): void;
+    /** The active selection, or `null`. */
+    getSelection(): SelectionMask | null;
+    get hasSelection(): boolean;
+    private get naturalSize();
+    private dropMismatchedSelection;
+    /**
+     * Replaces the selection, or combines `mask` with it by `mode`, as one undo step. A mask of a
+     * different size (e.g. an AI segmentation at another resolution) is resampled to the image.
+     * Returns false when nothing changed.
+     */
+    setSelection(mask: SelectionMask | null, mode?: SelectionMode): boolean;
+    /** Select › All. */
+    selectAll(): boolean;
+    /** Select › Deselect. */
+    deselect(): boolean;
+    /** Select › Inverse (with nothing selected, selects everything). */
+    invertSelection(): boolean;
+    private shapeCommand;
+    /** Rectangular marquee in natural image pixels. */
+    selectRect(rect: CropBox, options?: SelectionCommandOptions & ShapeSelectionOptions): boolean;
+    /** Elliptical marquee inscribed in `rect`. */
+    selectEllipse(rect: CropBox, options?: SelectionCommandOptions & ShapeSelectionOptions): boolean;
+    /** Lasso / polygonal lasso. */
+    selectPolygon(points: ImagePoint[], options?: SelectionCommandOptions & ShapeSelectionOptions): boolean;
+    /**
+     * Supplies the pixels the selection tools sample (natural size RGBA), e.g. decoded in a worker
+     * or in a test; `null` goes back to reading the source image. A new source image clears it.
+     */
+    setSamplePixels(pixels: PixelBuffer | null): void;
+    /**
+     * The pixels the selection tools sample: the source image at natural size, or with
+     * `sampleMerged` the source after the base adjustments and adjustment layers (no crop,
+     * rotation or annotations). `null` without pixel access (no DOM, tainted canvas).
+     */
+    getSamplePixels(options?: SampleOptions): Promise<PixelBuffer | null>;
+    private requirePixels;
+    /**
+     * Magic wand at `point` (natural image pixels). Resolves to the resulting selection (null when
+     * nothing is selected).
+     */
+    magicWand(point: ImagePoint, options?: MagicWandOptions & SelectionCommandOptions & SampleOptions): Promise<SelectionMask | null>;
+    /** Select › Color Range with colour samples (`#rrggbb` or `[r, g, b]`, optionally where they were picked). */
+    selectColorRange(samples: ColorRangeSample[], options?: ColorRangeOptions & SelectionCommandOptions & SampleOptions): Promise<SelectionMask | null>;
+    /** Select › Modify: grow, shrink, feather, border or smooth by `radius` pixels (one undo step). */
+    modifySelection(op: SelectionModifyOp, radius: number): boolean;
+    /**
+     * Refine Edge: snaps the selection (e.g. a coarse AI mask loaded with `loadSelectionFromImage`)
+     * to the image's edges with a guided filter, then smooth / feather / contrast / shift edge.
+     */
+    refineSelection(params: RefineEdgeParams, options?: SampleOptions): Promise<boolean>;
+    /**
+     * Loads a selection from a mask image (an AI segmentation, a saved mask): a data URL / URL or
+     * RGBA pixels, by luminance (white = selected) or a channel. Any size; it is resampled.
+     */
+    loadSelectionFromImage(source: string | PixelBuffer, options?: {
+        channel?: SelectionChannel;
+        invert?: boolean;
+        threshold?: number;
+        mode?: SelectionMode;
+    }): Promise<SelectionMask | null>;
+    /** Quick Mask view (tints the unselected area). View state: no undo step. */
+    setQuickMask(on: boolean): void;
+    /**
+     * Adds the selection as the layer's mask (Reveal Selection), replacing any mask, as one undo
+     * step. Without a selection, returns false.
+     */
+    applySelectionAsLayerMask(layerId: string, props?: LayerMaskProps): boolean;
+    /** Sets (from a selection-shaped mask) or removes (`null`) a layer's mask as one undo step. */
+    setAdjustmentLayerMask(layerId: string, mask: SelectionMask | null, props?: LayerMaskProps): boolean;
+    /** Changes a layer mask's density (0..1), feather (px) or enabled flag; the mask pixels are kept. */
+    setAdjustmentLayerMaskProps(layerId: string, props: LayerMaskProps, commitToHistory?: boolean): boolean;
+    /** Load Selection from a layer mask (its pixels; density and feather are not applied). */
+    selectionFromLayerMask(layerId: string, mode?: SelectionMode): boolean;
+    /**
+     * Histogram of the last rendered preview (after adjustments and layers, before annotations),
+     * or `null` before the first render or without canvas pixel access.
+     */
+    getHistogram(): ImageHistogram | null;
+    /** Calls `listener` now and whenever a render produces a new preview histogram. */
+    subscribeHistogram(listener: (histogram: ImageHistogram | null) => void): () => void;
     setDepthMask(partial: Partial<DepthMaskOptions>): void;
     resetDepthMask(): void;
     addAnnotation(annotation: CreateAnnotationPayload): string;
@@ -464,10 +1335,12 @@ declare class ImageEditorController {
     renderMask(options?: {
         useAnnotations?: boolean;
         useCrop?: boolean;
+        useSelection?: boolean;
     }): Promise<HTMLCanvasElement>;
     toMaskDataURL(options?: {
         useAnnotations?: boolean;
         useCrop?: boolean;
+        useSelection?: boolean;
     }): Promise<string>;
     /**
      * Renders the current source image at natural size with no crop, rotation, flip,
@@ -487,133 +1360,412 @@ declare class ImageEditorController {
      */
     applyBackgroundRemovedImage(newDataUrl: string): Promise<void>;
     private replaceSource;
+    /** The serializable state; `selection` is included (run-length encoded) only when something is selected. */
     toJSON(): SerializedImageEditorState;
     loadJSON(data: SerializedImageEditorState): void;
     private serializeState;
     private applySerializedState;
 }
 
-type CropHandle = 'nw' | 'ne' | 'se' | 'sw' | 'n' | 's' | 'e' | 'w' | 'inside' | null;
-interface ViewportMetrics {
-    vpWidth: number;
-    vpHeight: number;
-    centerX: number;
-    centerY: number;
-    baseW: number;
-    baseH: number;
-    fitScale: number;
-    renderW: number;
-    renderH: number;
-    totalScale: number;
-    imageRect: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-    cropRect: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    } | null;
+/** The `version` that `ImageEditorController.toJSON()` writes. */
+declare const IMAGE_EDITOR_STATE_VERSION = 1;
+/**
+ * Migration steps for `SerializedImageEditorState`, keyed by the version they
+ * start from. Empty while only version 1 exists.
+ */
+declare const imageEditorStateMigrations: Record<number, MigrationStep>;
+interface ImageEditorDocumentLoad {
+    /** State to pass to `loadJSON` / `initialState`. */
+    state: SerializedImageEditorState;
+    report: LoadReport;
+    /** Top-level keys this build does not know; spread them into the saved JSON to keep them. */
+    unknown: JsonObject;
 }
 /**
- * A complete description of the natural-image -> target mapping (see module comment).
+ * Loads stored image editor state (a JSON string or object) with a `LoadReport`:
+ *
+ * - Runs `imageEditorStateMigrations` up to `IMAGE_EDITOR_STATE_VERSION`; a missing
+ *   `version` is taken as current.
+ * - A newer `version` is still loaded but reported `readOnly`: do not save over it.
+ * - Each section (`crop`, `transform`, `adjustments`, `depthMask`, `annotations`, and the
+ *   optional run-length encoded `selection`)
+ *   falls back to its default on its own; invalid annotations are dropped one by one.
+ * - Unknown top-level keys are returned in `unknown`.
+ *
+ * Valid state from `toJSON()` comes back unchanged, so `loadJSON(state)` behaves
+ * exactly as with the raw object.
  */
-interface ImageProjection {
-    /** Visible region in natural image pixels (crop box or full image). */
-    region: CropBox;
-    /** Rotation in degrees, normalised to [0, 360). */
-    angle: number;
-    flipH: boolean;
-    flipV: boolean;
-    /** Uniform scale from image pixels to target pixels. */
-    scale: number;
-    /** Target-space point that the centre of `region` maps to. */
-    originX: number;
-    originY: number;
+declare function loadImageEditorDocument(input: unknown): ImageEditorDocumentLoad;
+
+/**
+ * Adjustment layers: Photoshop-matching evaluation on encoded sRGB colours in 0..1.
+ *
+ * Every layer is compiled once per parameter change into a per-pixel function (per-channel kinds
+ * into three 4096-entry LUTs); {@link applyAdjustmentLayers} runs the stack on an ImageData.
+ */
+type Rgb = [number, number, number];
+/** Entries in a tone LUT (curves, levels, colour balance). */
+declare const ADJUSTMENT_LUT_SIZE = 4096;
+/** Linear interpolation into a 0..1-domain LUT. */
+declare function sampleLut(table: ArrayLike<number>, v: number): number;
+interface AdjustmentKindInfo {
+    kind: AdjustmentKind;
+    label: string;
 }
-/** Normalises any rotation in degrees to [0, 360). */
-declare function normalizeAngle(degrees: number): number;
-/** Whether the rotation swaps the displayed width and height. */
-declare function isQuarterTurnSwapped(transform: Pick<ImageTransform, 'rotate'>): boolean;
-/** Size of a region once rotated (bounding box for arbitrary angles). */
-declare function getRotatedSize(width: number, height: number, transform: Pick<ImageTransform, 'rotate'>): {
-    width: number;
-    height: number;
-};
-/** Maps a natural-image point to target space. */
-declare function projectImagePoint(pt: ImagePoint, p: ImageProjection): ImagePoint;
-/** Exact inverse of {@link projectImagePoint}. */
-declare function unprojectCanvasPoint(pt: ImagePoint, p: ImageProjection): ImagePoint;
+declare const ADJUSTMENT_KINDS: readonly AdjustmentKindInfo[];
+declare function isAdjustmentKind(value: unknown): value is AdjustmentKind;
+declare function adjustmentKindLabel(kind: AdjustmentKind): string;
+declare const HUE_RANGE_LABELS: readonly ["Reds", "Yellows", "Greens", "Cyans", "Blues", "Magentas"];
+/** The neutral range `i` (0 reds … 5 magentas): fully on for 30° around its centre, fading over 30° each side. */
+declare function neutralHueRange(i: number): HueRange;
+declare const identityCurve: () => CurvePoint[];
+declare const identityLevels: () => LevelsChannel;
+/** Neutral parameters of every kind (fresh objects on every call). */
+declare function defaultAdjustmentParams<K extends AdjustmentKind>(kind: K): AdjustmentParamsMap[K];
+/** A new layer of `kind` with neutral (or the given) parameters, enabled, opacity 1, normal blend. */
+declare function createAdjustmentLayer<K extends AdjustmentKind>(kind: K, options?: {
+    id?: string;
+    name?: string;
+    params?: Partial<AdjustmentParamsMap[K]>;
+    enabled?: boolean;
+    opacity?: number;
+    blend?: BlendMode;
+    mask?: AdjustmentLayerMask;
+}): AdjustmentLayerOf<K>;
 /**
- * Applies the projection to a 2D context so that subsequent drawing in natural image
- * pixels lands exactly where {@link projectImagePoint} says it does.
+ * A clean, deep-copied layer from stored or hand-written data: missing fields get neutral
+ * defaults, numbers are clamped to their ranges. `null` for an unknown kind.
  */
-declare function applyImageProjectionToContext(ctx: Pick<CanvasRenderingContext2D, 'translate' | 'scale' | 'rotate'>, p: ImageProjection): void;
-/** Projects an image-space rectangle and returns its target-space bounding box. */
-declare function projectImageRect(rect: CropBox, p: ImageProjection): {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
-/** Clamps a crop box to the image bounds. */
-declare function clampCropToImage(crop: CropBox, width: number, height: number): CropBox;
+declare function normalizeAdjustmentLayer(raw: unknown): AdjustmentLayer | null;
+/** Normalises a stored layer list (drops unknown kinds, de-duplicates ids). */
+declare function normalizeAdjustmentLayers(raw: unknown): AdjustmentLayer[];
 /**
- * Returns the natural-image -> canvas projection used by the interactive viewport.
+ * Photoshop curve: a natural cubic spline through the points (0..1 in and out; it may overshoot
+ * between points, as Photoshop's does), constant outside the first / last point, clamped to
+ * 0..1, sampled into a LUT. Fewer than two distinct points: the identity.
  */
-declare function getViewportProjection(state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean, cropOverride?: CropBox | null): ImageProjection;
+declare function curveLut(points: ReadonlyArray<{
+    input: number;
+    output: number;
+}>, size?: number): Float32Array;
+/** {@link curveLut} for Curves points in levels (0..255). */
+declare function curveLutFromLevels(points: readonly CurvePoint[]): Float32Array;
+/** A Levels record with values in 0..1 (as `levelsValue` takes them). */
+interface UnitLevels {
+    inBlack: number;
+    inWhite: number;
+    gamma: number;
+    outBlack: number;
+    outWhite: number;
+}
 /**
- * Calculates current viewport projection metrics for canvas <-> image coordinate mapping.
- * `cropRect` is the on-screen (rotated/flipped) rectangle of the crop box.
+ * One Levels record on `v` (0..1). With `quantum` (8-bit: 255) Photoshop works on whole levels:
+ * the input is a level and the stretch is rounded (half up) before the gamma. A gamma above 1 has
+ * Photoshop's soft shadow toe: a p-norm soft-min of the power curve and a line of slope ≈ 2^gamma.
  */
-declare function getViewportMetrics(state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean, cropOverride?: CropBox | null): ViewportMetrics;
+declare function levelsValue(ch: UnitLevels, v: number, quantum?: number): number;
+/** RGB (0..1) → HSL with hue in turns (0..1). */
+declare function rgbToHsl(c: readonly number[]): [number, number, number];
+declare function hslToRgb(h: number, s: number, l: number): Rgb;
+/** How much a pixel of hue `deg` belongs to `range` (0..1): a trapezoid that may wrap past 0/360. */
+declare function hueRangeWeight(range: Pick<HueRange, 'bounds'>, deg: number): number;
+/** Range edits as three hue-indexed tables (hue shift in degrees, saturation and lightness as fractions). */
+declare function hueRangeTables(ranges: readonly HueRange[]): [Float32Array, Float32Array, Float32Array];
 /**
- * Converts a point on the canvas (in internal canvas pixel space) to natural image pixel
- * space, accounting for zoom, pan, fit scale, crop offset, rotation and flips.
+ * One Hue/Saturation evaluation: hue shift in degrees, saturation and lightness in -1..1.
+ * Lightness first, then hue and saturation (raising divides by 1 − s, lowering multiplies by
+ * 1 + s). Colorize sets hue and saturation at the lightened lightness.
  */
-declare function canvasToImagePoint(canvasPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean): ImagePoint;
+declare function hueSaturation(c: readonly number[], hue: number, s: number, l: number, colorize: boolean): Rgb;
+/** A colour range's Lightness: towards the brightest channel when raised, the darkest when lowered. */
+declare function rangeLightness(c: readonly number[], l: number): Rgb;
+/** Grey Vibrance › Saturation desaturates to (linear light; blue has no weight). */
+declare const VIBRANCE_GREY: readonly [number, number];
+/** The Vibrance slider (`v` in -1..1) on a linear-light pixel: an HSV change that keeps the hue. */
+declare function vibranceLinear(c: Rgb, v: number): Rgb;
+/** Photoshop's Vibrance on one encoded sRGB pixel (`v`, `s`: the sliders / 100). */
+declare function vibrancePixel(c: readonly number[], v: number, s: number): Rgb;
 /**
- * Converts a point in natural image pixel space to internal canvas pixel space.
- * Exact inverse of {@link canvasToImagePoint}.
+ * Color Balance on channel `ch` (0 red, 1 green, 2 blue) of `v` (0..1); `tones` are the
+ * shadows, midtones and highlights slider triples (-100..100). Highlights, shadows, then midtones.
  */
-declare function imageToCanvasPoint(imgPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean): ImagePoint;
+declare function colorBalanceChannel(tones: readonly [readonly number[], readonly number[], readonly number[]], preserveLuminosity: boolean, ch: number, v: number): number;
 /**
- * Converts a crop handle in screen orientation to the equivalent edge/corner of the crop
- * box in natural image space, or the reverse with `toScreen = true`.
+ * Black & White grey: the smallest channel, plus the secondary part (middle − smallest) and the
+ * primary part (largest − middle) weighted by the sliders (percent: reds, yellows, greens, cyans,
+ * blues, magentas).
  */
-declare function mapCropHandle(handle: CropHandle, transform: ImageTransform, toScreen?: boolean): CropHandle;
+declare function blackWhiteGray(c: readonly number[], weights: readonly number[]): number;
 /**
- * Hit-tests the crop box and its corner/edge handles given a canvas point.
- * The returned handle names the edge/corner of the crop box in natural image space
- * (what {@link calculateCropDrag} expects); use `getCropCursor(handle, state.transform)`
- * to obtain the matching on-screen cursor.
+ * Photo Filter's linear-light RGB matrix (row-major 3×3): the pixel's D50 XYZ, relative to white,
+ * multiplied by the filter colour's mixed in by `density` (0..1). `normalizeY` keeps luminance Y.
  */
-declare function hitTestCrop(canvasPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, handleThreshold?: number, cropOverride?: CropBox | null): CropHandle;
+declare function photoFilterMatrix(color: readonly number[], density: number, normalizeY?: boolean): number[][];
+/** Photoshop posterize: `levels` equal input bins over 0..255, outputs `floor(k·255 / (levels − 1))`. */
+declare function posterizeValue(v: number, levels: number): number;
+/** Rec.601 luma (Photoshop's grey for Threshold). */
+declare const rgbToGray: (c: readonly number[]) => number;
+/** `#rrggbb` → 0..1 RGB (black for anything else). */
+declare function hexToRgb(hex: string): Rgb;
+/** Mutates an encoded sRGB colour (0..1) in place. */
+type PixelOp = (c: Rgb) => void;
 /**
- * Returns CSS cursor style corresponding to a crop handle. Pass the current transform when
- * the handle comes from {@link hitTestCrop} (image space) so the cursor matches the
- * on-screen orientation under rotation/flip.
+ * Per-channel LUTs of a Curves or Levels layer: each channel's record first, then the master.
+ * `null` for any other kind.
  */
-declare function getCropCursor(handle: CropHandle, transform?: ImageTransform): string;
+declare function toneLuts(layer: AdjustmentLayer): [Float32Array, Float32Array, Float32Array] | null;
 /**
- * Calculates updated crop rectangle given a drag interaction.
+ * Compiles a layer into a pixel function, or `null` when it is the identity (neutral parameters).
+ * Pure: depends on `kind` and `params` only.
  */
-declare function calculateCropDrag(startCrop: CropBox, handle: CropHandle, startImgPt: ImagePoint, currentImgPt: ImagePoint, imgWidth: number, imgHeight: number, aspectRatio?: number | null, transform?: ImageTransform): CropBox;
+declare function compileAdjustmentLayer(layer: AdjustmentLayer): PixelOp | null;
+/** Layers that change pixels: enabled, visible, not the identity. */
+declare function activeAdjustmentLayers(layers: readonly AdjustmentLayer[] | undefined): AdjustmentLayer[];
 /**
- * Calculates bounding box of an annotation.
+ * Evaluates one colour (encoded sRGB, 0..1) through a layer stack: each layer adjusts the result
+ * of the layers below and is blended over it with its blend mode and opacity (an opaque
+ * backdrop, so `(1 − α)·Cb + α·B(Cb, Cs)`).
  */
-declare function getAnnotationBounds(ann: Annotation): {
+declare function evaluateAdjustmentLayers(color: readonly number[], layers: readonly AdjustmentLayer[]): Rgb;
+/**
+ * Applies an adjustment-layer stack to 8-bit straight RGBA pixels in place. Each pixel is
+ * decoded once, run through every layer in float, and encoded once. Transparent pixels are
+ * left alone; alpha is never changed.
+ *
+ * `masks` (layer id → 0..1 coverage per pixel of `imageData`, see `buildLayerMaskPlanes`)
+ * scales each masked layer's opacity per pixel: coverage 0 leaves the pixel as the layers below
+ * made it, 1 applies the layer fully.
+ */
+declare function applyAdjustmentLayers(imageData: Pick<ImageData, 'data'>, layers: readonly AdjustmentLayer[] | undefined, masks?: ReadonlyMap<string, ArrayLike<number>>): void;
+/** Stable cache key of a layer stack's pixel effect (for renderer caches). */
+declare function adjustmentLayersKey(layers: readonly AdjustmentLayer[] | undefined): string;
+
+/**
+ * Control specs: one table describes every numeric adjustment slider (id, label, section, range,
+ * default, step, display precision and track style). The React and Svelte panels render from it,
+ * the agent tools expose it as a schema, and values are addressed by id.
+ */
+type ControlSection = 'light' | 'color' | 'effects' | 'layer';
+/** How a slider track is drawn. */
+type ControlTrack = 
+/** Plain track, fill from the minimum. */
+{
+    kind: 'plain';
+}
+/** Zero in the middle. */
+ | {
+    kind: 'centered';
+}
+/** Blue → yellow (white-balance temperature). */
+ | {
+    kind: 'temp';
+}
+/** Green → magenta (tint). */
+ | {
+    kind: 'tint';
+}
+/** A two-colour gradient. */
+ | {
+    kind: 'gradient';
+    from: string;
+    to: string;
+}
+/** Full hue rainbow. */
+ | {
+    kind: 'rainbow';
+};
+interface ControlSpec {
+    /** Dotted path of the value (`exposure`; inside a layer's params: `midtones.0`, `ranges.4.hue`). */
+    id: string;
+    label: string;
+    section: ControlSection;
+    min: number;
+    max: number;
+    step: number;
+    default: number;
+    /** Decimal places shown (after `displayScale`). */
+    decimals: number;
+    track: ControlTrack;
+    /** Multiplier for display (opacity 0..1 shows as 0..100 %). */
+    displayScale?: number;
+    /** Unit suffix for display (`px`, `%`, `°`). */
+    unit?: string;
+    /** The rendering process the control needs (tint: process 2). */
+    requiresProcess?: 1 | 2;
+}
+/** Every numeric base adjustment, in panel order. */
+declare const IMAGE_ADJUSTMENT_CONTROLS: readonly ControlSpec[];
+/**
+ * Numeric parameters of each adjustment-layer kind, addressed inside `layer.params`. Curves points
+ * and booleans / colours (colorize, preserve luminosity, tint, filter colour) are edited by the
+ * dedicated controls, not sliders.
+ */
+declare const ADJUSTMENT_LAYER_CONTROLS: Readonly<Record<AdjustmentKind, readonly ControlSpec[]>>;
+/** Opacity of any adjustment layer (0..1, shown as %). */
+declare const ADJUSTMENT_LAYER_OPACITY_CONTROL: ControlSpec;
+/** The base-adjustment control with this id. */
+declare function findAdjustmentControl(id: string): ControlSpec | undefined;
+/** The control of a layer parameter (`opacity` included). */
+declare function findLayerControl(kind: AdjustmentKind, id: string): ControlSpec | undefined;
+/** `v` clamped to the control's range and snapped to its step; non-finite values give the default. */
+declare function clampControlValue(spec: ControlSpec, v: unknown): number;
+/** A value as the slider shows it (`+12`, `35%`, `4px`). */
+declare function formatControlValue(spec: ControlSpec, v: number): string;
+/** Where `v` sits on the track, 0 (left) to 1 (right). */
+declare function controlPosition(spec: ControlSpec, v: number): number;
+/** CSS background for a control's track. */
+declare function controlTrackBackground(spec: ControlSpec): string | undefined;
+/** Reads a dotted path (`ranges.2.hue`) from an object. */
+declare function getControlPath(obj: unknown, path: string): unknown;
+/** A copy of `obj` with the dotted path set (arrays and objects along the path are cloned). */
+declare function setControlPath<T>(obj: T, path: string, value: unknown): T;
+/** The base adjustment values the control table describes. */
+declare function readAdjustmentControls(adjustments: ImageAdjustments): Record<string, number>;
+
+interface ImageEditorToolProviderOptions {
+    /** Provider id (unique per registry). Default `image-editor`. */
+    id?: string;
+    /** Always prefix tool names with `<namespace>__`. */
+    namespace?: string;
+}
+/**
+ * Agent tools for an image editor, for a `ToolRegistry`:
+ *
+ * - `get_adjustments`: base slider values (by control id), process version and adjustment layers.
+ * - `list_controls`: the control table (ids, ranges, defaults, steps), layer kinds and blend modes.
+ * - `set_adjustments {values, label}`: sets base controls (`exposure`) and layer parameters
+ *   (`layers.<id>.vibrance`, `layers.<id>.opacity`) in one undo step; values are clamped to the
+ *   control ranges and the applied values are echoed.
+ * - `add_adjustment_layer {kind, params?, opacity?, blend?, name?}`.
+ * - `render_preview {maxSide}`: the rendered image as a PNG, longest side at most `maxSide`.
+ * - Selections and masks: `get_selection`, `select_region`, `select_by_color`, `modify_selection`,
+ *   `refine_selection`, `apply_selection_as_mask` (see `createImageSelectionTools`).
+ */
+declare function createImageEditorToolProvider(controller: ImageEditorController, options?: ImageEditorToolProviderOptions): AgentToolProvider;
+
+/** Box coordinates of a curve point. */
+declare function curvePointToBox(p: CurvePoint, width: number, height: number): {
     x: number;
     y: number;
-    width: number;
-    height: number;
 };
+/** The curve point (whole levels, clamped) under box coordinates. */
+declare function boxToCurvePoint(x: number, y: number, width: number, height: number): CurvePoint;
+/** An SVG polyline path of the evaluated curve (spline, clamped, constant beyond the end points). */
+declare function curveSvgPath(points: readonly CurvePoint[], width: number, height: number, samples?: number): string;
+/** Index of the point within `radius` box units of (x, y), nearest first; -1 for none. */
+declare function hitTestCurvePoint(points: readonly CurvePoint[], x: number, y: number, width: number, height: number, radius?: number): number;
+/** Inserts a point in input order (replacing one at the same input). Returns the new list and its index. */
+declare function insertCurvePoint(points: readonly CurvePoint[], p: CurvePoint): {
+    points: CurvePoint[];
+    index: number;
+};
+/** Moves point `index`, keeping its input strictly between its neighbours'. */
+declare function moveCurvePoint(points: readonly CurvePoint[], index: number, p: CurvePoint): CurvePoint[];
+/** Removes point `index`; a curve keeps at least two points. */
+declare function removeCurvePoint(points: readonly CurvePoint[], index: number): CurvePoint[];
+
 /**
- * Hit tests if a point in image space is within an annotation's bounds.
+ * The selection's outline at `threshold` (0..255, default 128) as axis-aligned segments on pixel
+ * boundaries, `[x0, y0, x1, y1, …]` in natural image pixels, with collinear neighbours merged.
+ * This is what marching ants are drawn from. Linear in the pixel count.
  */
-declare function hitTestAnnotation(imgPt: ImagePoint, ann: Annotation, padding?: number): boolean;
+declare function selectionOutline(mask: SelectionMask, threshold?: number): Float32Array;
+interface QuickMaskStyle {
+    /** Overlay colour, `[r, g, b]` 0..255 (default Photoshop's rubylith red). */
+    color?: readonly [number, number, number];
+    /** 0..1 (default 0.5): opacity over fully unselected pixels. */
+    opacity?: number;
+}
+/**
+ * Quick Mask view: RGBA pixels (natural image size) tinting the *unselected* area, so the
+ * selection shows through clear, as Photoshop's rubylith overlay.
+ */
+declare function quickMaskPixels(mask: SelectionMask, style?: QuickMaskStyle): Uint8ClampedArray;
+
+/** Selection tools of the image editor UI. */
+type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'lasso';
+declare const SELECTION_TOOLS: readonly {
+    id: SelectionToolKind;
+    label: string;
+}[];
+declare const SELECTION_MODE_LABELS: Record<SelectionMode, string>;
+/** The options bar of the selection tools (shared by the React and Svelte UIs). */
+interface SelectionToolOptions {
+    tool: SelectionToolKind;
+    mode: SelectionMode;
+    /** Magic wand tolerance, 0..255. */
+    tolerance: number;
+    contiguous: boolean;
+    antiAlias: boolean;
+    /** Sample the adjusted image instead of the source. */
+    sampleMerged: boolean;
+    distance: ColorDistance;
+}
+declare const DEFAULT_SELECTION_TOOL_OPTIONS: SelectionToolOptions;
+/**
+ * Photoshop's modifier keys: Shift adds, Alt/Option subtracts, both intersect; otherwise the
+ * options bar mode.
+ */
+declare function selectionModeFromModifiers(modifiers: {
+    shiftKey?: boolean;
+    altKey?: boolean;
+}, fallback: SelectionMode): SelectionMode;
+interface RefineEdgeControl {
+    id: keyof Omit<RefineEdgeParams, 'smartRadius'>;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+    unit: string;
+}
+/** Sliders of the Refine Edge panel. */
+declare const REFINE_EDGE_CONTROLS: readonly RefineEdgeControl[];
+/** A one-line status: "No selection" or "W × H px selected (n % of the image)". */
+declare function describeSelection(mask: SelectionMask | null | undefined): string;
+
+interface GestureModifiers {
+    shiftKey?: boolean;
+    altKey?: boolean;
+}
+/**
+ * Pointer gestures of the selection tools, shared by the React and Svelte image editors: feed
+ * it pointer positions in natural image pixels (`canvasToImagePoint(..., false)`).
+ *
+ * - Magic wand: selects on `begin` (async, as it may read pixels).
+ * - Rectangle / ellipse: drag a box; a click without a drag deselects (replace mode).
+ * - Lasso: drag a free-hand path, closed on `end`.
+ *
+ * Shift adds, Alt subtracts, both intersect (overriding the options bar mode). While dragging,
+ * {@link draftPath} is the outline to show (`RenderOptions.draftSelectionPath`).
+ */
+declare class SelectionGesture {
+    readonly controller: ImageEditorController;
+    private readonly getOptions;
+    private start;
+    private points;
+    private current;
+    private modifiers;
+    /** The last error (e.g. pixels unavailable for the wand), for the UI to show. */
+    error: string | null;
+    constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
+    get active(): boolean;
+    /** The outline of the shape being drawn, or `null`. */
+    get draftPath(): ImagePoint[] | null;
+    /** Pointer down. Resolves once a wand click has been applied. */
+    begin(point: ImagePoint, modifiers?: GestureModifiers): Promise<void>;
+    /** Pointer move; returns true when the draft changed (re-render). */
+    move(point: ImagePoint): boolean;
+    /** Pointer up: commits the shape. Returns true when the selection changed. */
+    end(point?: ImagePoint, modifiers?: GestureModifiers): boolean;
+    /** Abandons a drag without changing the selection. */
+    cancel(): void;
+}
+
+/**
+ * Agent tools for selections and masks (part of `createImageEditorToolProvider`):
+ * `get_selection`, `select_region`, `select_by_color`, `modify_selection`, `refine_selection`
+ * and `apply_selection_as_mask`. Coordinates are natural pixels of the source image.
+ */
+declare function createImageSelectionTools(controller: ImageEditorController): AgentTool[];
 
-export { AS_SHOT_KELVIN, type Annotation, type AnnotationType, type ArrowAnnotation, type AspectRatio, type BaseAnnotation, type Chromaticity, type CircleAnnotation, type CreateAnnotationPayload, type CropBox, type CropHandle, D65, DEFAULT_ADJUSTMENTS, DEFAULT_DEPTH_MASK, DEFAULT_TRANSFORM, type DepthMaskOptions, type ExportOptions, IDENTITY_MATRIX3, type ImageAdjustments, type ImageAnnotation, type ImageDimensions, type ImageEditorAIHooks, ImageEditorController, type ImageEditorOptions, ImageEditorRenderer, type ImageEditorState, type ImageEditorTool, type ImagePoint, type ImageProcessVersion, type ImageProjection, type ImageTransform, type InpaintHook, type InpaintOptions, LATEST_PROCESS_VERSION, LEGACY_PROCESS_VERSION, LUMA_709, type LineAnnotation, MAX_KELVIN, MIN_KELVIN, MIRED_PER_TEMPERATURE_UNIT, type Matrix3, type PenAnnotation, type RectAnnotation, type RemoveBackgroundHook, type RemoveBackgroundOptions, type RenderOptions, type SerializedImageEditorState, TINT_SCALE, TONE_LUT_SIZE, type TextAnnotation, type ViewportMetrics, applyAdjustments, applyDepthMask, applyImageProjectionToContext, applyLegacyAdjustments, applyMatrix3, applyProcess2Adjustments, bradfordAdaptation, buildToneLut, calculateCropDrag, canvasToImagePoint, clampCropToImage, getAnnotationBounds, getCropCursor, getRotatedSize, getViewportMetrics, getViewportProjection, globalImageCache, hitTestAnnotation, hitTestCrop, imageToCanvasPoint, invertMatrix3, isQuarterTurnSwapped, kelvinToTemperature, linearSrgbToXy, linearToSrgb, mapCropHandle, mulMatrix3, normalizeAngle, normalizeProcessVersion, normalizeStoredAdjustments, projectImagePoint, projectImageRect, removeAlpha, sampleToneLut, srgbToLinear, tempTintToXy, temperatureToKelvin, toneCurve, unprojectCanvasPoint, uvToXy, wbMatrix, whiteBalanceFromSample, whiteBalanceMatrix, xyToTempTint, xyToUv };
+export { ADJUSTMENT_KINDS, ADJUSTMENT_LAYER_CONTROLS, ADJUSTMENT_LAYER_OPACITY_CONTROL, ADJUSTMENT_LUT_SIZE, AS_SHOT_KELVIN, type AdjustmentKind, type AdjustmentKindInfo, type AdjustmentLayer, type AdjustmentLayerBase, type AdjustmentLayerInit, type AdjustmentLayerMask, type AdjustmentLayerOf, type AdjustmentLayerUpdate, type AdjustmentParamsMap, type Annotation, type AnnotationType, type ArrowAnnotation, type AspectRatio, BLEND_MODES, type BaseAnnotation, type BlackWhiteParams, type BlendMode, type BlendModeInfo, type Chromaticity, type CircleAnnotation, type ColorBalanceParams, type ColorBalanceTone, type ColorDistance, type ColorRangeOptions, type ColorRangeSample, type ControlSection, type ControlSpec, type ControlTrack, type CreateAnnotationPayload, type CropBox, type CropHandle, type CurvePoint, type CurvesParams, D65, DEFAULT_ADJUSTMENTS, DEFAULT_DEPTH_MASK, DEFAULT_REFINE_EDGE_PARAMS, DEFAULT_SELECTION_TOOL_OPTIONS, DEFAULT_TRANSFORM, DIRECT_GAUSSIAN_MAX_SIGMA, type DepthMaskOptions, EMPTY_DISTANCE, type ExportOptions, GUIDED_FILTER_EPS, type GestureModifiers, HISTOGRAM_BINS, HUE_RANGE_LABELS, type HistogramChannel, type HueRange, type HueSaturationParams, IDENTITY_MATRIX3, IMAGE_ADJUSTMENT_CONTROLS, IMAGE_EDITOR_SCHEMA_VERSION, IMAGE_EDITOR_STATE_VERSION, type ImageAdjustments, type ImageAnnotation, type ImageDimensions, type ImageEditorAIHooks, ImageEditorController, type ImageEditorDocumentLoad, type ImageEditorOptions, ImageEditorRenderer, type ImageEditorState, type ImageEditorTool, type ImageEditorToolProviderOptions, type ImageHistogram, type ImagePoint, type ImageProcessVersion, type ImageProjection, type ImageTransform, type InpaintHook, type InpaintOptions, type InvertParams, LATEST_PROCESS_VERSION, LEGACY_PROCESS_VERSION, LUMA_709, type LayerMaskProps, type LevelsChannel, type LevelsParams, type LineAnnotation, MAX_KELVIN, MIN_KELVIN, MIRED_PER_TEMPERATURE_UNIT, type MagicWandOptions, type Matrix3, type PenAnnotation, type PhotoFilterParams, type PixelBuffer, type PixelOp, type PosterizeParams, type QuickMaskStyle, REFINE_EDGE_CONTROLS, type RectAnnotation, type RefineEdgeControl, type RefineEdgeParams, type RemoveBackgroundHook, type RemoveBackgroundOptions, type RenderOptions, type Rgb$1 as Rgb, type Rgba, SELECTION_MODES, SELECTION_MODE_LABELS, SELECTION_MODIFY_OPS, SELECTION_TOOLS, type SampleOptions, type SelectionChannel, type SelectionCommandOptions, SelectionGesture, type SelectionMask, type SelectionMode, type SelectionModifyOp, type SelectionToolKind, type SelectionToolOptions, type SerializedImageEditorState, type SerializedSelection, type ShapeSelectionOptions, TINT_SCALE, TONE_LUT_SIZE, TONE_RANGE_PRESETS, type TextAnnotation, type ThresholdParams, type ToneRangePreset, type UnitLevels, VIBRANCE_GREY, type VibranceParams, type ViewportMetrics, activeAdjustmentLayers, adjustmentKindLabel, adjustmentLayersKey, applyAdjustmentLayers, applyAdjustments, applyDepthMask, applyImageProjectionToContext, applyLegacyAdjustments, applyMatrix3, applyProcess2Adjustments, blackWhiteGray, blendChannel, blendImageData, blendLum, blendPixel, blendRgb, borderCoverage, boxMean, boxToCurvePoint, bradfordAdaptation, buildLayerMaskPlanes, buildToneLut, calculateCropDrag, canvasCompositeOperation, canvasToImagePoint, clampControlValue, clampCropToImage, colorBalanceChannel, colorRange, combineSelections, compileAdjustmentLayer, computeHistogram, computeSelectionBounds, contractCoverage, controlPosition, controlTrackBackground, coverageToByte, createAdjustmentLayer, createImageEditorToolProvider, createImageSelectionTools, createSelectionMask, curveLut, curveLutFromLevels, curvePointToBox, curveSvgPath, decodeLayerMask, decodeSelectionRle, defaultAdjustmentParams, describeSelection, deserializeSelection, distanceTransform, edgeWidth, ellipsePoints, ellipseSelection, encodeSelectionRle, evaluateAdjustmentLayers, expandCoverage, featherCoverage, findAdjustmentControl, findLayerControl, formatControlValue, fullSelection, gaussianBlur, getAnnotationBounds, getControlPath, getCropCursor, getRotatedSize, getViewportMetrics, getViewportProjection, globalImageCache, greyMorphology, guidePlanes, guidedFilterColor, hashMaskContent, hexToRgb, histogramPath, hitTestAnnotation, hitTestCrop, hitTestCurvePoint, hslToRgb, hueRange, hueRangeTables, hueRangeWeight, hueSaturation, identityCurve, identityLevels, imageEditorStateMigrations, imageToCanvasPoint, insertCurvePoint, invertMatrix3, invertSelection, isAdjustmentKind, isBlendMode, isQuarterTurnSwapped, isSelectionEmpty, isSelectionMode, isSeparableBlendMode, kelvinToTemperature, layerMaskCoverage, layerMaskFromSelection, layerMaskKey, levelsValue, linearSrgbToXy, linearToSrgb, loadImageEditorDocument, magicWand, mapCropHandle, migrateSerializedImageEditorState, modifySelection, moveCurvePoint, mulMatrix3, neutralHueRange, normalizeAdjustmentLayer, normalizeAdjustmentLayers, normalizeAngle, normalizeBlendMode, normalizeLayerMask, normalizeProcessVersion, normalizeRect, normalizeRefineEdgeParams, normalizeStoredAdjustments, parseSelectionMode, photoFilterMatrix, polygonCoverage, polygonSelection, posterizeValue, projectImagePoint, projectImageRect, projectMaskCoverage, quickMaskPixels, rangeLightness, readAdjustmentControls, rectSelection, refineCoverage, refineEdgeHalo, refineSelection, removeAlpha, removeCurvePoint, resizeSelection, rgbToGray, rgbToHsl, sampleLut, sampleToneLut, selectionArea, selectionFromCoverage, selectionFromPixels, selectionModeFromModifiers, selectionOutline, selectionToCoverage, selectionToPixels, selectionValueAt, serializeSelection, setControlPath, setLum, shiftCoverage, smoothCoverage, srgb8ToLab, srgbToLinear, tempTintToXy, temperatureToKelvin, toneCurve, toneLuts, toneRange, unprojectCanvasPoint, updateLayerMaskProps, uvToXy, vibranceLinear, vibrancePixel, wbMatrix, whiteBalanceFromSample, whiteBalanceMatrix, xyToTempTint, xyToUv };