@pixerate/editor 0.24.0 → 0.25.0

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

@@ -1,5 +1,5 @@
 import { b as LoadReport, J as JsonObject, f as MigrationStep } from '../migrate-iTlm3a8h.cjs';
-import { A as AgentToolProvider } from '../registry-DnzpgY27.cjs';
+import { A as AgentToolProvider, a as AgentTool } from '../registry-DnzpgY27.cjs';
 import '../schema-DYDGdYL9.cjs';
 
 /**
@@ -50,6 +50,94 @@ declare function blendPixel(mode: BlendMode, backdrop: readonly number[], source
  */
 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;
@@ -209,6 +297,27 @@ interface AdjustmentLayerBase {
     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 = {
@@ -306,6 +415,13 @@ 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 {
     /**
@@ -318,6 +434,8 @@ interface SerializedImageEditorState {
     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';
@@ -356,7 +474,9 @@ interface ImageEditorAIHooks {
  * ({@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.
@@ -540,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.
@@ -581,6 +710,13 @@ 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.
@@ -623,10 +759,355 @@ 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. */
@@ -636,6 +1117,22 @@ interface AdjustmentLayerUpdate<K extends AdjustmentKind = AdjustmentKind> {
     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> {
@@ -674,6 +1171,9 @@ declare class ImageEditorController {
     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.
@@ -735,6 +1235,79 @@ declare class ImageEditorController {
     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.
@@ -762,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,
@@ -785,135 +1360,13 @@ 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;
-}
-/**
- * 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;
-
 /** The `version` that `ImageEditorController.toJSON()` writes. */
 declare const IMAGE_EDITOR_STATE_VERSION = 1;
 /**
@@ -934,7 +1387,8 @@ interface ImageEditorDocumentLoad {
  * - 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`)
+ * - 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`.
  *
@@ -976,6 +1430,7 @@ declare function createAdjustmentLayer<K extends AdjustmentKind>(kind: K, option
     enabled?: boolean;
     opacity?: number;
     blend?: BlendMode;
+    mask?: AdjustmentLayerMask;
 }): AdjustmentLayerOf<K>;
 /**
  * A clean, deep-copied layer from stored or hand-written data: missing fields get neutral
@@ -1076,8 +1531,12 @@ declare function evaluateAdjustmentLayers(color: readonly number[], layers: read
  * 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: ImageData, layers: readonly AdjustmentLayer[] | undefined): void;
+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;
 
@@ -1179,6 +1638,8 @@ interface ImageEditorToolProviderOptions {
  *   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;
 
@@ -1203,4 +1664,108 @@ declare function moveCurvePoint(points: readonly CurvePoint[], index: number, p:
 /** Removes point `index`; a curve keeps at least two points. */
 declare function removeCurvePoint(points: readonly CurvePoint[], index: number): CurvePoint[];
 
-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 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 ControlSection, type ControlSpec, type ControlTrack, type CreateAnnotationPayload, type CropBox, type CropHandle, type CurvePoint, type CurvesParams, D65, DEFAULT_ADJUSTMENTS, DEFAULT_DEPTH_MASK, DEFAULT_TRANSFORM, type DepthMaskOptions, type ExportOptions, 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 LevelsChannel, type LevelsParams, type LineAnnotation, MAX_KELVIN, MIN_KELVIN, MIRED_PER_TEMPERATURE_UNIT, type Matrix3, type PenAnnotation, type PhotoFilterParams, type PixelOp, type PosterizeParams, type RectAnnotation, type RemoveBackgroundHook, type RemoveBackgroundOptions, type RenderOptions, type Rgb$1 as Rgb, type Rgba, type SerializedImageEditorState, TINT_SCALE, TONE_LUT_SIZE, type TextAnnotation, type ThresholdParams, type UnitLevels, VIBRANCE_GREY, type VibranceParams, type ViewportMetrics, activeAdjustmentLayers, adjustmentKindLabel, adjustmentLayersKey, applyAdjustmentLayers, applyAdjustments, applyDepthMask, applyImageProjectionToContext, applyLegacyAdjustments, applyMatrix3, applyProcess2Adjustments, blackWhiteGray, blendChannel, blendImageData, blendLum, blendPixel, blendRgb, boxToCurvePoint, bradfordAdaptation, buildToneLut, calculateCropDrag, canvasCompositeOperation, canvasToImagePoint, clampControlValue, clampCropToImage, colorBalanceChannel, compileAdjustmentLayer, computeHistogram, controlPosition, controlTrackBackground, createAdjustmentLayer, createImageEditorToolProvider, curveLut, curveLutFromLevels, curvePointToBox, curveSvgPath, defaultAdjustmentParams, evaluateAdjustmentLayers, findAdjustmentControl, findLayerControl, formatControlValue, getAnnotationBounds, getControlPath, getCropCursor, getRotatedSize, getViewportMetrics, getViewportProjection, globalImageCache, hexToRgb, histogramPath, hitTestAnnotation, hitTestCrop, hitTestCurvePoint, hslToRgb, hueRangeTables, hueRangeWeight, hueSaturation, identityCurve, identityLevels, imageEditorStateMigrations, imageToCanvasPoint, insertCurvePoint, invertMatrix3, isAdjustmentKind, isBlendMode, isQuarterTurnSwapped, isSeparableBlendMode, kelvinToTemperature, levelsValue, linearSrgbToXy, linearToSrgb, loadImageEditorDocument, mapCropHandle, migrateSerializedImageEditorState, moveCurvePoint, mulMatrix3, neutralHueRange, normalizeAdjustmentLayer, normalizeAdjustmentLayers, normalizeAngle, normalizeBlendMode, normalizeProcessVersion, normalizeStoredAdjustments, photoFilterMatrix, posterizeValue, projectImagePoint, projectImageRect, rangeLightness, readAdjustmentControls, removeAlpha, removeCurvePoint, rgbToGray, rgbToHsl, sampleLut, sampleToneLut, setControlPath, setLum, srgbToLinear, tempTintToXy, temperatureToKelvin, toneCurve, toneLuts, unprojectCanvasPoint, uvToXy, vibranceLinear, vibrancePixel, wbMatrix, whiteBalanceFromSample, whiteBalanceMatrix, xyToTempTint, xyToUv };
+/**
+ * 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 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 { 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 };