@pixerate/editor 0.88.0 → 0.89.0

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

@@ -1,56 +1,14 @@
+import { P as PixelSurface, T as TiledSurface, B as BlendMode } from '../surface-fJhkmNQn.js';
+export { a as BLEND_MODES, b as BlendModeInfo, M as MaskSurface, R as RasterRect, c as Rgb, d as Rgba, S as SurfaceDraft, e as TILE, f as TILE_SHIFT, g as Tile, h as TileKey, i as blendChannel, j as blendImageData, k as blendLum, l as blendPixel, m as blendRgb, n as canvasCompositeOperation, o as collectTiles, p as contentBounds, q as emptySurface, r as fillRect, s as finishTile, t as isBlendMode, u as isSeparableBlendMode, v as normalizeBlendMode, w as packRgba, x as readPixel, y as readRegion, z as setLum, A as solidSurface, C as surfaceBytes, D as surfaceFromPixels, E as surfacesEqual, F as tileCoord, G as tileKey, H as tileRect, I as tilesInRect, J as translateSurface, K as uniformTile, L as writeRegion } from '../surface-fJhkmNQn.js';
+import { RasterLayerBase, RasterMask as RasterMask$1, RasterPixelLayer, GroupBlendMode, LayerLocation as LayerLocation$1, LayerLocks, RasterSources, RasterCompositor, CompositorOptions } from '../raster/index.js';
+export { CompositeCallOptions, CompositeStats, DIRECT_GAUSSIAN_MAX_SIGMA, DecodedPng, ZlibError, adler32, base64ToBytes, blendTile, bytesToBase64, changedTiles, decodePng, deflate, deflateRaw, encodePng, findLayer, flattenLayers, gaussianBlur, inflate, inflateRaw, insertLayer, isLayerLocked, isPng, mapLayer, parseDataUrl, pngDataUrl } from '../raster/index.js';
+import { BrushSettings, StrokeCoverage, StrokeApply, StrokePoint } from '../paint/index.js';
+export { CoverageMap, DEFAULT_BRUSH, Dab, DabWalker, MAX_BRUSH_SIZE, applyStrokeToTile, coverageTileCoord, dabCoverage, dabRect, normalizeBrush, rasterizeDab, smoothPoints, tipFalloff, tipReach, tipShape, walkDabs } from '../paint/index.js';
 import { b as LoadReport, J as JsonObject, f as MigrationStep } from '../migrate-iTlm3a8h.js';
 import { a as AgentToolProvider, A as AgentTool } from '../registry-D-4fit9C.js';
 import { b as CaptureSurface } from '../capture-wwNGaW05.js';
 import '../schema-Di0CS6Pe.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
@@ -139,551 +97,340 @@ 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;
-}
-interface ImagePoint {
-    x: number;
-    y: number;
-}
-interface CropBox {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-type AspectRatio = number | null;
-interface ImageTransform {
-    rotate: number;
-    flipH: boolean;
-    flipV: boolean;
+/**
+ * The image editor's layer stack: pixel, adjustment, group and annotation layers in one ordered
+ * tree (bottom to top), all in document space (natural pixels of the document).
+ *
+ * Layer objects are immutable. Every change builds new objects along the path from the root to
+ * the changed layer and shares everything else, so undo history, the compositor's caches and
+ * serialization can compare layers by identity.
+ */
+
+/** Blend modes of a layer; groups also accept `pass-through`. */
+type LayerBlendMode = GroupBlendMode;
+
+/**
+ * A layer mask (see the raster module's `RasterMask`) whose parametric `source` is a depth map:
+ * a depth mask is generated from it instead of painted, and its surface is unused.
+ */
+type RasterMask = RasterMask$1<DepthMaskOptions>;
+interface LayerBase extends RasterLayerBase {
+    mask?: RasterMask;
 }
-interface ImageAdjustments {
+/** The base sliders of the old document-level adjustments, as a filter on one layer. */
+interface DevelopSettings {
     brightness: number;
     contrast: number;
     saturation: number;
     exposure: number;
     temperature: number;
-    /**
-     * -100 (green) to 100 (magenta), 0 is default. White-balance tint correction in Duv × 3000
-     * (process 2 only; the legacy process ignores it).
-     */
     tint?: number;
-    blur: number;
-    opacity: number;
-    /**
-     * Rendering process the values are interpreted by. `2` (the latest; new edits and Reset get
-     * it): linear-light exposure, Bradford white balance, LUT tone curve without intermediate
-     * clipping. `1` or missing: the legacy 8-bit rendering, so edits saved before process
-     * versions existed look exactly as they did. See `normalizeProcessVersion`.
-     */
+    /** Rendering process (see `ImageAdjustments.process`). */
     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 {
+type DevelopFilter = {
     id: string;
-    /** Optional display name. */
-    name?: string;
+    kind: 'develop';
     enabled: boolean;
-    /** 0..1 */
-    opacity: number;
-    /** How the adjusted colour is blended over the layers below. */
-    blend: BlendMode;
+} & DevelopSettings;
+/** Box blur of `radius` pixels (the old `adjustments.blur`), clamped at the canvas edges. */
+interface BlurFilter {
+    id: string;
+    kind: 'blur';
+    enabled: boolean;
+    radius: number;
+}
+type LayerFilter = DevelopFilter | BlurFilter;
+type LayerFilterKind = LayerFilter['kind'];
+interface PixelLayer extends LayerBase, Omit<RasterPixelLayer, keyof RasterLayerBase> {
+    /** Live filters, applied bottom (first) to top before the mask and blend. */
+    filters?: LayerFilter[];
     /**
-     * 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).
+     * `'document'`: the pixels are the document's source image, unmodified (the Background of an
+     * opened image). Such a layer's `surface` is a placeholder; read its pixels through the
+     * controller. Painting it drops the flag.
      */
-    mask?: AdjustmentLayerMask;
+    source?: 'document';
 }
+type AdjustmentLayerNode<K extends AdjustmentKind = AdjustmentKind> = {
+    [P in K]: LayerBase & {
+        type: 'adjustment';
+        kind: P;
+        params: AdjustmentParamsMap[P];
+    };
+}[K];
+interface GroupLayer extends Omit<LayerBase, 'blend'> {
+    type: 'group';
+    blend: LayerBlendMode;
+    /** Bottom to top. */
+    children: ImageLayer[];
+    /** UI only. */
+    collapsed?: boolean;
+}
+/** One annotation (pen, shape, arrow, text, image) as a layer, drawn by the annotation renderer. */
+interface AnnotationLayer extends LayerBase {
+    type: 'annotation';
+    annotation: Annotation;
+}
+type ImageLayer = PixelLayer | AdjustmentLayerNode | GroupLayer | AnnotationLayer;
+type ImageLayerType = ImageLayer['type'];
+/** Which part of the active layer painting targets. */
+type LayerTarget = 'pixels' | 'mask';
+/** A fresh id with `prefix` (`layer`, `flt`, …). */
+declare function newLayerId(prefix?: string): string;
+type LayerLocation = LayerLocation$1<ImageLayer>;
+
+/** The top-level and nested pixel layers. */
+declare function pixelLayers(layers: readonly ImageLayer[]): PixelLayer[];
+/** The develop filter of a pixel layer, if any. */
+declare function developFilter(layer: PixelLayer): DevelopFilter | undefined;
+declare function blurFilter(layer: PixelLayer): BlurFilter | undefined;
+/** True for filters that change pixels (enabled, non-neutral). */
+declare function isActiveFilter(f: LayerFilter): boolean;
+/** True when a filter needs neighbouring pixels (it can't run tile by tile). */
+declare function isSpatialFilter(f: LayerFilter): boolean;
+/** Document-space bounds of a pixel layer's stored tiles, or `null`. */
+declare function pixelLayerBounds(layer: PixelLayer, surface?: PixelSurface): CropBox | null;
+/** Human label of a layer kind. */
+declare function layerTypeLabel(type: ImageLayerType): string;
+
 /**
- * A layer mask: 8-bit coverage of the source image, run-length encoded (see
- * `encodeSelectionRle`), plus non-destructive density and feather.
+ * Schema version 3 of the image editor document: the layer tree, with pixel layers and painted
+ * masks stored as PNG assets (cropped to their content and placed by position), plus the
+ * document-level crop, transform, output opacity, migrated blur and selection.
+ *
+ * Encoding is synchronous and exact (see `png.ts`). Each surface's encoding is memoised, so
+ * saving an unchanged layer again costs nothing.
  */
-interface AdjustmentLayerMask {
-    width: number;
-    height: number;
-    /** `r1:` run-length encoding of the mask bytes. */
-    rle: string;
-    /** 0..1 (missing = 1). */
+
+declare const LAYERED_SCHEMA_VERSION: 3;
+/** A stored raster mask. Pixels: `asset` (grey PNG) placed at `x`, `y`; elsewhere `defaultValue`. */
+interface SerializedRasterMask {
+    defaultValue: 0 | 255;
+    asset?: string;
+    x?: number;
+    y?: number;
     density?: number;
-    /** Gaussian σ in pixels (missing = 0). */
     feather?: number;
-    /** `false` keeps the mask but ignores it. */
     enabled?: boolean;
+    source?: DepthMaskOptions;
 }
-/** A non-destructive adjustment layer (Photoshop's Layer › New Adjustment Layer). */
-type AdjustmentLayer = {
-    [K in AdjustmentKind]: AdjustmentLayerBase & {
-        kind: K;
-        params: AdjustmentParamsMap[K];
+interface SerializedLayerBase {
+    id: string;
+    name: string;
+    visible: boolean;
+    opacity: number;
+    blend: string;
+    clipped?: boolean;
+    mask?: SerializedRasterMask;
+    locks?: LayerLocks;
+}
+interface SerializedPixelLayer extends SerializedLayerBase {
+    type: 'pixel';
+    /** Asset id of the pixels (RGBA PNG) placed at `x`, `y` in layer space; missing when empty. */
+    asset?: string;
+    x?: number;
+    y?: number;
+    offset: {
+        x: number;
+        y: number;
     };
-}[AdjustmentKind];
-type AdjustmentLayerOf<K extends AdjustmentKind> = Extract<AdjustmentLayer, {
-    kind: K;
-}>;
-interface DepthMaskOptions {
-    enabled: boolean;
-    maskSource: string | null;
-    mode: 'threshold' | 'brightness';
-    depthRange: [number, number];
-    softness: number;
-    invert: boolean;
+    fillOpacity?: number;
+    filters?: LayerFilter[];
+    /** `'document'`: the pixels are the document's source image (no asset is stored). */
+    source?: 'document';
+}
+interface SerializedAdjustmentLayer extends SerializedLayerBase {
+    type: 'adjustment';
+    kind: string;
+    params: unknown;
+}
+interface SerializedGroupLayer extends SerializedLayerBase {
+    type: 'group';
+    children: SerializedLayer[];
+    collapsed?: boolean;
+}
+interface SerializedAnnotationLayer extends SerializedLayerBase {
+    type: 'annotation';
+    annotation: Annotation;
+}
+type SerializedLayer = SerializedPixelLayer | SerializedAdjustmentLayer | SerializedGroupLayer | SerializedAnnotationLayer;
+/** A version 3 document (layers). */
+interface SerializedLayeredImageEditorState {
+    version: 3;
+    /** Canvas size in pixels. */
+    width: number;
+    height: number;
+    /** Bottom to top. */
+    layers: SerializedLayer[];
+    /** Asset id → PNG data URL (or an external reference, see `ImageEditorAssetStore`). */
+    assets: Record<string, string>;
+    activeLayerId: string | null;
+    crop: CropBox | null;
+    transform: ImageTransform;
+    /** Export alpha, 0..1. */
+    opacity: number;
+    /** Blur migrated from a v1 / v2 document with adjustment layers (runs after the layers). */
+    legacyOutputBlur?: number;
+    selection?: SerializedSelection;
 }
-type AnnotationType = 'pen' | 'rect' | 'circle' | 'arrow' | 'line' | 'text' | 'image';
-interface BaseAnnotation {
-    id: string;
-    type: AnnotationType;
+interface EncodedSurface {
+    url: string;
     x: number;
     y: number;
-    rotation?: number;
-    opacity?: number;
-    /** Blend mode the annotation is drawn with (default `normal`). */
-    blend?: BlendMode;
 }
-interface PenAnnotation extends BaseAnnotation {
-    type: 'pen';
-    points: ImagePoint[];
-    strokeColor: string;
-    strokeWidth: number;
+/** The surface's content (non-default pixels) as a PNG data URL and its position, or `null`. */
+declare function encodeSurface(surface: TiledSurface): EncodedSurface | null;
+interface SerializeContext {
+    /** Adds an asset and returns its id. */
+    addAsset(url: string, hint: string): string;
+}
+declare function serializeLayer(layer: ImageLayer, ctx: SerializeContext): SerializedLayer;
+/** Serializes a layer tree with inline assets (asset ids are derived from layer ids). */
+declare function serializeLayers(layers: readonly ImageLayer[]): {
+    layers: SerializedLayer[];
+    assets: Record<string, string>;
+};
+interface DeserializeContext {
+    assets: Record<string, string>;
+    /** Decodes an asset (PNG data URL by default). Throw for an unusable asset. */
+    decodeAsset?(ref: string, channels: 1 | 4): {
+        width: number;
+        height: number;
+        data: ArrayLike<number>;
+    };
+    /** Problems found while reading (unknown kinds, broken assets); the rest still loads. */
+    problems: string[];
 }
-interface RectAnnotation extends BaseAnnotation {
-    type: 'rect';
+/** Decodes a PNG data URL into pixels of `channels` bytes each. */
+declare function decodePngDataUrl(url: string, channels: 1 | 4): {
     width: number;
     height: number;
-    strokeColor: string;
-    strokeWidth: number;
-    fillColor?: string;
-    cornerRadius?: number;
+    data: Uint8ClampedArray;
+};
+declare function deserializeLayer(raw: unknown, ctx: DeserializeContext): ImageLayer | null;
+/** Reads a stored layer tree (layers that cannot be read are dropped and reported). */
+declare function deserializeLayers(raw: unknown, ctx: DeserializeContext): ImageLayer[];
+
+/** 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 CircleAnnotation extends BaseAnnotation {
-    type: 'circle';
-    radiusX: number;
-    radiusY: number;
-    strokeColor: string;
-    strokeWidth: number;
-    fillColor?: string;
-}
-interface ArrowAnnotation extends BaseAnnotation {
-    type: 'arrow';
-    endX: number;
-    endY: number;
-    strokeColor: string;
-    strokeWidth: number;
-}
-interface LineAnnotation extends BaseAnnotation {
-    type: 'line';
-    endX: number;
-    endY: number;
-    strokeColor: string;
-    strokeWidth: number;
-}
-interface TextAnnotation extends BaseAnnotation {
-    type: 'text';
-    text: string;
-    fontSize: number;
-    fontFamily?: string;
-    color: string;
-    fontWeight?: string | number;
-}
-interface ImageAnnotation extends BaseAnnotation {
-    type: 'image';
-    src: string;
-    width: number;
-    height: number;
-}
-type Annotation = PenAnnotation | RectAnnotation | CircleAnnotation | ArrowAnnotation | LineAnnotation | TextAnnotation | ImageAnnotation;
-type CreateAnnotationPayload = Omit<PenAnnotation, 'id'> | Omit<RectAnnotation, 'id'> | Omit<CircleAnnotation, 'id'> | Omit<ArrowAnnotation, 'id'> | Omit<LineAnnotation, 'id'> | Omit<TextAnnotation, 'id'> | Omit<ImageAnnotation, 'id'>;
-type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'arrow' | 'line' | 'text' | 'watermark';
-interface ImageEditorState {
-    sourceUrl: string | null;
-    imageDimensions: ImageDimensions;
-    crop: CropBox | null;
-    transform: ImageTransform;
-    adjustments: ImageAdjustments;
-    depthMask: DepthMaskOptions;
-    annotations: Annotation[];
-    selectedAnnotationId: string | null;
-    activeTool: ImageEditorTool;
-    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 {
-    /**
-     * 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';
-    quality?: number;
+interface PixelSource {
+    data: ArrayLike<number>;
     width?: number;
     height?: number;
-    includeAnnotations?: boolean;
-}
-interface ImageEditorOptions {
-    image?: string | HTMLImageElement;
-    initialState?: Partial<SerializedImageEditorState>;
-    onStateChange?: (state: ImageEditorState) => void;
-    maxHistoryDepth?: number;
 }
-interface InpaintOptions {
-    prompt: string;
-    imageDataUrl: string;
-    maskDataUrl?: string;
-    cropBox?: CropBox | null;
-}
-interface RemoveBackgroundOptions {
-    imageDataUrl: string;
-}
-type InpaintHook = (options: InpaintOptions) => Promise<string | void> | string | void;
-type RemoveBackgroundHook = (options: RemoveBackgroundOptions) => Promise<string | void> | string | void;
-interface ImageEditorAIHooks {
-    onInpaint?: InpaintHook;
-    onRemoveBackground?: RemoveBackgroundHook;
-}
-
 /**
- * Applies color and tone adjustments (brightness, contrast, saturation, exposure, temperature, tint,
- * 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, 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.
- */
-declare function applyLegacyAdjustments(imageData: ImageData, adjustments: ImageAdjustments): void;
-/**
- * Process 2: decode sRGB to linear float once; apply exposure (gain) and white balance (a
- * Bradford matrix relative to as-shot) in linear light; a per-channel tone LUT for the
- * highlight shoulder, contrast and brightness; luminance-preserving saturation in linear light;
- * then encode back to sRGB through a LUT. Nothing is clamped between stages, only at the final
- * encode. Neutral settings are the identity.
- */
-declare function applyProcess2Adjustments(imageData: ImageData, adjustments: ImageAdjustments): void;
-/**
- * Blends a depth/alpha mask into the main image data based on Gleamforge depth masking.
- * Supports threshold range with softness gradation, brightness mode, and optional inversion.
+ * 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 applyDepthMask(mainImageData: ImageData, maskImageData: ImageData, options: DepthMaskOptions): void;
+declare function computeHistogram(imageData: PixelSource): ImageHistogram;
+type HistogramChannel = 'red' | 'green' | 'blue' | 'luminance';
 /**
- * Removes alpha channel by setting all alpha bytes to 255 (completely opaque).
- * From Gleamforge image-filters.ts.
+ * 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 removeAlpha(imageData: ImageData): void;
+declare function histogramPath(histogram: ImageHistogram, channel: HistogramChannel, width: number, height: number, options?: {
+    scale?: 'linear' | 'sqrt';
+    max?: number;
+}): string;
 
 /**
- * Colour science for the image editor's process 2 rendering: sRGB transfer functions,
- * correlated colour temperature / tint (Kim et al. Planckian locus, tint as Duv), Bradford
- * white-balance adaptation relative to "as shot", and the display-referred tone curve.
+ * The image editor's compositor: the raster engine (`@pixerate/editor/raster`) with the photo
+ * layer kinds plugged in. Adjustment layers filter what is below them (a run of adjacent ones is
+ * one float pass with one rounding at the end, exactly as `applyAdjustmentLayers` does, so a
+ * document migrated from adjustment layers renders identically); annotation layers are drawn by
+ * the host; pixel layers can carry develop and blur filters; masks can be depth masks.
  */
-/** A CIE 1931 chromaticity. */
-interface Chromaticity {
-    x: number;
-    y: number;
+
+/** What the compositor needs from its host besides the layers. */
+interface CompositorSources extends RasterSources {
+    /** The pixels of a pixel layer (resolves layers whose pixels are the document source). */
+    surfaceOf?(layer: PixelLayer): PixelSurface;
+    /**
+     * A parametric mask's depth map as RGBA at canvas size (the red channel is the depth), or
+     * `null` while it is unavailable (the mask then reveals everything).
+     */
+    depthMap?(source: DepthMaskOptions): {
+        width: number;
+        height: number;
+        data: ArrayLike<number>;
+    } | null;
+    /** Draws one annotation into RGBA for `rect` (canvas hosts only); `null` when unavailable. */
+    rasterizeAnnotation?(annotation: Annotation, rect: CropBox): Uint8ClampedArray | null;
+}
+/** The `AdjustmentLayer` shape `applyAdjustmentLayers` evaluates, for a node (memoised). */
+declare function adjustmentNodeAsLayer(node: AdjustmentLayerNode): AdjustmentLayer;
+/** Evaluates a depth mask (see `applyDepthMask`) into one coverage byte per depth sample. */
+declare function depthMaskAlpha(depth: number, options: DepthMaskOptions): number;
+/** The per-tile compositor for image editor layer stacks (see the raster module for the caches). */
+declare class LayerCompositor extends RasterCompositor<ImageLayer, CompositorSources> {
+    constructor(options?: CompositorOptions);
+}
+
+interface RenderOptions {
+    viewportWidth?: number;
+    viewportHeight?: number;
+    showCropOverlay?: boolean;
+    showSelectionOverlay?: boolean;
+    interactive?: boolean;
+    draftAnnotation?: Annotation | null;
+    draftCrop?: CropBox | null;
+    /** Viewport fit mode: 'contain' scales to full viewport bounds; 'margin' scales to 85% with 1.0 cap (default). */
+    fit?: ImageEditorFit;
+    /**
+     * 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;
+    /** Document rectangles that are the only change since the last render (strokes); recomposites only there. */
+    dirty?: CropBox[];
+    /** The layer being edited: tiles keep a checkpoint below it so strokes and drags on it start there. */
+    checkpointLayerId?: string | null;
+    /** The paint tools' cursor: a circle of `diameter` px at (`x`, `y`) in natural pixels. */
+    brushCursor?: {
+        x: number;
+        y: number;
+        diameter: number;
+    } | null;
 }
-/** A row-major 3×3 matrix (`[m00, m01, m02, m10, …, m22]`). */
-type Matrix3 = [number, number, number, number, number, number, number, number, number];
-/** The rendering of adjustments from before process versions existed. Frozen. */
-declare const LEGACY_PROCESS_VERSION: 1;
-/** The process new edits and Reset get. */
-declare const LATEST_PROCESS_VERSION: 2;
-type ImageProcessVersion = 1 | 2;
-/**
- * Reads a stored process number leniently: a missing or damaged value (not a whole number) is
- * the legacy process, so a saved edit from before process versions renders exactly as it did. A
- * whole number newer than this build knows renders with the latest process.
- */
-declare function normalizeProcessVersion(value: unknown): ImageProcessVersion;
-declare function srgbToLinear(v: number): number;
-declare function linearToSrgb(v: number): number;
-/** Rec.709 / sRGB luminance weights (linear light). */
-declare const LUMA_709: readonly [number, number, number];
-declare const IDENTITY_MATRIX3: Matrix3;
-declare function mulMatrix3(a: Matrix3, b: Matrix3): Matrix3;
-declare function applyMatrix3(m: Matrix3, v: readonly [number, number, number]): [number, number, number];
-declare function invertMatrix3(m: Matrix3): Matrix3 | null;
-declare const D65: Chromaticity;
-/** Bradford chromatic adaptation (XYZ → XYZ) from white `src` to white `dst`. */
-declare function bradfordAdaptation(src: Chromaticity, dst: Chromaticity): Matrix3;
-/**
- * Matrix (linear sRGB → linear sRGB) that white-balances a scene lit by `src` so that it
- * renders as if lit by D65.
- */
-declare function wbMatrix(src: Chromaticity): Matrix3;
-/** The chromaticity of a linear sRGB colour. */
-declare function linearSrgbToXy(rgb: readonly [number, number, number]): Chromaticity;
-/** Tint units per unit of Duv. */
-declare const TINT_SCALE = 3000;
-declare const MIN_KELVIN = 1667;
-declare const MAX_KELVIN = 25000;
-/** CIE 1931 xy → CIE 1960 uv. */
-declare function xyToUv(p: Chromaticity): [number, number];
-/** CIE 1960 uv → CIE 1931 xy. */
-declare function uvToXy(u: number, v: number): Chromaticity;
-/**
- * Source illuminant chromaticity for temperature `kelvin` and correction `tint`.
- * Positive tint means a green source white, whose correction adds magenta to the image.
- */
-declare function tempTintToXy(kelvin: number, tint: number): Chromaticity;
-/** Inverse of {@link tempTintToXy}: nearest locus temperature (searched in mired space) and tint. */
-declare function xyToTempTint(p: Chromaticity): {
-    kelvin: number;
-    tint: number;
-};
-/** Rendered images carry no as-shot white: "as shot" is 6500 K / tint 0 and maps to the identity. */
-declare const AS_SHOT_KELVIN = 6500;
-/** Mireds per unit of the `temperature` slider (−100…100). */
-declare const MIRED_PER_TEMPERATURE_UNIT = 1;
-/**
- * Maps the `temperature` slider (−100 cool … +100 warm) to the Kelvin white-balance setting:
- * one mired per unit around 6500 K, so 0 → 6500 K, +100 → ~18 570 K (a strong warming
- * correction), −100 → ~3 940 K (a strong cooling correction). Mireds are perceptually even,
- * so equal slider steps look like equal changes.
- */
-declare function temperatureToKelvin(temperature: number): number;
-/** Inverse of {@link temperatureToKelvin}. */
-declare function kelvinToTemperature(kelvin: number): number;
 /**
- * White-balance matrix (linear sRGB) for the `temperature` / `tint` sliders, relative to
- * "as shot": the identity at 0 / 0. Normalised so neutral luminance is preserved (white
- * balance doesn't change exposure).
+ * Image Cache to avoid refetching HTMLImageElement objects repeatedly during re-renders.
  */
-declare function whiteBalanceMatrix(temperature: number, tint?: number): Matrix3;
+declare class ImageCache {
+    private cache;
+    get(src: string): Promise<HTMLImageElement>;
+    set(src: string, img: HTMLImageElement): void;
+    /** The loaded image for `src`, or `undefined` while it is not loaded yet. */
+    peek(src: string): HTMLImageElement | undefined;
+    clear(): void;
+}
+declare const globalImageCache: ImageCache;
 /**
- * Neutral-point eyedropper: the `temperature` / `tint` that render the sampled sRGB colour
- * (0–255 per channel, as it appears in the unadjusted image) neutral. Results are clamped to
- * the slider range −100…100.
- */
-declare function whiteBalanceFromSample(rgb: readonly [number, number, number] | {
-    r: number;
-    g: number;
-    b: number;
-}): {
-    temperature: number;
-    tint: number;
-};
-/** Number of intervals in a tone LUT (the table has `TONE_LUT_SIZE + 1` entries). */
-declare const TONE_LUT_SIZE = 4096;
-/**
- * The process 2 tone curve for one linear input value in `[0, headroom]`:
- *
- * 1. A highlight shoulder (extended Reinhard with white point `headroom`) above a knee of 0.6
- *    rolls values above 1 (after exposure / white balance) back into range instead of clipping.
- *    With no headroom (`headroom = 1`) it is exactly the identity.
- * 2. In a gamma-2.2 perceptual domain, contrast is an S-curve anchored at 0, middle grey and 1
- *    (as `ToneMap::display`), and brightness a midtone lift anchored at 0 and 1.
- *
- * `contrast` and `brightness` are −100…100; both 0 with `headroom = 1` is the identity.
- */
-declare function toneCurve(y: number, contrast: number, brightness: number, headroom?: number): number;
-/** Tabulates {@link toneCurve} over `[0, headroom]` in {@link TONE_LUT_SIZE} steps. */
-declare function buildToneLut(contrast: number, brightness: number, headroom?: number): Float32Array;
-/** 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;
-    showCropOverlay?: boolean;
-    showSelectionOverlay?: boolean;
-    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.
- */
-declare class ImageCache {
-    private cache;
-    get(src: string): Promise<HTMLImageElement>;
-    set(src: string, img: HTMLImageElement): void;
-    clear(): void;
-}
-declare const globalImageCache: ImageCache;
-/**
- * Renders an image with all its transformations, filters, depth masks, and annotations
- * to a target HTMLCanvasElement.
+ * Renders an image with all its transformations, filters, depth masks, and annotations
+ * to a target HTMLCanvasElement.
  */
 declare class ImageEditorRenderer {
     imageCache: ImageCache;
@@ -698,6 +445,28 @@ declare class ImageEditorRenderer {
     onPreviewHistogram?: (histogram: ImageHistogram | null) => void;
     private sourceIds;
     private nextSourceId;
+    /**
+     * The viewport's compositor. It only ever composites the viewport's stack, so its tile cache can
+     * trust dirty rectangles; exports use `exportCompositor`.
+     */
+    compositor: LayerCompositor;
+    private exportCompositor;
+    /** How the host resolves layer pixels (set by the controller). */
+    layerSources?: LayerSourcesHost;
+    /**
+     * Debug / test switch: `'legacy'` forces the old base path for documents that still have the
+     * v1 / v2 shape, `'layers'` forces the compositor. Default: chosen per document.
+     */
+    baseRoute: 'auto' | 'legacy' | 'layers';
+    /** Which path the last base render took. */
+    lastBaseRoute: 'legacy' | 'layers' | null;
+    private comp;
+    private depthMaps;
+    private assetVersion;
+    private scratch;
+    private cachedPostCanvas;
+    private cachedPostKey;
+    private cachedPostHistogram;
     /**
      * Helper to create a canvas element safely in browser/JSDOM.
      */
@@ -711,6 +480,32 @@ declare class ImageEditorRenderer {
      * and the depth mask (which receives the identical transform so it stays aligned).
      */
     private renderBaseImage;
+    /** Which base path renders `state` (see `needsLegacyBase`). */
+    private chooseRoute;
+    /** Compositor sources for a `width × height` canvas: layer pixels, depth maps and annotation rasterizing. */
+    compositorSources(width: number, height: number): CompositorSources;
+    /** Loads what the compositor reads synchronously: depth maps (at canvas size) and annotation images. */
+    /** Loads depth maps and annotation images the compositor reads synchronously. */
+    prepareLayerAssets(layers: readonly ImageLayer[], width: number, height: number): Promise<void>;
+    /** Whether annotation layers can be rasterized here (a 2D canvas with pixel access). */
+    canRasterize(): boolean;
+    /** One annotation drawn into a tile-sized RGBA buffer at `rect` (document space), or `null` without a canvas. */
+    private rasterizeAnnotation;
+    private putTile;
+    /**
+     * Brings the viewport's composite canvas (document space, covering `region`) up to date,
+     * uploading only the tiles that changed since the last render.
+     */
+    private updateComposite;
+    /**
+     * The base canvas of a layered document: the composite drawn through the base projection (crop,
+     * rotation, flips at scale 1), then output opacity and the migrated blur, which run in the output
+     * frame. Cached until the composite or those settings change.
+     */
+    private layeredBase;
+    /** Output opacity then the migrated blur, in place on a base canvas; returns its histogram. */
+    private applyPost;
+    private publishHistogram;
     private quickMaskCache;
     private outlineCache;
     /** Rubylith over the unselected area, drawn in natural image space. */
@@ -731,6 +526,8 @@ declare class ImageEditorRenderer {
      */
     private drawAnnotationBlended;
     private drawAnnotationContent;
+    /** Draws an annotation synchronously; an image annotation draws `img` (skipped when `null`). */
+    drawAnnotationShape(ctx: CanvasRenderingContext2D, ann: Annotation, img: CanvasImageSource | null): void;
     /**
      * Draws selection box around active annotation.
      */
@@ -764,6 +561,12 @@ declare class ImageEditorRenderer {
     }): Promise<HTMLCanvasElement>;
     private drawAnnotationMask;
 }
+/** What the renderer asks its host (the controller) about layer pixels. */
+interface LayerSourcesHost {
+    surfaceOf(layer: PixelLayer): PixelSurface;
+    sourceIsOpaque(): boolean;
+    version(): string;
+}
 
 interface ShapeSelectionOptions {
     /** Partial coverage along the edge (default true). */
@@ -866,16 +669,6 @@ declare function borderCoverage(m: ArrayLike<number>, w: number, h: number, r: n
  * 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. */
@@ -1109,8 +902,90 @@ declare function projectMaskCoverage(coverage: Float32Array, maskWidth: number,
  */
 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;
+/** A refused layer operation; the message says why and how to fix it. */
+declare class LayerOperationError extends Error {
+    constructor(message: string);
+}
+/** Where a layer goes: above or below a layer (in its group), or at a position in a group. */
+interface LayerPlacement {
+    /** Directly above this layer, in the same group. */
+    aboveId?: string;
+    /** Directly below this layer, in the same group. */
+    belowId?: string;
+    /** Inside this group (at `index`, default the top). */
+    parentId?: string;
+    /** Index in the parent's children (or the top level), 0 = bottom. */
+    index?: number;
+}
+/** The layer with `id`, or a `LayerOperationError` listing the ids that exist. */
+declare function requireLayer(layers: readonly ImageLayer[], id: string): LayerLocation$1<ImageLayer>;
+/** Refuses when the layer is locked for `what` (and always for `all`). */
+declare function requireUnlocked(layer: ImageLayer, what: keyof LayerLocks, action: string): void;
+/** Inserts `layer` at `placement` (default: the top level at `defaultIndex`, or the top). */
+declare function placeLayer(layers: readonly ImageLayer[], layer: ImageLayer, placement?: LayerPlacement, defaultIndex?: number): ImageLayer[];
+/** Removes a layer (refused when it is locked). */
+declare function removeLayer(layers: readonly ImageLayer[], id: string): ImageLayer[];
+/** Moves a layer to `placement`. A group cannot go inside itself. Returns the new stack. */
+declare function moveLayer(layers: readonly ImageLayer[], id: string, placement: LayerPlacement): ImageLayer[];
+/** Every id in a subtree gets a fresh one (for duplicates). */
+declare function withNewIds<T extends ImageLayer>(layer: T): T;
+/** Duplicates a layer (and its children) directly above it. Returns the stack and the copy's id. */
+declare function duplicateLayer(layers: readonly ImageLayer[], id: string, name?: string): {
+    layers: ImageLayer[];
+    id: string;
+};
+/** Properties `setLayerProperties` changes. */
+interface LayerProperties {
+    name?: string;
+    visible?: boolean;
+    /** 0..1 */
+    opacity?: number;
+    /** 0..1, pixel layers only. */
+    fillOpacity?: number;
+    blend?: LayerBlendMode;
+    clipped?: boolean;
+    locks?: LayerLocks;
+    /** Groups only (UI state). */
+    collapsed?: boolean;
+}
+/** Validates and applies property changes to one layer. */
+declare function setLayerProperties(layers: readonly ImageLayer[], id: string, props: LayerProperties): ImageLayer[];
+/**
+ * Puts layers (siblings in one group or the top level) into a new group at the position of the
+ * topmost one, keeping their order. Returns the stack and the group id.
+ */
+declare function groupLayers(layers: readonly ImageLayer[], ids: string[], name?: string): {
+    layers: ImageLayer[];
+    id: string;
+};
+/** Replaces a group by its children (the group's own opacity, blend and mask are dropped). */
+declare function ungroupLayer(layers: readonly ImageLayer[], id: string): {
+    layers: ImageLayer[];
+    ids: string[];
+};
+/** Sets a pixel layer's offset (refused when its position is locked). */
+declare function offsetLayer(layers: readonly ImageLayer[], id: string, offset: {
+    x: number;
+    y: number;
+}): ImageLayer[];
+/** Sets or removes (`null`) a layer's mask. */
+declare function setLayerMask(layers: readonly ImageLayer[], id: string, mask: RasterMask | null): ImageLayer[];
+/** A clean filter from loose input (for tools and the UI). */
+declare function normalizeFilter(raw: Partial<LayerFilter> & {
+    kind: LayerFilter['kind'];
+}, id?: string): LayerFilter;
+/** Adds a filter on top of a pixel layer's filters. A layer has at most one filter of each kind. */
+declare function addLayerFilter(layers: readonly ImageLayer[], id: string, filter: LayerFilter): ImageLayer[];
+/** Changes one filter of a pixel layer (`changes` merged and validated). */
+declare function updateLayerFilter(layers: readonly ImageLayer[], id: string, filterId: string, changes: Record<string, unknown>): ImageLayer[];
+declare function removeLayerFilter(layers: readonly ImageLayer[], id: string, filterId: string): ImageLayer[];
+/** A blend mode check for tools. */
+declare function parseBlend(value: unknown, allowPassThrough?: boolean): BlendMode | 'pass-through' | undefined;
+/** The union of two rectangles (either may be null). */
+declare function unionRect(a: CropBox | null, b: CropBox | null): CropBox | null;
+
+/** Latest serialized schema version (`3`: layers). Documents with the old shape still write 1 or 2. */
+declare const IMAGE_EDITOR_SCHEMA_VERSION: 3;
 /** Changes to an adjustment layer; `params` is merged into the current parameters. */
 interface AdjustmentLayerUpdate<K extends AdjustmentKind = AdjustmentKind> {
     params?: Partial<AdjustmentParamsMap[K]>;
@@ -1135,10 +1010,113 @@ interface SampleOptions {
     /** Pixels to use instead of reading the source image (natural size, RGBA). */
     pixels?: PixelBuffer;
 }
-/** A new adjustment layer: its kind plus optional initial values. */
+/** A new adjustment layer: its kind plus optional initial values and position. */
 interface AdjustmentLayerInit<K extends AdjustmentKind = AdjustmentKind> extends AdjustmentLayerUpdate<K> {
     kind: K;
     id?: string;
+    /** Put the new layer directly above this layer (in its group). */
+    aboveId?: string;
+    /** Put the new layer at the top of this group. */
+    parentId?: string;
+}
+/** A new pixel layer: empty, a solid colour over the canvas, or given pixels, plus its properties and position. */
+interface PixelLayerInit extends LayerPlacement {
+    id?: string;
+    name?: string;
+    /** Fill the canvas with this colour (`#rgb`, `#rrggbb`, `#rrggbbaa` or `[r, g, b, a?]` 0..255). */
+    color?: string | number[];
+    /** RGBA pixels placed at `x`, `y` (document pixels). */
+    pixels?: PixelBuffer;
+    x?: number;
+    y?: number;
+    visible?: boolean;
+    /** 0..1 (default 1). */
+    opacity?: number;
+    fillOpacity?: number;
+    blend?: BlendMode;
+}
+/** The paint tools' options (view state). */
+interface PaintOptions {
+    brush: BrushSettings;
+    /** `#rrggbb`: what the brush and Fill paint. */
+    foreground: string;
+    /** `#rrggbb`: what the eraser paints on transparency-locked layers and masks. */
+    background: string;
+}
+/** A stroke: tool, target (default the active layer and target) and brush / colour overrides. */
+interface StrokeInit {
+    tool?: 'brush' | 'eraser';
+    layerId?: string;
+    channel?: LayerTarget;
+    /** Overrides of the paint options' brush. */
+    brush?: Partial<BrushSettings>;
+    /** Paint colour (default the foreground). Masks take its grey value. */
+    color?: string | number[];
+    /** Eraser colour on locked transparency / masks (default the background). */
+    background?: string | number[];
+    /** Kept with the stroke for replays (v1 brushes have no jitter). */
+    seed?: number;
+}
+interface FillOptions {
+    layerId?: string;
+    channel?: LayerTarget;
+    /** Default the foreground colour. */
+    color?: string | number[];
+    /** 0..1 (default 1). */
+    opacity?: number;
+    blend?: BlendMode;
+    /** Limit to the selection when there is one (default true). */
+    useSelection?: boolean;
+}
+/** What a stroke, fill or clear changed. */
+interface PaintStrokeResult {
+    layerId: string;
+    channel: LayerTarget;
+    /** Document rectangle that changed (null when nothing did). */
+    bounds: CropBox | null;
+    dabs: number;
+}
+/** An opaque pre-stroke history snapshot. */
+type HistoryEntryHandle = {
+    readonly __historyEntry: unique symbol;
+};
+/**
+ * A stroke in progress (see `beginStroke`): `push` input points as they arrive, then `end` (one
+ * undo step) or `cancel`.
+ */
+declare class PaintStrokeSession {
+    private readonly controller;
+    readonly target: {
+        id: string;
+        channel: LayerTarget;
+        surface: TiledSurface;
+    };
+    private readonly stroke;
+    private readonly apply;
+    private readonly before;
+    private readonly base;
+    private readonly live;
+    private readonly touched;
+    private last;
+    private closed;
+    constructor(controller: ImageEditorController, target: {
+        id: string;
+        channel: LayerTarget;
+        surface: TiledSurface;
+    }, stroke: StrokeCoverage, apply: StrokeApply);
+    get layerId(): string;
+    /** Adds input points (document pixels); the stack shows the stroke so far. */
+    push(points: readonly StrokePoint[]): void;
+    private update;
+    /** Finishes the stroke (one undo step) and returns what changed. */
+    end(): PaintStrokeResult;
+    /** Abandons the stroke and restores the layer. */
+    cancel(): void;
+}
+/** Where a new annotation goes. */
+interface AnnotationPlacement {
+    /** Put the annotation layer directly above this layer (default: the top of the stack). */
+    aboveId?: string;
 }
 declare const DEFAULT_ADJUSTMENTS: ImageAdjustments;
 /**
@@ -1147,13 +1125,24 @@ declare const DEFAULT_ADJUSTMENTS: ImageAdjustments;
  */
 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.
+ * Brings a stored editor state of any schema version to a clean state of the same family:
+ * version 1 (and a missing version) has no adjustment layers, version 2 has them, and both stay
+ * in the document-level schema so old states load and render exactly as before. Version 3
+ * (layers) is returned with its document fields cleaned. To lift a v1 / v2 state into layers,
+ * use {@link migrateToLayeredState}.
  */
 declare function migrateSerializedImageEditorState(data: Partial<SerializedImageEditorState> & {
     version?: number;
 }): SerializedImageEditorState;
+/**
+ * Lifts a stored state of any version into the layered schema (v3) for a canvas of
+ * `width × height`: the source becomes the Background layer with the base sliders as its
+ * `develop` filter and the depth mask as its parametric mask, adjustment layers go above it and
+ * annotations on top (see `layersFromLegacy`).
+ */
+declare function migrateToLayeredState(data: Partial<SerializedImageEditorState> & {
+    version?: number;
+}, size: ImageDimensions): SerializedLayeredImageEditorState;
 declare const DEFAULT_TRANSFORM: ImageTransform;
 declare const DEFAULT_DEPTH_MASK: DepthMaskOptions;
 /**
@@ -1170,11 +1159,17 @@ declare class ImageEditorController {
     private undoStack;
     private redoStack;
     private maxHistoryDepth;
+    private maxHistoryBytes;
     private isApplyingHistory;
     private initialSnapshot;
     /** Pixels the selection tools sample (host-provided or read back from the source). */
     private samplePixels;
     private samplePixelsOverride;
+    /** Decoded source pixels (the Background's surface), by the buffer or element they came from. */
+    private sourceSurfaces;
+    private viewKey;
+    /** For `compositePixels` and mask evaluation (the renderer keeps its own for the viewport). */
+    private compositor;
     constructor(options?: ImageEditorOptions);
     /**
      * Loads a new source image and makes it the baseline that `reset()` returns to.
@@ -1186,10 +1181,24 @@ declare class ImageEditorController {
     getImageElement(): CanvasImageSource | null;
     getState(): ImageEditorState;
     subscribe(listener: (state: ImageEditorState) => void): () => void;
+    /**
+     * Where layer pixels changed since the last viewport render, when only strokes changed them
+     * (the renderer then recomposites just those rectangles); `'all'` after any other change.
+     */
+    private pendingDirty;
     private notify;
+    /** Recomputes the compatibility views (`adjustments`, `depthMask`, `annotations`) when the stack changed. */
+    private syncViews;
+    private stack;
     private captureHistoryEntry;
     private restoreHistoryEntry;
     private recordHistory;
+    /**
+     * Bytes of pixel tiles held only by undo / redo steps (not by the current state). The oldest
+     * undo steps are dropped while it exceeds `maxHistoryBytes`.
+     */
+    get historyBytes(): number;
+    private trimHistoryBytes;
     get canUndo(): boolean;
     get canRedo(): boolean;
     undo(): boolean;
@@ -1203,6 +1212,223 @@ declare class ImageEditorController {
     setRotation(degrees: number): void;
     flipHorizontal(): void;
     flipVertical(): void;
+    /** The layer stack, bottom to top (immutable objects). */
+    getLayers(): ImageLayer[];
+    getLayer(id: string): ImageLayer | undefined;
+    /** The active layer, or `undefined`. */
+    getActiveLayer(): ImageLayer | undefined;
+    /**
+     * Makes a layer the active one (or none) and chooses whether painting targets its pixels or
+     * its mask. View state: no undo step. Returns false for an unknown id.
+     */
+    setActiveLayer(id: string | null, target?: LayerTarget): boolean;
+    /**
+     * The pixels of a pixel layer, in document space (`x`, `y` is the top-left of the returned
+     * buffer), or `null` for an unknown or empty layer. Resolves the Background's source pixels.
+     */
+    getLayerPixels(id: string): (PixelBuffer & {
+        x: number;
+        y: number;
+    }) | null;
+    private boundsCache;
+    /**
+     * Document bounds of a layer's non-transparent pixels (pixel layers; the Background's source
+     * included), or `null` for an empty or non-pixel layer.
+     */
+    getLayerBounds(id: string): CropBox | null;
+    /**
+     * Composites the layer stack in document space without a canvas (annotation layers need one
+     * and are left out): `rect` (default: the canvas) as RGBA, straight alpha. Crop, rotation and
+     * output opacity are not applied. With `layerIds`, only those layers are composited.
+     */
+    compositePixels(rect?: CropBox, options?: {
+        layerIds?: string[];
+    }): PixelBuffer;
+    private compositorSources;
+    private sourceIds;
+    private nextSourceId;
+    /** Changes whenever the Background's source pixels can have changed. */
+    private sourceVersion;
+    /** The pixels a pixel layer composites (the decoded source for the Background). */
+    private surfaceOf;
+    /**
+     * The source image as a surface (cached): host-supplied sample pixels first, then the decoded
+     * element, then pixels read back for the selection tools.
+     */
+    private sourceSurface;
+    private opaqueCache;
+    /** Whether every source pixel is opaque (some legacy renders depend on it). */
+    private sourceIsOpaque;
+    /** Synchronously reads the source element's pixels through a canvas, or `null`. */
+    private decodeSource;
+    /** Records one undo step and applies a new stack (and any other state change in `extra`). */
+    private commitLayers;
+    /** The default position of a new layer: above the active layer, else the top of the stack. */
+    private newLayerPlacement;
+    /**
+     * Adds a pixel layer (one undo step) and makes it active: empty, filled with `color` over the
+     * canvas, or holding `pixels` placed at `x`, `y`. Goes above the active layer unless placed.
+     * Returns its id.
+     */
+    addPixelLayer(init?: PixelLayerInit): string;
+    /**
+     * `addPixelLayer` from an image: a PNG data URL or base64 PNG is decoded without a canvas;
+     * other formats and URLs need a browser. Returns the new layer id.
+     */
+    addPixelLayerFromImage(image: string, init?: Omit<PixelLayerInit, 'pixels' | 'color'>): Promise<string>;
+    /** RGBA pixels of an image given as a data URL, base64 PNG or URL. */
+    decodeImage(image: string): Promise<PixelBuffer>;
+    private nextLayerName;
+    /** Duplicates a layer (with its children) directly above it, as one undo step. Returns the copy's id. */
+    duplicateLayer(id: string, name?: string): string;
+    /** Deletes a layer (refused when locked), as one undo step. */
+    removeLayer(id: string): void;
+    /** Moves a layer above / below another, or into a group, as one undo step. Returns its new parent and index. */
+    moveLayer(id: string, placement: LayerPlacement): {
+        parentId: string | null;
+        index: number;
+    };
+    /**
+     * Changes name, visibility, opacity, fill, blend, clipping, locks or (groups) collapsed state, as
+     * one undo step (`commitToHistory = false` for the moves of a slider drag). Returns the layer.
+     */
+    setLayerProperties(id: string, props: LayerProperties, commitToHistory?: boolean): ImageLayer;
+    /** Adds an empty pass-through group above the active layer (or at `placement`) and makes it active. Returns its id. */
+    addGroup(init?: LayerPlacement & {
+        name?: string;
+        blend?: LayerBlendMode;
+    }): string;
+    /** Puts sibling layers into a new group (one undo step). Returns the group id. */
+    groupLayers(ids: string[], name?: string): string;
+    /** Replaces a group by its children (one undo step). Returns the child ids, bottom to top. */
+    ungroupLayer(id: string): string[];
+    /**
+     * Moves a pixel layer to an absolute offset (`x`, `y`) or by `dx`, `dy`, as one undo step
+     * (`commitToHistory = false` for the moves of a drag). Returns the offset and document bounds.
+     */
+    offsetLayer(id: string, move: {
+        x?: number;
+        y?: number;
+        dx?: number;
+        dy?: number;
+    }, commitToHistory?: boolean): {
+        offset: {
+            x: number;
+            y: number;
+        };
+        bounds: CropBox | null;
+    };
+    /**
+     * Adds a mask to a layer (one undo step): `reveal-all` (white), `hide-all` (black) or
+     * `selection` (the selection's coverage). Replaces an existing mask. Makes the mask the paint
+     * target when the layer is active.
+     */
+    addLayerMask(id: string, from?: 'reveal-all' | 'hide-all' | 'selection', props?: LayerMaskProps): RasterMask;
+    /** Removes a layer's mask (one undo step). */
+    removeLayerMask(id: string): void;
+    /** Changes any layer mask's density, feather or enabled flag (pixels kept). Returns the mask. */
+    setLayerMaskProps(id: string, props: LayerMaskProps, commitToHistory?: boolean): RasterMask;
+    /**
+     * Bakes a pixel layer's mask into its pixels (alpha × coverage, including density, feather or
+     * the depth map) and removes the mask, as one undo step.
+     */
+    applyLayerMask(id: string): Promise<void>;
+    /**
+     * Layer via Copy (or via Cut): a new pixel layer with the selected pixels of a pixel layer (the
+     * active one by default), directly above it, as one undo step. Returns the new id.
+     */
+    layerViaCopy(options?: {
+        layerId?: string;
+        cut?: boolean;
+        name?: string;
+    }): string;
+    /** Adds a `develop` or `blur` filter to a pixel layer (one undo step). Returns the layer's filters. */
+    addLayerFilter(id: string, filter: Partial<LayerFilter> & {
+        kind: LayerFilter['kind'];
+    }): LayerFilter[];
+    /** Changes one filter (one undo step, or none with `commitToHistory = false` during a drag). Returns the filters. */
+    updateLayerFilter(id: string, filterId: string, changes: Record<string, unknown>, commitToHistory?: boolean): LayerFilter[];
+    /** Removes one filter (one undo step). Returns the remaining filters. */
+    removeLayerFilter(id: string, filterId: string): LayerFilter[];
+    /** Composites `layers` (in isolation) over `rect` into a surface, loading depth maps first. */
+    private compositeToSurface;
+    /** Document bounds a layer can paint into (pixel content, annotations, or the canvas for the rest). */
+    private paintBounds;
+    /**
+     * Merge Down: composites a layer onto the pixel layer directly below it (which keeps its name,
+     * opacity and blend; masks, fill and filters are baked), as one undo step. Returns the merged id.
+     */
+    mergeDown(id: string): Promise<string>;
+    /**
+     * Merge Visible: the visible top-level layers become one normal pixel layer (at the position of
+     * the lowest of them); hidden layers stay. One undo step. Returns the merged id.
+     */
+    mergeVisible(): Promise<string>;
+    /** Flatten Image: every visible layer composited into one Background layer; hidden layers are discarded. One undo step. */
+    flattenImage(): Promise<string>;
+    private thumbCache;
+    /**
+     * A small RGBA preview of a pixel layer over the canvas (or of its mask with `mask: true`),
+     * longest side `maxSide` px, point-sampled; `null` for layers without pixels.
+     */
+    getLayerThumbnail(id: string, options?: {
+        maxSide?: number;
+        mask?: boolean;
+    }): PixelBuffer | null;
+    /** Brush settings, colours and tool options of the paint tools (view state, no undo). */
+    setPaintOptions(options: Partial<Omit<PaintOptions, 'brush'>> & {
+        brush?: Partial<BrushSettings>;
+    }): PaintOptions;
+    /** D: black foreground, white background. */
+    resetPaintColors(): void;
+    /** X: swaps the foreground and background colours. */
+    swapPaintColors(): void;
+    /** Resolves and validates what a stroke, fill or clear paints into. */
+    private paintTarget;
+    /** The layer with its pixels (or mask) replaced by `surface`. */
+    private withSurface;
+    /**
+     * Starts a brush or eraser stroke on a layer's pixels or mask (default: the active layer and
+     * target, the paint options' brush and colours). Feed points with `push`, finish with `end()`
+     * (one undo step for the whole stroke) or `cancel()`. While it runs, the stack shows the stroke
+     * without recording history.
+     */
+    beginStroke(init?: StrokeInit): PaintStrokeSession;
+    /** @internal Shows a stroke's live surface (no history). */
+    _strokeUpdate(layerId: string, channel: LayerTarget, surface: TiledSurface, rects: CropBox[]): void;
+    /** @internal Commits a finished stroke as one undo step (`before` is the pre-stroke state). */
+    _strokeCommit(before: HistoryEntryHandle, layerId: string, channel: LayerTarget, surface: TiledSurface | null): void;
+    /** @internal The pre-stroke snapshot. */
+    _captureForStroke(): HistoryEntryHandle;
+    /**
+     * Paints a whole stroke in one call (agents, replays): `points` in document pixels with optional
+     * pressure, through the brush or eraser. One undo step. Returns the layer, channel, the changed
+     * document bounds and the number of dabs.
+     */
+    paintStroke(init: StrokeInit & {
+        points: StrokePoint[];
+    }): PaintStrokeResult;
+    /**
+     * Edit › Fill: fills the selection (or, without one or with `useSelection: false`, the whole
+     * canvas) on a layer's pixels or mask with a colour (default the foreground), at `opacity` with
+     * `blend`. One undo step. Returns the changed bounds.
+     */
+    fillPixels(options?: FillOptions): PaintStrokeResult;
+    /**
+     * Edit › Clear: removes the selected pixels (alpha to 0; on a transparency-locked layer or a mask
+     * it fills with the background colour). Without a selection (or with `useSelection: false`) the
+     * whole canvas. One undo step. Returns the changed bounds.
+     */
+    clearPixels(options?: Omit<FillOptions, 'color' | 'blend'>): PaintStrokeResult;
+    private fillOrClear;
+    /** The pixel layer the base sliders edit: the active pixel layer, else the Background. */
+    private developLayer;
+    /**
+     * Sets base adjustment values as one undo step (unless `commitToHistory` is false). The base
+     * sliders edit the `develop` filter of the active pixel layer (or the Background), `blur` its
+     * blur filter (or `legacyOutputBlur` in migrated documents), `opacity` the output opacity, and
+     * `layers` replaces the adjustment layers.
+     */
     setAdjustments(partial: Partial<ImageAdjustments>, commitToHistory?: boolean): void;
     /** True when the adjustments use an older rendering process than {@link LATEST_PROCESS_VERSION}. */
     get isProcessOutdated(): boolean;
@@ -1213,13 +1439,24 @@ declare class ImageEditorController {
     upgradeProcess(): boolean;
     /** Resets the base sliders (latest process). Adjustment layers are kept; see `clearAdjustmentLayers`. */
     resetAdjustments(): void;
-    /** The adjustment layers, bottom (first) to top (last). */
+    /** The adjustment layers in stack order, bottom (first) to top (last). */
     getAdjustmentLayers(): AdjustmentLayer[];
     getAdjustmentLayer(id: string): AdjustmentLayer | undefined;
-    private setLayers;
+    private adjustmentNodes;
+    /**
+     * Where a new layer goes when no position is given: directly above the topmost layer that is
+     * not an annotation, so it adjusts what adjustment layers always adjusted (annotations stay on top).
+     */
+    private defaultInsertIndex;
+    /** Inserts `node` by `aboveId` / `parentId` / adjustment index / default position. */
+    private placeLayer;
+    /** `setAdjustments({ layers })`: updates nodes by id in place, removes missing ones, adds new ones. */
+    private replaceAdjustmentNodes;
     /**
-     * Adds an adjustment layer on top (or at `index`, 0 = bottom) as one undo step and returns
-     * its id. `kind` alone gives neutral parameters.
+     * Adds an adjustment layer and returns its id, as one undo step. With no position it goes
+     * above the other adjustment layers (or, without any, above the topmost non-annotation layer,
+     * so annotations stay on top); `index` counts adjustment layers (0 = below the others);
+     * `aboveId` / `parentId` place it anywhere in the stack. `kind` alone gives neutral parameters.
      */
     addAdjustmentLayer<K extends AdjustmentKind>(init: K | AdjustmentLayerInit<K>, index?: number): string;
     /**
@@ -1230,7 +1467,8 @@ declare class ImageEditorController {
     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. */
+    private moveAdjustmentNode;
+    /** Moves a layer to `toIndex` among the adjustment layers (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;
@@ -1262,13 +1500,14 @@ declare class ImageEditorController {
     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.
+     * or in a test; `null` goes back to reading the source image. Without a canvas (Node, workers)
+     * these are also the Background layer's pixels.
      */
     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).
+     * `sampleMerged` the composite of the layers (no crop, rotation or annotations). `null`
+     * without pixel access (no DOM, tainted canvas).
      */
     getSamplePixels(options?: SampleOptions): Promise<PixelBuffer | null>;
     private requirePixels;
@@ -1298,11 +1537,13 @@ declare class ImageEditorController {
     }): Promise<SelectionMask | null>;
     /** Quick Mask view (tints the unselected area). View state: no undo step. */
     setQuickMask(on: boolean): void;
+    private maskFromSelection;
     /**
      * 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;
+    private setLayerMask;
     /** 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. */
@@ -1316,9 +1557,12 @@ declare class ImageEditorController {
     getHistogram(): ImageHistogram | null;
     /** Calls `listener` now and whenever a render produces a new preview histogram. */
     subscribeHistogram(listener: (histogram: ImageHistogram | null) => void): () => void;
+    /** Sets the depth mask (a parametric mask on the active pixel layer, or the Background) as one undo step. */
     setDepthMask(partial: Partial<DepthMaskOptions>): void;
     resetDepthMask(): void;
-    addAnnotation(annotation: CreateAnnotationPayload): string;
+    private annotationLayer;
+    /** Adds an annotation as its own layer (top of the stack unless `aboveId` is given). */
+    addAnnotation(annotation: CreateAnnotationPayload, placement?: AnnotationPlacement): string;
     updateAnnotation(id: string, partial: Partial<Annotation>, commitToHistory?: boolean): void;
     removeAnnotation(id: string): void;
     clearAnnotations(): void;
@@ -1329,6 +1573,7 @@ declare class ImageEditorController {
     resetZoom(): void;
     setPan(pan: ImagePoint): void;
     setComparing(comparing: boolean): void;
+    setFit(fit: ImageEditorFit): void;
     render(targetCanvas: HTMLCanvasElement, options?: RenderOptions): Promise<void>;
     renderExport(options?: ExportOptions): Promise<HTMLCanvasElement>;
     /**
@@ -1366,23 +1611,572 @@ declare class ImageEditorController {
      */
     applyInpaintedImage(newDataUrl: string): Promise<void>;
     /**
-     * Replaces the source image with a background-removed result as ONE undoable step.
-     * Crop and annotations are kept (rescaled if the new image has different dimensions).
+     * Replaces the source image with a background-removed result as ONE undoable step.
+     * Crop and annotations are kept (rescaled if the new image has different dimensions).
+     */
+    applyBackgroundRemovedImage(newDataUrl: string): Promise<void>;
+    private replaceSource;
+    /**
+     * The serializable state. A document whose layers still have the v1 / v2 shape (the
+     * Background with its sliders and depth mask, adjustment layers, annotations) is written as
+     * v1 / v2 exactly as before; anything else is written as v3 with the layer pixels as PNG
+     * assets. `selection` is included (run-length encoded) only when something is selected.
+     */
+    toJSON(): SerializedImageEditorState;
+    /** Loads a stored state of any version (one undo step). */
+    loadJSON(data: SerializedImageEditorState): void;
+    /** Problems found by the last `loadJSON` / `initialState` of a v3 document (unreadable layers or assets). */
+    lastLoadProblems: string[];
+    private applyStored;
+    private serializeState;
+}
+/** A colour as RGBA bytes: `#rgb`, `#rrggbb`, `#rrggbbaa` or `[r, g, b, a?]` (0..255). */
+declare function parseColor(value: string | number[]): [number, number, number, number];
+/** `#rrggbb` of RGBA bytes (alpha dropped). */
+declare function toHex(c: readonly number[]): string;
+
+interface ImageDimensions {
+    width: number;
+    height: number;
+}
+interface ImagePoint {
+    x: number;
+    y: number;
+}
+interface CropBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type AspectRatio = number | null;
+interface ImageTransform {
+    rotate: number;
+    flipH: boolean;
+    flipV: boolean;
+}
+interface ImageAdjustments {
+    brightness: number;
+    contrast: number;
+    saturation: number;
+    exposure: number;
+    temperature: number;
+    /**
+     * -100 (green) to 100 (magenta), 0 is default. White-balance tint correction in Duv × 3000
+     * (process 2 only; the legacy process ignores it).
+     */
+    tint?: number;
+    blur: number;
+    opacity: number;
+    /**
+     * Rendering process the values are interpreted by. `2` (the latest; new edits and Reset get
+     * it): linear-light exposure, Bradford white balance, LUT tone curve without intermediate
+     * clipping. `1` or missing: the legacy 8-bit rendering, so edits saved before process
+     * 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;
+    mode: 'threshold' | 'brightness';
+    depthRange: [number, number];
+    softness: number;
+    invert: boolean;
+}
+type AnnotationType = 'pen' | 'rect' | 'circle' | 'arrow' | 'line' | 'text' | 'image';
+interface BaseAnnotation {
+    id: string;
+    type: AnnotationType;
+    x: number;
+    y: number;
+    rotation?: number;
+    opacity?: number;
+    /** Blend mode the annotation is drawn with (default `normal`). */
+    blend?: BlendMode;
+}
+interface PenAnnotation extends BaseAnnotation {
+    type: 'pen';
+    points: ImagePoint[];
+    strokeColor: string;
+    strokeWidth: number;
+}
+interface RectAnnotation extends BaseAnnotation {
+    type: 'rect';
+    width: number;
+    height: number;
+    strokeColor: string;
+    strokeWidth: number;
+    fillColor?: string;
+    cornerRadius?: number;
+}
+interface CircleAnnotation extends BaseAnnotation {
+    type: 'circle';
+    radiusX: number;
+    radiusY: number;
+    strokeColor: string;
+    strokeWidth: number;
+    fillColor?: string;
+}
+interface ArrowAnnotation extends BaseAnnotation {
+    type: 'arrow';
+    endX: number;
+    endY: number;
+    strokeColor: string;
+    strokeWidth: number;
+}
+interface LineAnnotation extends BaseAnnotation {
+    type: 'line';
+    endX: number;
+    endY: number;
+    strokeColor: string;
+    strokeWidth: number;
+}
+interface TextAnnotation extends BaseAnnotation {
+    type: 'text';
+    text: string;
+    fontSize: number;
+    fontFamily?: string;
+    color: string;
+    fontWeight?: string | number;
+}
+interface ImageAnnotation extends BaseAnnotation {
+    type: 'image';
+    src: string;
+    width: number;
+    height: number;
+}
+type Annotation = PenAnnotation | RectAnnotation | CircleAnnotation | ArrowAnnotation | LineAnnotation | TextAnnotation | ImageAnnotation;
+type CreateAnnotationPayload = Omit<PenAnnotation, 'id'> | Omit<RectAnnotation, 'id'> | Omit<CircleAnnotation, 'id'> | Omit<ArrowAnnotation, 'id'> | Omit<LineAnnotation, 'id'> | Omit<TextAnnotation, 'id'> | Omit<ImageAnnotation, 'id'>;
+type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'arrow' | 'line' | 'text' | 'watermark' | 'move' | 'brush' | 'eraser';
+type ImageEditorFit = 'contain' | 'margin';
+interface ImageEditorState {
+    sourceUrl: string | null;
+    /** Canvas (document) size in pixels: the source image's natural size. */
+    imageDimensions: ImageDimensions;
+    crop: CropBox | null;
+    transform: ImageTransform;
+    /**
+     * Compatibility view of the layer stack: the develop filter of the active pixel layer (or the
+     * Background), its blur (or `legacyOutputBlur`), the output opacity and every adjustment layer
+     * in stack order. Edit it with `setAdjustments` and the adjustment-layer methods.
+     */
+    adjustments: ImageAdjustments;
+    /** Compatibility view: the parametric depth mask of the active pixel layer (or the Background). */
+    depthMask: DepthMaskOptions;
+    /** Compatibility view: the annotation of every annotation layer, bottom to top. */
+    annotations: Annotation[];
+    selectedAnnotationId: string | null;
+    activeTool: ImageEditorTool;
+    zoom: number;
+    pan: ImagePoint;
+    isOriginalCompared: boolean;
+    /** Viewport fit mode: 'contain' scales to full viewport bounds; 'margin' scales to 85% with 1.0 cap (default). */
+    fit?: ImageEditorFit;
+    /**
+     * 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;
+    /**
+     * The layer stack, bottom to top. Opening an image gives one pixel layer, "Background", whose
+     * pixels are the source image. Layers are immutable: compare them by identity.
+     */
+    layers: ImageLayer[];
+    /** The layer that layer commands, painting and `setAdjustments` act on, or `null`. */
+    activeLayerId: string | null;
+    /** Whether painting targets the active layer's pixels or its mask. */
+    activeTarget: LayerTarget;
+    /** Export alpha (0..1), applied after compositing; `adjustments.opacity` mirrors it. */
+    outputOpacity: number;
+    /**
+     * Blur that runs after the adjustment layers, kept from v1 / v2 documents that had both so
+     * they render as before. New edits blur a layer instead (`blur` filter).
+     */
+    legacyOutputBlur?: number;
+    /** Brush settings and foreground / background colours of the paint tools (view state). */
+    paint: PaintOptions;
+}
+/**
+ * A stored editor state in the document-level schema (versions 1 and 2). Documents whose layer
+ * stack has exactly this shape are still written this way, byte for byte.
+ */
+interface LegacySerializedImageEditorState {
+    /**
+     * 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;
+}
+/**
+ * A stored editor state: the document-level schema (v1 / v2) or the layered schema (v3, see
+ * `SerializedLayeredImageEditorState`). `toJSON()` writes v1 / v2 while the layer stack still
+ * has the shape those versions describe.
+ */
+type SerializedImageEditorState = LegacySerializedImageEditorState | SerializedLayeredImageEditorState;
+interface ExportOptions {
+    format?: 'image/png' | 'image/jpeg' | 'image/webp';
+    quality?: number;
+    width?: number;
+    height?: number;
+    includeAnnotations?: boolean;
+    /** Render only these layers (groups with their children). */
+    layerIds?: string[];
+}
+interface ImageEditorOptions {
+    image?: string | HTMLImageElement;
+    initialState?: Partial<SerializedImageEditorState>;
+    onStateChange?: (state: ImageEditorState) => void;
+    maxHistoryDepth?: number;
+    /**
+     * Upper bound for the pixel data held only by undo / redo steps (tiles shared with the
+     * current state are free). The oldest steps are dropped first. Default 512 MiB.
      */
-    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;
+    maxHistoryBytes?: number;
+    /** Viewport fit mode: 'contain' scales to full viewport bounds; 'margin' scales to 85% with 1.0 cap (default). */
+    fit?: ImageEditorFit;
+}
+interface InpaintOptions {
+    prompt: string;
+    imageDataUrl: string;
+    maskDataUrl?: string;
+    cropBox?: CropBox | null;
+}
+interface RemoveBackgroundOptions {
+    imageDataUrl: string;
+}
+type InpaintHook = (options: InpaintOptions) => Promise<string | void> | string | void;
+type RemoveBackgroundHook = (options: RemoveBackgroundOptions) => Promise<string | void> | string | void;
+interface ImageEditorAIHooks {
+    onInpaint?: InpaintHook;
+    onRemoveBackground?: RemoveBackgroundHook;
+}
+
+/**
+ * Applies color and tone adjustments (brightness, contrast, saturation, exposure, temperature, tint,
+ * 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, 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.
+ */
+declare function applyLegacyAdjustments(imageData: {
+    data: Uint8ClampedArray;
+}, adjustments: ImageAdjustments): void;
+/**
+ * Process 2: decode sRGB to linear float once; apply exposure (gain) and white balance (a
+ * Bradford matrix relative to as-shot) in linear light; a per-channel tone LUT for the
+ * highlight shoulder, contrast and brightness; luminance-preserving saturation in linear light;
+ * then encode back to sRGB through a LUT. Nothing is clamped between stages, only at the final
+ * encode. Neutral settings are the identity.
+ */
+declare function applyProcess2Adjustments(imageData: {
+    data: Uint8ClampedArray;
+}, adjustments: ImageAdjustments): void;
+/**
+ * Fast separable box blur running horizontally and vertically (`adjustments.blur` and the `blur`
+ * layer filter): `radius` pixels each side, edges clamped, rounded after each pass.
+ */
+declare function applyBoxBlur(imageData: {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}, radius: number): void;
+/**
+ * Blends a depth/alpha mask into the main image data based on Gleamforge depth masking.
+ * Supports threshold range with softness gradation, brightness mode, and optional inversion.
+ */
+declare function applyDepthMask(mainImageData: ImageData, maskImageData: ImageData, options: DepthMaskOptions): void;
+/**
+ * Removes alpha channel by setting all alpha bytes to 255 (completely opaque).
+ * From Gleamforge image-filters.ts.
+ */
+declare function removeAlpha(imageData: ImageData): void;
+
+/**
+ * Colour science for the image editor's process 2 rendering: sRGB transfer functions,
+ * correlated colour temperature / tint (Kim et al. Planckian locus, tint as Duv), Bradford
+ * white-balance adaptation relative to "as shot", and the display-referred tone curve.
+ */
+/** A CIE 1931 chromaticity. */
+interface Chromaticity {
+    x: number;
+    y: number;
 }
+/** A row-major 3×3 matrix (`[m00, m01, m02, m10, …, m22]`). */
+type Matrix3 = [number, number, number, number, number, number, number, number, number];
+/** The rendering of adjustments from before process versions existed. Frozen. */
+declare const LEGACY_PROCESS_VERSION: 1;
+/** The process new edits and Reset get. */
+declare const LATEST_PROCESS_VERSION: 2;
+type ImageProcessVersion = 1 | 2;
+/**
+ * Reads a stored process number leniently: a missing or damaged value (not a whole number) is
+ * the legacy process, so a saved edit from before process versions renders exactly as it did. A
+ * whole number newer than this build knows renders with the latest process.
+ */
+declare function normalizeProcessVersion(value: unknown): ImageProcessVersion;
+declare function srgbToLinear(v: number): number;
+declare function linearToSrgb(v: number): number;
+/** Rec.709 / sRGB luminance weights (linear light). */
+declare const LUMA_709: readonly [number, number, number];
+declare const IDENTITY_MATRIX3: Matrix3;
+declare function mulMatrix3(a: Matrix3, b: Matrix3): Matrix3;
+declare function applyMatrix3(m: Matrix3, v: readonly [number, number, number]): [number, number, number];
+declare function invertMatrix3(m: Matrix3): Matrix3 | null;
+declare const D65: Chromaticity;
+/** Bradford chromatic adaptation (XYZ → XYZ) from white `src` to white `dst`. */
+declare function bradfordAdaptation(src: Chromaticity, dst: Chromaticity): Matrix3;
+/**
+ * Matrix (linear sRGB → linear sRGB) that white-balances a scene lit by `src` so that it
+ * renders as if lit by D65.
+ */
+declare function wbMatrix(src: Chromaticity): Matrix3;
+/** The chromaticity of a linear sRGB colour. */
+declare function linearSrgbToXy(rgb: readonly [number, number, number]): Chromaticity;
+/** Tint units per unit of Duv. */
+declare const TINT_SCALE = 3000;
+declare const MIN_KELVIN = 1667;
+declare const MAX_KELVIN = 25000;
+/** CIE 1931 xy → CIE 1960 uv. */
+declare function xyToUv(p: Chromaticity): [number, number];
+/** CIE 1960 uv → CIE 1931 xy. */
+declare function uvToXy(u: number, v: number): Chromaticity;
+/**
+ * Source illuminant chromaticity for temperature `kelvin` and correction `tint`.
+ * Positive tint means a green source white, whose correction adds magenta to the image.
+ */
+declare function tempTintToXy(kelvin: number, tint: number): Chromaticity;
+/** Inverse of {@link tempTintToXy}: nearest locus temperature (searched in mired space) and tint. */
+declare function xyToTempTint(p: Chromaticity): {
+    kelvin: number;
+    tint: number;
+};
+/** Rendered images carry no as-shot white: "as shot" is 6500 K / tint 0 and maps to the identity. */
+declare const AS_SHOT_KELVIN = 6500;
+/** Mireds per unit of the `temperature` slider (−100…100). */
+declare const MIRED_PER_TEMPERATURE_UNIT = 1;
+/**
+ * Maps the `temperature` slider (−100 cool … +100 warm) to the Kelvin white-balance setting:
+ * one mired per unit around 6500 K, so 0 → 6500 K, +100 → ~18 570 K (a strong warming
+ * correction), −100 → ~3 940 K (a strong cooling correction). Mireds are perceptually even,
+ * so equal slider steps look like equal changes.
+ */
+declare function temperatureToKelvin(temperature: number): number;
+/** Inverse of {@link temperatureToKelvin}. */
+declare function kelvinToTemperature(kelvin: number): number;
+/**
+ * White-balance matrix (linear sRGB) for the `temperature` / `tint` sliders, relative to
+ * "as shot": the identity at 0 / 0. Normalised so neutral luminance is preserved (white
+ * balance doesn't change exposure).
+ */
+declare function whiteBalanceMatrix(temperature: number, tint?: number): Matrix3;
+/**
+ * Neutral-point eyedropper: the `temperature` / `tint` that render the sampled sRGB colour
+ * (0–255 per channel, as it appears in the unadjusted image) neutral. Results are clamped to
+ * the slider range −100…100.
+ */
+declare function whiteBalanceFromSample(rgb: readonly [number, number, number] | {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    temperature: number;
+    tint: number;
+};
+/** Number of intervals in a tone LUT (the table has `TONE_LUT_SIZE + 1` entries). */
+declare const TONE_LUT_SIZE = 4096;
+/**
+ * The process 2 tone curve for one linear input value in `[0, headroom]`:
+ *
+ * 1. A highlight shoulder (extended Reinhard with white point `headroom`) above a knee of 0.6
+ *    rolls values above 1 (after exposure / white balance) back into range instead of clipping.
+ *    With no headroom (`headroom = 1`) it is exactly the identity.
+ * 2. In a gamma-2.2 perceptual domain, contrast is an S-curve anchored at 0, middle grey and 1
+ *    (as `ToneMap::display`), and brightness a midtone lift anchored at 0 and 1.
+ *
+ * `contrast` and `brightness` are −100…100; both 0 with `headroom = 1` is the identity.
+ */
+declare function toneCurve(y: number, contrast: number, brightness: number, headroom?: number): number;
+/** Tabulates {@link toneCurve} over `[0, headroom]` in {@link TONE_LUT_SIZE} steps. */
+declare function buildToneLut(contrast: number, brightness: number, headroom?: number): Float32Array;
+/** Linearly interpolated lookup into a LUT from {@link buildToneLut}. */
+declare function sampleToneLut(lut: Float32Array, headroom: number, y: number): number;
 
-/** 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.
+ * The newest `version` that `ImageEditorController.toJSON()` writes (3: layers). Documents whose
+ * layers still have the old shape are written as version 1 or 2.
+ */
+declare const IMAGE_EDITOR_STATE_VERSION = 3;
+/**
+ * Migration steps for the document-level schema (versions 1 and 2), keyed by the version they
+ * start from. Empty: version 2 only adds `adjustments.layers`, which version 1 readers keep.
  */
 declare const imageEditorStateMigrations: Record<number, MigrationStep>;
 interface ImageEditorDocumentLoad {
@@ -1547,7 +2341,9 @@ declare function evaluateAdjustmentLayers(color: readonly number[], layers: read
  * 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;
+declare function applyAdjustmentLayers(imageData: {
+    data: Uint8ClampedArray;
+}, 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;
 
@@ -1792,6 +2588,24 @@ declare function createImageSelectionTools(controller: ImageEditorController): A
  */
 declare function createImageEditTools(controller: ImageEditorController): AgentTool[];
 
+/** A short description of a mask for agents (no pixels). */
+declare function maskSummary(mask: RasterMask | undefined): Record<string, unknown> | null;
+/**
+ * A plain description of a layer (and its children) for agents: ids, types, names, document
+ * bounds, visibility, opacity, fill, blend, clipping, locks, mask summary and whether it is
+ * active. `boundsOf` gives a pixel layer's document bounds.
+ */
+declare function describeLayer(layer: ImageLayer, activeId: string | null, boundsOf: (layer: ImageLayer) => CropBox | null): Record<string, unknown>;
+/**
+ * Agent tools for the image editor's layer stack: `list_layers`, `set_active_layer`,
+ * `add_pixel_layer`, `duplicate_layer`, `remove_layer`, `move_layer`, `set_layer_properties`,
+ * `group_layers`, `ungroup_layer`, `merge_down`, `merge_visible`, `flatten_image`, `offset_layer`,
+ * `add_layer_mask`, `apply_layer_mask`, `remove_layer_mask`, `set_layer_mask_properties`,
+ * `layer_via_copy`, `add_layer_filter`, `update_layer_filter` and `remove_layer_filter`. Each write
+ * is one undo step, validates before changing anything and returns what it changed.
+ */
+declare function createImageLayerTools(controller: ImageEditorController): AgentTool[];
+
 /**
  * Region-based mosaic (pixelation) and box-blur filters for redacting or anonymizing
  * rectangular bounding boxes on an ImageData-like buffer.
@@ -1842,4 +2656,277 @@ declare function applyRegionBlur<T extends MosaicImageDataLike>(imageData: T, re
  */
 declare function createImageCaptureSurface(controller: ImageEditorController): CaptureSurface;
 
-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 MosaicImageDataLike, type MosaicRegion, 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, applyRegionBlur, applyRegionMosaic, 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, createImageCaptureSurface, createImageEditTools, 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, resolveMosaicRegionBounds, 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 };
+/**
+ * Between the old document-level model (schema v1 / v2: base sliders, adjustment layers, blur,
+ * depth mask and annotations) and the layer stack:
+ *
+ * - `layersFromLegacy` lifts a v1 / v2 state into layers: the source becomes the Background
+ *   pixel layer carrying the base sliders as its `develop` filter and the depth mask as its
+ *   parametric mask; adjustment layers go above it, annotations on top in their order. Blur
+ *   becomes a `blur` filter on the Background, or `legacyOutputBlur` when adjustment layers
+ *   exist (blur used to run after them).
+ * - `legacyView` reads the stack back as `adjustments` / `depthMask` / `annotations` (the
+ *   compatibility views on the editor state) and says whether the stack still has exactly the
+ *   legacy shape, in which case it serializes as v1 / v2 byte for byte.
+ */
+
+declare const BACKGROUND_LAYER_ID = "background";
+declare const BACKGROUND_LAYER_NAME = "Background";
+declare const DEVELOP_FILTER_ID = "develop";
+declare const BLUR_FILTER_ID = "blur";
+/** The old document-level parts of the editor state. */
+interface LegacyParts {
+    adjustments: ImageAdjustments;
+    depthMask: DepthMaskOptions;
+    annotations: Annotation[];
+}
+/** The stack as stored at document level next to the layers. */
+interface LayerStack {
+    layers: ImageLayer[];
+    /** Export alpha (the old `adjustments.opacity`), 0..1. */
+    outputOpacity: number;
+    /** Migrated blur that must run after the adjustment layers (never created by new edits). */
+    legacyOutputBlur?: number;
+}
+/** A raster mask from an old adjustment-layer mask, resampled to the document if needed. */
+declare function rasterMaskFromLegacy(mask: AdjustmentLayerMask, width: number, height: number): RasterMask | null;
+/**
+ * True when an adjustment layer's mask came from a v1 / v2 mask of another size than the canvas
+ * (the old renderer resampled it per render; the stack holds a canvas-sized copy).
+ */
+declare function hasResampledLegacyMask(layers: readonly ImageLayer[], width: number, height: number): boolean;
+/** The old mask shape of a raster mask (its pixels over the canvas, run-length encoded). */
+declare function legacyMaskOf(mask: RasterMask, width: number, height: number): AdjustmentLayerMask;
+/** True when the depth mask settings are the defaults (no mask at all). */
+declare function isDefaultDepthMask(mask: DepthMaskOptions | undefined): boolean;
+declare function developFromAdjustments(adjustments: ImageAdjustments): DevelopFilter;
+/** The default name of an annotation layer. */
+declare function annotationLayerName(annotation: Annotation): string;
+declare function annotationLayerFor(annotation: Annotation): AnnotationLayer;
+declare function adjustmentNodeFromLegacy(layer: AdjustmentLayer, width: number, height: number): AdjustmentLayerNode;
+/** The Background layer of an opened image (its pixels are the document source). */
+declare function backgroundLayer(filters?: LayerFilter[], mask?: RasterMask): PixelLayer;
+/** A parametric depth mask on a layer. */
+declare function depthRasterMask(source: DepthMaskOptions): RasterMask;
+/** Lifts a v1 / v2 state into a layer stack (see the module comment). */
+declare function layersFromLegacy(parts: Partial<LegacyParts>, width: number, height: number): LayerStack;
+/** The old `AdjustmentLayer` shape of a node, keys in the order `normalizeAdjustmentLayer` writes. */
+declare function legacyAdjustmentLayer(node: AdjustmentLayerNode, width: number, height: number): AdjustmentLayer;
+/** The pixel layer whose develop filter the legacy API edits: the active one, else the Background. */
+declare function developTarget(layers: readonly ImageLayer[], activeLayerId: string | null): PixelLayer | null;
+interface LegacyViewResult extends LegacyParts {
+    /**
+     * True when the stack has exactly the shape a v1 / v2 document lifts to (an unpainted,
+     * unmoved Background with develop / blur filters and an optional depth mask, then adjustment
+     * layers, then plain annotation layers), so it can be written as v1 / v2.
+     */
+    exact: boolean;
+}
+/** Reads the stack back as the old document-level parts (see `LegacyViewResult`). */
+declare function legacyView(stack: LayerStack, width: number, height: number, activeLayerId?: string | null): LegacyViewResult;
+/** See `LegacyViewResult.exact`. */
+declare function isLegacyShape(stack: LayerStack): boolean;
+
+/**
+ * Pure helpers between the compositor and the renderer: the output stage (projection to the
+ * cropped, rotated frame, output opacity and the migrated blur), the routing rule that keeps
+ * old-shape documents on the exact legacy path where document-space compositing cannot match it,
+ * and per-tile histograms. No DOM.
+ */
+
+/** True for 0, 90, 180 and 270 degrees. */
+declare function isQuarterTurn(rotate: number): boolean;
+/** The projection that draws `region` into a `baseW × baseH` buffer at scale 1 (the renderer's base canvas). */
+declare function baseProjection(region: CropBox, transform: ImageTransform, baseW: number, baseH: number): ImageProjection;
+/**
+ * Projects `src` (RGBA covering `srcRect` in document space) into the base frame of `region`
+ * under a quarter-turn `transform`: an exact pixel permutation (crop, flips, 90° steps), the
+ * same mapping the canvas draws with. Returns the base buffer and its size.
+ */
+declare function projectQuarterTurn(src: ArrayLike<number>, srcRect: CropBox, region: CropBox, transform: ImageTransform): {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+/** Output opacity as the old base adjustments applied it (`clamp(a · opacity)`), then the migrated blur. */
+declare function applyOutputStage(img: {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}, opacity: number, legacyOutputBlur?: number): void;
+interface RouteInput {
+    stack: LayerStack;
+    region: CropBox;
+    canvas: {
+        width: number;
+        height: number;
+    };
+    transform: ImageTransform;
+    /** Whether the source image is fully opaque. */
+    sourceOpaque: boolean;
+}
+/**
+ * Whether a document must render through the legacy base path to look exactly as before. Only
+ * documents that still have the v1 / v2 shape qualify, and only where compositing in document
+ * space cannot reproduce the old order of operations:
+ *
+ * - a rotation that is not a quarter turn, or a crop with fractional coordinates (the old path
+ *   resampled before adjusting);
+ * - an enabled depth mask (applied after the blur and resampled with the canvas);
+ * - output opacity below 1 (it rounded alpha before the depth mask);
+ * - a Background blur filter with a crop or a 90° / 270° turn (the old blur clamped at the crop
+ *   edge and ran on the rotated buffer);
+ * - a migrated output blur over a source with transparency (canvas premultiplication would round
+ *   colours before blurring);
+ * - an adjustment-layer mask stored at another size than the canvas (it was resampled through
+ *   the projection on every render).
+ */
+declare function needsLegacyBase(input: RouteInput): boolean;
+/**
+ * Splits the stack into what the compositor rasterizes and the annotation layers at the top that
+ * draw as crisp vectors over the result (as annotations always did): the trailing run of plain
+ * top-level annotation layers (hidden ones are skipped).
+ */
+declare function splitOverlayAnnotations(layers: readonly ImageLayer[]): {
+    composite: ImageLayer[];
+    overlay: AnnotationLayer[];
+};
+/** The integer rectangle covering `region`. */
+declare function coveringRect(region: CropBox): CropBox;
+/**
+ * The base image of a layered document without a canvas: the stack composited over `region`
+ * (integer), projected under a quarter-turn `transform`, then output opacity and the migrated
+ * blur. Annotation layers need a canvas and are skipped unless `sources` can rasterize them.
+ * This is what the renderer's base canvas holds for such documents.
+ */
+declare function renderLayeredBase(stack: LayerStack, region: CropBox, transform: ImageTransform, sources: CompositorSources, compositor?: LayerCompositor): {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+/** An empty histogram. */
+declare function emptyHistogram(): ImageHistogram;
+/** Adds the pixels of `rect` (in tile-local coordinates of a `stride`-wide RGBA buffer) to `h`. */
+declare function addToHistogram(h: ImageHistogram, data: ArrayLike<number>, stride: number, rect: CropBox): void;
+/** Sums histograms (and recomputes `max`). */
+declare function sumHistograms(parts: Iterable<ImageHistogram>): ImageHistogram;
+
+/**
+ * The layers panel's view model, shared by the React and Svelte panels: the rows to show (top of
+ * the stack first, groups indented, collapsed groups hiding their children), where a drop lands,
+ * and the menu of layer operations with whether each one applies to the active layer.
+ */
+
+interface LayerPanelRow {
+    layer: ImageLayer;
+    /** Nesting depth (0 = top level). */
+    depth: number;
+    parentId: string | null;
+    /** Index among its siblings, 0 = bottom. */
+    index: number;
+    active: boolean;
+    /** Display name (adjustment layers without a name show their kind). */
+    label: string;
+    /** Clipped to the layer below (drawn with an indent arrow). */
+    clipped: boolean;
+}
+/** Rows top to bottom; children of collapsed groups are left out. */
+declare function layerPanelRows(layers: readonly ImageLayer[], activeId: string | null): LayerPanelRow[];
+declare function layerLabel(layer: ImageLayer): string;
+/** A short type badge for rows without a thumbnail. */
+declare function layerBadge(layer: ImageLayer): string;
+/** Where a row was dropped on: the top or bottom part of the row, or the middle of a group row. */
+type DropZone = 'above' | 'below' | 'inside';
+/** The zone for a pointer at `fraction` (0 top .. 1 bottom) of a row's height. */
+declare function dropZone(fraction: number, isGroup: boolean): DropZone;
+/** The placement for `move_layer` when `dragId` is dropped on row `targetId` in `zone`, or `null` for a no-op. */
+declare function dropPlacement(layers: readonly ImageLayer[], dragId: string, targetId: string, zone: DropZone): LayerPlacement | null;
+type LayerMenuAction = 'new-layer' | 'new-group' | 'duplicate' | 'delete' | 'group-selected' | 'ungroup' | 'merge-down' | 'merge-visible' | 'flatten' | 'via-copy' | 'via-cut' | 'add-mask' | 'add-mask-selection' | 'apply-mask' | 'delete-mask' | 'toggle-mask' | 'toggle-clip';
+interface LayerMenuItem {
+    action: LayerMenuAction;
+    label: string;
+    enabled: boolean;
+}
+/** The layer menu for the controller's current state (active layer, selection). */
+declare function layerMenu(controller: ImageEditorController): LayerMenuItem[];
+/** Runs a menu action on the active layer. Resolves to the error message when it was refused. */
+declare function runLayerMenuAction(controller: ImageEditorController, action: LayerMenuAction): Promise<string | null>;
+
+/**
+ * Agent tools for painting: `paint_stroke` (brush or eraser along points, on pixels or a mask),
+ * `fill_pixels` and `clear_pixels` (Edit › Fill / Clear inside the selection). Each is one undo
+ * step and returns the layer, channel and changed bounds.
+ */
+declare function createImagePaintTools(controller: ImageEditorController): AgentTool[];
+
+/**
+ * The paint tools' view model, shared by the React and Svelte editors: the brush options bar's
+ * controls, Photoshop's shortcuts (B, E, V, [ ], Shift+[ ], number keys, D, X) and a pointer
+ * gesture that turns pointer events into strokes (Brush, Eraser) or layer moves (Move).
+ */
+
+/** Controls of the brush options bar (`hardness`, `opacity`, `flow`, `smoothing` shown in %). */
+declare const BRUSH_OPTION_CONTROLS: readonly (ControlSpec & {
+    id: 'size' | 'hardness' | 'opacity' | 'flow' | 'smoothing';
+})[];
+/** The paint tools in the toolbar. */
+declare const PAINT_TOOLS: readonly [{
+    readonly id: "move";
+    readonly label: "Move";
+    readonly shortcut: "V";
+}, {
+    readonly id: "brush";
+    readonly label: "Brush";
+    readonly shortcut: "B";
+}, {
+    readonly id: "eraser";
+    readonly label: "Eraser";
+    readonly shortcut: "E";
+}];
+type PaintTool = (typeof PAINT_TOOLS)[number]['id'];
+declare const isPaintTool: (tool: string) => tool is PaintTool;
+interface ShortcutEvent {
+    key: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+    /** The event target: shortcuts are ignored while typing in inputs. */
+    target?: unknown;
+}
+/**
+ * Applies a paint shortcut. Returns true when it was one (the caller then prevents the default).
+ * B / E / V choose the tool; [ and ] change the size, with Shift the hardness by 25 %; 1..9 set the
+ * opacity to 10..90 % and 0 to 100 %; D resets the colours to black and white; X swaps them.
+ */
+declare function handlePaintShortcut(controller: ImageEditorController, e: ShortcutEvent): boolean;
+/** One pointer sample in document pixels. */
+interface PaintPointerSample extends ImagePoint {
+    /** 0..1; a mouse is 1. */
+    pressure: number;
+}
+/** Pressure of a pointer event: pens report it; mice report 0.5 while pressed, which means "full". */
+declare function pointerPressure(e: {
+    pointerType?: string;
+    pressure?: number;
+}): number;
+/**
+ * Turns pointer events into strokes (Brush, Eraser on the active layer's target) or layer moves
+ * (Move on the active pixel layer). `down` returns an error message when the tool cannot act.
+ */
+declare class PaintGesture {
+    private readonly controller;
+    private stroke;
+    private move;
+    /** The last refusal (e.g. "layer is locked"), for the editor to show. */
+    error: string | null;
+    constructor(controller: ImageEditorController);
+    get active(): boolean;
+    down(sample: PaintPointerSample): string | null;
+    /** Feeds pointer samples (all coalesced events of one move, in order). */
+    moveTo(samples: PaintPointerSample[]): void;
+    up(): void;
+    cancel(): void;
+}
+
+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 AdjustmentLayerNode, type AdjustmentLayerOf, type AdjustmentLayerUpdate, type AdjustmentParamsMap, type Annotation, type AnnotationLayer, type AnnotationPlacement, type AnnotationType, type ArrowAnnotation, type AspectRatio, BACKGROUND_LAYER_ID, BACKGROUND_LAYER_NAME, BLUR_FILTER_ID, BRUSH_OPTION_CONTROLS, type BaseAnnotation, type BlackWhiteParams, BlendMode, type BlurFilter, BrushSettings, type Chromaticity, type CircleAnnotation, type ColorBalanceParams, type ColorBalanceTone, type ColorDistance, type ColorRangeOptions, type ColorRangeSample, CompositorOptions, type CompositorSources, 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, DEVELOP_FILTER_ID, type DepthMaskOptions, type DeserializeContext, type DevelopFilter, type DevelopSettings, type DropZone, EMPTY_DISTANCE, type ExportOptions, type FillOptions, GUIDED_FILTER_EPS, type GestureModifiers, type GroupLayer, HISTOGRAM_BINS, HUE_RANGE_LABELS, type HistogramChannel, type HistoryEntryHandle, 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 ImageEditorFit, type ImageEditorOptions, ImageEditorRenderer, type ImageEditorState, type ImageEditorTool, type ImageEditorToolProviderOptions, type ImageHistogram, type ImageLayer, type ImageLayerType, type ImagePoint, type ImageProcessVersion, type ImageProjection, type ImageTransform, type InpaintHook, type InpaintOptions, type InvertParams, LATEST_PROCESS_VERSION, LAYERED_SCHEMA_VERSION, LEGACY_PROCESS_VERSION, LUMA_709, type LayerBase, type LayerBlendMode, LayerCompositor, type LayerFilter, type LayerFilterKind, type LayerLocation, LayerLocks, type LayerMaskProps, type LayerMenuAction, type LayerMenuItem, LayerOperationError, type LayerPanelRow, type LayerPlacement, type LayerProperties, type LayerSourcesHost, type LayerStack, type LayerTarget, type LegacyParts, type LegacySerializedImageEditorState, type LegacyViewResult, type LevelsChannel, type LevelsParams, type LineAnnotation, MAX_KELVIN, MIN_KELVIN, MIRED_PER_TEMPERATURE_UNIT, type MagicWandOptions, type Matrix3, type MosaicImageDataLike, type MosaicRegion, PAINT_TOOLS, PaintGesture, type PaintOptions, type PaintPointerSample, type PaintStrokeResult, PaintStrokeSession, type PaintTool, type PenAnnotation, type PhotoFilterParams, type PixelBuffer, type PixelLayer, type PixelLayerInit, type PixelOp, PixelSurface, type PosterizeParams, type QuickMaskStyle, REFINE_EDGE_CONTROLS, type RasterMask, type RectAnnotation, type RefineEdgeControl, type RefineEdgeParams, type RemoveBackgroundHook, type RemoveBackgroundOptions, type RenderOptions, type RouteInput, 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 SerializeContext, type SerializedAdjustmentLayer, type SerializedAnnotationLayer, type SerializedGroupLayer, type SerializedImageEditorState, type SerializedLayer, type SerializedLayeredImageEditorState, type SerializedPixelLayer, type SerializedRasterMask, type SerializedSelection, type ShapeSelectionOptions, type ShortcutEvent, StrokeApply, StrokeCoverage, type StrokeInit, StrokePoint, TINT_SCALE, TONE_LUT_SIZE, TONE_RANGE_PRESETS, type TextAnnotation, type ThresholdParams, TiledSurface, type ToneRangePreset, type UnitLevels, VIBRANCE_GREY, type VibranceParams, type ViewportMetrics, activeAdjustmentLayers, addLayerFilter, addToHistogram, adjustmentKindLabel, adjustmentLayersKey, adjustmentNodeAsLayer, adjustmentNodeFromLegacy, annotationLayerFor, annotationLayerName, applyAdjustmentLayers, applyAdjustments, applyBoxBlur, applyDepthMask, applyImageProjectionToContext, applyLegacyAdjustments, applyMatrix3, applyOutputStage, applyProcess2Adjustments, applyRegionBlur, applyRegionMosaic, backgroundLayer, baseProjection, blackWhiteGray, blurFilter, borderCoverage, boxMean, boxToCurvePoint, bradfordAdaptation, buildLayerMaskPlanes, buildToneLut, calculateCropDrag, canvasToImagePoint, clampControlValue, clampCropToImage, colorBalanceChannel, colorRange, combineSelections, compileAdjustmentLayer, computeHistogram, computeSelectionBounds, contractCoverage, controlPosition, controlTrackBackground, coverageToByte, coveringRect, createAdjustmentLayer, createImageCaptureSurface, createImageEditTools, createImageEditorToolProvider, createImageLayerTools, createImagePaintTools, createImageSelectionTools, createSelectionMask, curveLut, curveLutFromLevels, curvePointToBox, curveSvgPath, decodeLayerMask, decodePngDataUrl, decodeSelectionRle, defaultAdjustmentParams, depthMaskAlpha, depthRasterMask, describeLayer, describeSelection, deserializeLayer, deserializeLayers, deserializeSelection, developFilter, developFromAdjustments, developTarget, distanceTransform, dropPlacement, dropZone, duplicateLayer, edgeWidth, ellipsePoints, ellipseSelection, emptyHistogram, encodeSelectionRle, encodeSurface, evaluateAdjustmentLayers, expandCoverage, featherCoverage, findAdjustmentControl, findLayerControl, formatControlValue, fullSelection, getAnnotationBounds, getControlPath, getCropCursor, getRotatedSize, getViewportMetrics, getViewportProjection, globalImageCache, greyMorphology, groupLayers, guidePlanes, guidedFilterColor, handlePaintShortcut, hasResampledLegacyMask, hashMaskContent, hexToRgb, histogramPath, hitTestAnnotation, hitTestCrop, hitTestCurvePoint, hslToRgb, hueRange, hueRangeTables, hueRangeWeight, hueSaturation, identityCurve, identityLevels, imageEditorStateMigrations, imageToCanvasPoint, insertCurvePoint, invertMatrix3, invertSelection, isActiveFilter, isAdjustmentKind, isDefaultDepthMask, isLegacyShape, isPaintTool, isQuarterTurn, isQuarterTurnSwapped, isSelectionEmpty, isSelectionMode, isSpatialFilter, kelvinToTemperature, layerBadge, layerLabel, layerMaskCoverage, layerMaskFromSelection, layerMaskKey, layerMenu, layerPanelRows, layerTypeLabel, layersFromLegacy, legacyAdjustmentLayer, legacyMaskOf, legacyView, levelsValue, linearSrgbToXy, linearToSrgb, loadImageEditorDocument, magicWand, mapCropHandle, maskSummary, migrateSerializedImageEditorState, migrateToLayeredState, modifySelection, moveCurvePoint, moveLayer, mulMatrix3, needsLegacyBase, neutralHueRange, newLayerId, normalizeAdjustmentLayer, normalizeAdjustmentLayers, normalizeAngle, normalizeFilter, normalizeLayerMask, normalizeProcessVersion, normalizeRect, normalizeRefineEdgeParams, normalizeStoredAdjustments, offsetLayer, parseBlend, parseColor, parseSelectionMode, photoFilterMatrix, pixelLayerBounds, pixelLayers, placeLayer, pointerPressure, polygonCoverage, polygonSelection, posterizeValue, projectImagePoint, projectImageRect, projectMaskCoverage, projectQuarterTurn, quickMaskPixels, rangeLightness, rasterMaskFromLegacy, readAdjustmentControls, rectSelection, refineCoverage, refineEdgeHalo, refineSelection, removeAlpha, removeCurvePoint, removeLayer, removeLayerFilter, renderLayeredBase, requireLayer, requireUnlocked, resizeSelection, resolveMosaicRegionBounds, rgbToGray, rgbToHsl, runLayerMenuAction, sampleLut, sampleToneLut, selectionArea, selectionFromCoverage, selectionFromPixels, selectionModeFromModifiers, selectionOutline, selectionToCoverage, selectionToPixels, selectionValueAt, serializeLayer, serializeLayers, serializeSelection, setControlPath, setLayerMask, setLayerProperties, shiftCoverage, smoothCoverage, splitOverlayAnnotations, srgb8ToLab, srgbToLinear, sumHistograms, tempTintToXy, temperatureToKelvin, toHex, toneCurve, toneLuts, toneRange, ungroupLayer, unionRect, unprojectCanvasPoint, updateLayerFilter, updateLayerMaskProps, uvToXy, vibranceLinear, vibrancePixel, wbMatrix, whiteBalanceFromSample, whiteBalanceMatrix, withNewIds, xyToTempTint, xyToUv };