@pixerate/editor 0.22.0 → 0.24.0

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

@@ -1,3 +1,55 @@
+import { b as LoadReport, J as JsonObject, f as MigrationStep } from '../migrate-iTlm3a8h.cjs';
+import { A as AgentToolProvider } from '../registry-DnzpgY27.cjs';
+import '../schema-DYDGdYL9.cjs';
+
+/**
+ * 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;
+
 interface ImageDimensions {
     width: number;
     height: number;
@@ -24,9 +76,150 @@ interface ImageAdjustments {
     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;
 }
+/** 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;
@@ -43,6 +236,8 @@ interface BaseAnnotation {
     y: number;
     rotation?: number;
     opacity?: number;
+    /** Blend mode the annotation is drawn with (default `normal`). */
+    blend?: BlendMode;
 }
 interface PenAnnotation extends BaseAnnotation {
     type: 'pen';
@@ -113,7 +308,11 @@ interface ImageEditorState {
     isOriginalCompared: boolean;
 }
 interface SerializedImageEditorState {
-    version: 1;
+    /**
+     * Schema version. `2` adds `adjustments.layers`; states without layers are still written as
+     * `1` so they round-trip unchanged. See `migrateSerializedImageEditorState`.
+     */
+    version: 1 | 2;
     crop: CropBox | null;
     transform: ImageTransform;
     adjustments: ImageAdjustments;
@@ -150,10 +349,27 @@ interface ImageEditorAIHooks {
 }
 
 /**
- * Applies color and tone adjustments (brightness, contrast, saturation, exposure, temperature, opacity, blur)
- * directly to the pixel data of an ImageData buffer.
+ * 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): 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.
@@ -165,6 +381,157 @@ declare function applyDepthMask(mainImageData: ImageData, maskImageData: ImageDa
  */
 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;
+
+/** 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;
@@ -192,6 +559,13 @@ declare class ImageEditorRenderer {
     imageCache: ImageCache;
     private cachedBaseCanvas;
     private cachedBaseKey;
+    /**
+     * Histogram of the last viewport base render (after adjustments and layers, before
+     * annotations); `null` until a render with pixel access has happened.
+     */
+    previewHistogram: ImageHistogram | null;
+    /** Called whenever the viewport base image is re-rendered with the new histogram. */
+    onPreviewHistogram?: (histogram: ImageHistogram | null) => void;
     private sourceIds;
     private nextSourceId;
     /**
@@ -212,6 +586,14 @@ declare class ImageEditorRenderer {
      * Draws an individual annotation onto the canvas.
      */
     drawAnnotation(ctx: CanvasRenderingContext2D, ann: Annotation): Promise<void>;
+    /**
+     * Scalar fallback for blend modes the canvas cannot composite (Photoshop soft light, linear /
+     * vivid / pin light, hard mix, subtract, divide, darker / lighter colour, linear burn / dodge):
+     * draws the annotation on a same-size layer with the same transform, blends it into a copy of
+     * the target's pixels with `blendImageData`, and copies the result back inside the current clip.
+     */
+    private drawAnnotationBlended;
+    private drawAnnotationContent;
     /**
      * Draws selection box around active annotation.
      */
@@ -245,7 +627,35 @@ declare class ImageEditorRenderer {
     private drawAnnotationMask;
 }
 
+/** Latest serialized schema version (`2`: adjustment layers). */
+declare const IMAGE_EDITOR_SCHEMA_VERSION: 2;
+/** Changes to an adjustment layer; `params` is merged into the current parameters. */
+interface AdjustmentLayerUpdate<K extends AdjustmentKind = AdjustmentKind> {
+    params?: Partial<AdjustmentParamsMap[K]>;
+    enabled?: boolean;
+    opacity?: number;
+    blend?: BlendMode;
+    name?: string;
+}
+/** A new adjustment layer: its kind plus optional initial values. */
+interface AdjustmentLayerInit<K extends AdjustmentKind = AdjustmentKind> extends AdjustmentLayerUpdate<K> {
+    kind: K;
+    id?: string;
+}
 declare const DEFAULT_ADJUSTMENTS: ImageAdjustments;
+/**
+ * Fills in defaults for stored adjustments. A stored object without `process` was saved before
+ * process versions existed and keeps the legacy rendering.
+ */
+declare function normalizeStoredAdjustments(stored: Partial<ImageAdjustments> | undefined | null): ImageAdjustments;
+/**
+ * Brings a stored editor state of any schema version to the current shape. Version 1 (and a
+ * missing version) has no adjustment layers; everything else is unchanged, so old states load
+ * and render exactly as before.
+ */
+declare function migrateSerializedImageEditorState(data: Partial<SerializedImageEditorState> & {
+    version?: number;
+}): SerializedImageEditorState;
 declare const DEFAULT_TRANSFORM: ImageTransform;
 declare const DEFAULT_DEPTH_MASK: DepthMaskOptions;
 /**
@@ -257,6 +667,7 @@ declare class ImageEditorController {
     private renderer;
     private imageElement;
     private listeners;
+    private histogramListeners;
     private onStateChange?;
     private undoStack;
     private redoStack;
@@ -292,7 +703,45 @@ declare class ImageEditorController {
     flipHorizontal(): void;
     flipVertical(): void;
     setAdjustments(partial: Partial<ImageAdjustments>, commitToHistory?: boolean): void;
+    /** True when the adjustments use an older rendering process than {@link LATEST_PROCESS_VERSION}. */
+    get isProcessOutdated(): boolean;
+    /**
+     * Update to Current Process: re-interprets the current adjustment values with the latest
+     * rendering process (one undo step). Returns false when already current.
+     */
+    upgradeProcess(): boolean;
+    /** Resets the base sliders (latest process). Adjustment layers are kept; see `clearAdjustmentLayers`. */
     resetAdjustments(): void;
+    /** The adjustment layers, bottom (first) to top (last). */
+    getAdjustmentLayers(): AdjustmentLayer[];
+    getAdjustmentLayer(id: string): AdjustmentLayer | undefined;
+    private setLayers;
+    /**
+     * Adds an adjustment layer on top (or at `index`, 0 = bottom) as one undo step and returns
+     * its id. `kind` alone gives neutral parameters.
+     */
+    addAdjustmentLayer<K extends AdjustmentKind>(init: K | AdjustmentLayerInit<K>, index?: number): string;
+    /**
+     * Updates a layer (`params` merged into the current ones, then normalised). Pass
+     * `commitToHistory = false` for the moves of a drag after recording its start once.
+     * Returns false for an unknown id.
+     */
+    updateAdjustmentLayer(id: string, update: AdjustmentLayerUpdate, commitToHistory?: boolean): boolean;
+    /** Removes a layer as one undo step. Returns false for an unknown id. */
+    removeAdjustmentLayer(id: string): boolean;
+    /** Moves a layer to `toIndex` (0 = bottom) as one undo step. Returns false if nothing moved. */
+    moveAdjustmentLayer(id: string, toIndex: number): boolean;
+    /** Shows or hides a layer (flips it without `enabled`) as one undo step. */
+    toggleAdjustmentLayer(id: string, enabled?: boolean): boolean;
+    /** Removes every adjustment layer as one undo step. */
+    clearAdjustmentLayers(): void;
+    /**
+     * Histogram of the last rendered preview (after adjustments and layers, before annotations),
+     * or `null` before the first render or without canvas pixel access.
+     */
+    getHistogram(): ImageHistogram | null;
+    /** Calls `listener` now and whenever a render produces a new preview histogram. */
+    subscribeHistogram(listener: (histogram: ImageHistogram | null) => void): () => void;
     setDepthMask(partial: Partial<DepthMaskOptions>): void;
     resetDepthMask(): void;
     addAnnotation(annotation: CreateAnnotationPayload): string;
@@ -465,4 +914,293 @@ declare function getAnnotationBounds(ann: Annotation): {
  */
 declare function hitTestAnnotation(imgPt: ImagePoint, ann: Annotation, padding?: number): boolean;
 
-export { type Annotation, type AnnotationType, type ArrowAnnotation, type AspectRatio, type BaseAnnotation, type CircleAnnotation, type CreateAnnotationPayload, type CropBox, type CropHandle, DEFAULT_ADJUSTMENTS, DEFAULT_DEPTH_MASK, DEFAULT_TRANSFORM, type DepthMaskOptions, type ExportOptions, type ImageAdjustments, type ImageAnnotation, type ImageDimensions, type ImageEditorAIHooks, ImageEditorController, type ImageEditorOptions, ImageEditorRenderer, type ImageEditorState, type ImageEditorTool, type ImagePoint, type ImageProjection, type ImageTransform, type InpaintHook, type InpaintOptions, type LineAnnotation, type PenAnnotation, type RectAnnotation, type RemoveBackgroundHook, type RemoveBackgroundOptions, type RenderOptions, type SerializedImageEditorState, type TextAnnotation, type ViewportMetrics, applyAdjustments, applyDepthMask, applyImageProjectionToContext, calculateCropDrag, canvasToImagePoint, clampCropToImage, getAnnotationBounds, getCropCursor, getRotatedSize, getViewportMetrics, getViewportProjection, globalImageCache, hitTestAnnotation, hitTestCrop, imageToCanvasPoint, isQuarterTurnSwapped, mapCropHandle, normalizeAngle, projectImagePoint, projectImageRect, removeAlpha, unprojectCanvasPoint };
+/** The `version` that `ImageEditorController.toJSON()` writes. */
+declare const IMAGE_EDITOR_STATE_VERSION = 1;
+/**
+ * Migration steps for `SerializedImageEditorState`, keyed by the version they
+ * start from. Empty while only version 1 exists.
+ */
+declare const imageEditorStateMigrations: Record<number, MigrationStep>;
+interface ImageEditorDocumentLoad {
+    /** State to pass to `loadJSON` / `initialState`. */
+    state: SerializedImageEditorState;
+    report: LoadReport;
+    /** Top-level keys this build does not know; spread them into the saved JSON to keep them. */
+    unknown: JsonObject;
+}
+/**
+ * Loads stored image editor state (a JSON string or object) with a `LoadReport`:
+ *
+ * - Runs `imageEditorStateMigrations` up to `IMAGE_EDITOR_STATE_VERSION`; a missing
+ *   `version` is taken as current.
+ * - A newer `version` is still loaded but reported `readOnly`: do not save over it.
+ * - Each section (`crop`, `transform`, `adjustments`, `depthMask`, `annotations`)
+ *   falls back to its default on its own; invalid annotations are dropped one by one.
+ * - Unknown top-level keys are returned in `unknown`.
+ *
+ * Valid state from `toJSON()` comes back unchanged, so `loadJSON(state)` behaves
+ * exactly as with the raw object.
+ */
+declare function loadImageEditorDocument(input: unknown): ImageEditorDocumentLoad;
+
+/**
+ * Adjustment layers: Photoshop-matching evaluation on encoded sRGB colours in 0..1.
+ *
+ * Every layer is compiled once per parameter change into a per-pixel function (per-channel kinds
+ * into three 4096-entry LUTs); {@link applyAdjustmentLayers} runs the stack on an ImageData.
+ */
+type Rgb = [number, number, number];
+/** Entries in a tone LUT (curves, levels, colour balance). */
+declare const ADJUSTMENT_LUT_SIZE = 4096;
+/** Linear interpolation into a 0..1-domain LUT. */
+declare function sampleLut(table: ArrayLike<number>, v: number): number;
+interface AdjustmentKindInfo {
+    kind: AdjustmentKind;
+    label: string;
+}
+declare const ADJUSTMENT_KINDS: readonly AdjustmentKindInfo[];
+declare function isAdjustmentKind(value: unknown): value is AdjustmentKind;
+declare function adjustmentKindLabel(kind: AdjustmentKind): string;
+declare const HUE_RANGE_LABELS: readonly ["Reds", "Yellows", "Greens", "Cyans", "Blues", "Magentas"];
+/** The neutral range `i` (0 reds … 5 magentas): fully on for 30° around its centre, fading over 30° each side. */
+declare function neutralHueRange(i: number): HueRange;
+declare const identityCurve: () => CurvePoint[];
+declare const identityLevels: () => LevelsChannel;
+/** Neutral parameters of every kind (fresh objects on every call). */
+declare function defaultAdjustmentParams<K extends AdjustmentKind>(kind: K): AdjustmentParamsMap[K];
+/** A new layer of `kind` with neutral (or the given) parameters, enabled, opacity 1, normal blend. */
+declare function createAdjustmentLayer<K extends AdjustmentKind>(kind: K, options?: {
+    id?: string;
+    name?: string;
+    params?: Partial<AdjustmentParamsMap[K]>;
+    enabled?: boolean;
+    opacity?: number;
+    blend?: BlendMode;
+}): AdjustmentLayerOf<K>;
+/**
+ * A clean, deep-copied layer from stored or hand-written data: missing fields get neutral
+ * defaults, numbers are clamped to their ranges. `null` for an unknown kind.
+ */
+declare function normalizeAdjustmentLayer(raw: unknown): AdjustmentLayer | null;
+/** Normalises a stored layer list (drops unknown kinds, de-duplicates ids). */
+declare function normalizeAdjustmentLayers(raw: unknown): AdjustmentLayer[];
+/**
+ * Photoshop curve: a natural cubic spline through the points (0..1 in and out; it may overshoot
+ * between points, as Photoshop's does), constant outside the first / last point, clamped to
+ * 0..1, sampled into a LUT. Fewer than two distinct points: the identity.
+ */
+declare function curveLut(points: ReadonlyArray<{
+    input: number;
+    output: number;
+}>, size?: number): Float32Array;
+/** {@link curveLut} for Curves points in levels (0..255). */
+declare function curveLutFromLevels(points: readonly CurvePoint[]): Float32Array;
+/** A Levels record with values in 0..1 (as `levelsValue` takes them). */
+interface UnitLevels {
+    inBlack: number;
+    inWhite: number;
+    gamma: number;
+    outBlack: number;
+    outWhite: number;
+}
+/**
+ * One Levels record on `v` (0..1). With `quantum` (8-bit: 255) Photoshop works on whole levels:
+ * the input is a level and the stretch is rounded (half up) before the gamma. A gamma above 1 has
+ * Photoshop's soft shadow toe: a p-norm soft-min of the power curve and a line of slope ≈ 2^gamma.
+ */
+declare function levelsValue(ch: UnitLevels, v: number, quantum?: number): number;
+/** RGB (0..1) → HSL with hue in turns (0..1). */
+declare function rgbToHsl(c: readonly number[]): [number, number, number];
+declare function hslToRgb(h: number, s: number, l: number): Rgb;
+/** How much a pixel of hue `deg` belongs to `range` (0..1): a trapezoid that may wrap past 0/360. */
+declare function hueRangeWeight(range: Pick<HueRange, 'bounds'>, deg: number): number;
+/** Range edits as three hue-indexed tables (hue shift in degrees, saturation and lightness as fractions). */
+declare function hueRangeTables(ranges: readonly HueRange[]): [Float32Array, Float32Array, Float32Array];
+/**
+ * One Hue/Saturation evaluation: hue shift in degrees, saturation and lightness in -1..1.
+ * Lightness first, then hue and saturation (raising divides by 1 − s, lowering multiplies by
+ * 1 + s). Colorize sets hue and saturation at the lightened lightness.
+ */
+declare function hueSaturation(c: readonly number[], hue: number, s: number, l: number, colorize: boolean): Rgb;
+/** A colour range's Lightness: towards the brightest channel when raised, the darkest when lowered. */
+declare function rangeLightness(c: readonly number[], l: number): Rgb;
+/** Grey Vibrance › Saturation desaturates to (linear light; blue has no weight). */
+declare const VIBRANCE_GREY: readonly [number, number];
+/** The Vibrance slider (`v` in -1..1) on a linear-light pixel: an HSV change that keeps the hue. */
+declare function vibranceLinear(c: Rgb, v: number): Rgb;
+/** Photoshop's Vibrance on one encoded sRGB pixel (`v`, `s`: the sliders / 100). */
+declare function vibrancePixel(c: readonly number[], v: number, s: number): Rgb;
+/**
+ * Color Balance on channel `ch` (0 red, 1 green, 2 blue) of `v` (0..1); `tones` are the
+ * shadows, midtones and highlights slider triples (-100..100). Highlights, shadows, then midtones.
+ */
+declare function colorBalanceChannel(tones: readonly [readonly number[], readonly number[], readonly number[]], preserveLuminosity: boolean, ch: number, v: number): number;
+/**
+ * Black & White grey: the smallest channel, plus the secondary part (middle − smallest) and the
+ * primary part (largest − middle) weighted by the sliders (percent: reds, yellows, greens, cyans,
+ * blues, magentas).
+ */
+declare function blackWhiteGray(c: readonly number[], weights: readonly number[]): number;
+/**
+ * Photo Filter's linear-light RGB matrix (row-major 3×3): the pixel's D50 XYZ, relative to white,
+ * multiplied by the filter colour's mixed in by `density` (0..1). `normalizeY` keeps luminance Y.
+ */
+declare function photoFilterMatrix(color: readonly number[], density: number, normalizeY?: boolean): number[][];
+/** Photoshop posterize: `levels` equal input bins over 0..255, outputs `floor(k·255 / (levels − 1))`. */
+declare function posterizeValue(v: number, levels: number): number;
+/** Rec.601 luma (Photoshop's grey for Threshold). */
+declare const rgbToGray: (c: readonly number[]) => number;
+/** `#rrggbb` → 0..1 RGB (black for anything else). */
+declare function hexToRgb(hex: string): Rgb;
+/** Mutates an encoded sRGB colour (0..1) in place. */
+type PixelOp = (c: Rgb) => void;
+/**
+ * Per-channel LUTs of a Curves or Levels layer: each channel's record first, then the master.
+ * `null` for any other kind.
+ */
+declare function toneLuts(layer: AdjustmentLayer): [Float32Array, Float32Array, Float32Array] | null;
+/**
+ * Compiles a layer into a pixel function, or `null` when it is the identity (neutral parameters).
+ * Pure: depends on `kind` and `params` only.
+ */
+declare function compileAdjustmentLayer(layer: AdjustmentLayer): PixelOp | null;
+/** Layers that change pixels: enabled, visible, not the identity. */
+declare function activeAdjustmentLayers(layers: readonly AdjustmentLayer[] | undefined): AdjustmentLayer[];
+/**
+ * Evaluates one colour (encoded sRGB, 0..1) through a layer stack: each layer adjusts the result
+ * of the layers below and is blended over it with its blend mode and opacity (an opaque
+ * backdrop, so `(1 − α)·Cb + α·B(Cb, Cs)`).
+ */
+declare function evaluateAdjustmentLayers(color: readonly number[], layers: readonly AdjustmentLayer[]): Rgb;
+/**
+ * Applies an adjustment-layer stack to 8-bit straight RGBA pixels in place. Each pixel is
+ * decoded once, run through every layer in float, and encoded once. Transparent pixels are
+ * left alone; alpha is never changed.
+ */
+declare function applyAdjustmentLayers(imageData: ImageData, layers: readonly AdjustmentLayer[] | undefined): void;
+/** Stable cache key of a layer stack's pixel effect (for renderer caches). */
+declare function adjustmentLayersKey(layers: readonly AdjustmentLayer[] | undefined): string;
+
+/**
+ * Control specs: one table describes every numeric adjustment slider (id, label, section, range,
+ * default, step, display precision and track style). The React and Svelte panels render from it,
+ * the agent tools expose it as a schema, and values are addressed by id.
+ */
+type ControlSection = 'light' | 'color' | 'effects' | 'layer';
+/** How a slider track is drawn. */
+type ControlTrack = 
+/** Plain track, fill from the minimum. */
+{
+    kind: 'plain';
+}
+/** Zero in the middle. */
+ | {
+    kind: 'centered';
+}
+/** Blue → yellow (white-balance temperature). */
+ | {
+    kind: 'temp';
+}
+/** Green → magenta (tint). */
+ | {
+    kind: 'tint';
+}
+/** A two-colour gradient. */
+ | {
+    kind: 'gradient';
+    from: string;
+    to: string;
+}
+/** Full hue rainbow. */
+ | {
+    kind: 'rainbow';
+};
+interface ControlSpec {
+    /** Dotted path of the value (`exposure`; inside a layer's params: `midtones.0`, `ranges.4.hue`). */
+    id: string;
+    label: string;
+    section: ControlSection;
+    min: number;
+    max: number;
+    step: number;
+    default: number;
+    /** Decimal places shown (after `displayScale`). */
+    decimals: number;
+    track: ControlTrack;
+    /** Multiplier for display (opacity 0..1 shows as 0..100 %). */
+    displayScale?: number;
+    /** Unit suffix for display (`px`, `%`, `°`). */
+    unit?: string;
+    /** The rendering process the control needs (tint: process 2). */
+    requiresProcess?: 1 | 2;
+}
+/** Every numeric base adjustment, in panel order. */
+declare const IMAGE_ADJUSTMENT_CONTROLS: readonly ControlSpec[];
+/**
+ * Numeric parameters of each adjustment-layer kind, addressed inside `layer.params`. Curves points
+ * and booleans / colours (colorize, preserve luminosity, tint, filter colour) are edited by the
+ * dedicated controls, not sliders.
+ */
+declare const ADJUSTMENT_LAYER_CONTROLS: Readonly<Record<AdjustmentKind, readonly ControlSpec[]>>;
+/** Opacity of any adjustment layer (0..1, shown as %). */
+declare const ADJUSTMENT_LAYER_OPACITY_CONTROL: ControlSpec;
+/** The base-adjustment control with this id. */
+declare function findAdjustmentControl(id: string): ControlSpec | undefined;
+/** The control of a layer parameter (`opacity` included). */
+declare function findLayerControl(kind: AdjustmentKind, id: string): ControlSpec | undefined;
+/** `v` clamped to the control's range and snapped to its step; non-finite values give the default. */
+declare function clampControlValue(spec: ControlSpec, v: unknown): number;
+/** A value as the slider shows it (`+12`, `35%`, `4px`). */
+declare function formatControlValue(spec: ControlSpec, v: number): string;
+/** Where `v` sits on the track, 0 (left) to 1 (right). */
+declare function controlPosition(spec: ControlSpec, v: number): number;
+/** CSS background for a control's track. */
+declare function controlTrackBackground(spec: ControlSpec): string | undefined;
+/** Reads a dotted path (`ranges.2.hue`) from an object. */
+declare function getControlPath(obj: unknown, path: string): unknown;
+/** A copy of `obj` with the dotted path set (arrays and objects along the path are cloned). */
+declare function setControlPath<T>(obj: T, path: string, value: unknown): T;
+/** The base adjustment values the control table describes. */
+declare function readAdjustmentControls(adjustments: ImageAdjustments): Record<string, number>;
+
+interface ImageEditorToolProviderOptions {
+    /** Provider id (unique per registry). Default `image-editor`. */
+    id?: string;
+    /** Always prefix tool names with `<namespace>__`. */
+    namespace?: string;
+}
+/**
+ * Agent tools for an image editor, for a `ToolRegistry`:
+ *
+ * - `get_adjustments`: base slider values (by control id), process version and adjustment layers.
+ * - `list_controls`: the control table (ids, ranges, defaults, steps), layer kinds and blend modes.
+ * - `set_adjustments {values, label}`: sets base controls (`exposure`) and layer parameters
+ *   (`layers.<id>.vibrance`, `layers.<id>.opacity`) in one undo step; values are clamped to the
+ *   control ranges and the applied values are echoed.
+ * - `add_adjustment_layer {kind, params?, opacity?, blend?, name?}`.
+ * - `render_preview {maxSide}`: the rendered image as a PNG, longest side at most `maxSide`.
+ */
+declare function createImageEditorToolProvider(controller: ImageEditorController, options?: ImageEditorToolProviderOptions): AgentToolProvider;
+
+/** Box coordinates of a curve point. */
+declare function curvePointToBox(p: CurvePoint, width: number, height: number): {
+    x: number;
+    y: number;
+};
+/** The curve point (whole levels, clamped) under box coordinates. */
+declare function boxToCurvePoint(x: number, y: number, width: number, height: number): CurvePoint;
+/** An SVG polyline path of the evaluated curve (spline, clamped, constant beyond the end points). */
+declare function curveSvgPath(points: readonly CurvePoint[], width: number, height: number, samples?: number): string;
+/** Index of the point within `radius` box units of (x, y), nearest first; -1 for none. */
+declare function hitTestCurvePoint(points: readonly CurvePoint[], x: number, y: number, width: number, height: number, radius?: number): number;
+/** Inserts a point in input order (replacing one at the same input). Returns the new list and its index. */
+declare function insertCurvePoint(points: readonly CurvePoint[], p: CurvePoint): {
+    points: CurvePoint[];
+    index: number;
+};
+/** Moves point `index`, keeping its input strictly between its neighbours'. */
+declare function moveCurvePoint(points: readonly CurvePoint[], index: number, p: CurvePoint): CurvePoint[];
+/** Removes point `index`; a curve keeps at least two points. */
+declare function removeCurvePoint(points: readonly CurvePoint[], index: number): CurvePoint[];
+
+export { ADJUSTMENT_KINDS, ADJUSTMENT_LAYER_CONTROLS, ADJUSTMENT_LAYER_OPACITY_CONTROL, ADJUSTMENT_LUT_SIZE, AS_SHOT_KELVIN, type AdjustmentKind, type AdjustmentKindInfo, type AdjustmentLayer, type AdjustmentLayerBase, type AdjustmentLayerInit, type AdjustmentLayerOf, type AdjustmentLayerUpdate, type AdjustmentParamsMap, type Annotation, type AnnotationType, type ArrowAnnotation, type AspectRatio, BLEND_MODES, type BaseAnnotation, type BlackWhiteParams, type BlendMode, type BlendModeInfo, type Chromaticity, type CircleAnnotation, type ColorBalanceParams, type ColorBalanceTone, type ControlSection, type ControlSpec, type ControlTrack, type CreateAnnotationPayload, type CropBox, type CropHandle, type CurvePoint, type CurvesParams, D65, DEFAULT_ADJUSTMENTS, DEFAULT_DEPTH_MASK, DEFAULT_TRANSFORM, type DepthMaskOptions, type ExportOptions, HISTOGRAM_BINS, HUE_RANGE_LABELS, type HistogramChannel, type HueRange, type HueSaturationParams, IDENTITY_MATRIX3, IMAGE_ADJUSTMENT_CONTROLS, IMAGE_EDITOR_SCHEMA_VERSION, IMAGE_EDITOR_STATE_VERSION, type ImageAdjustments, type ImageAnnotation, type ImageDimensions, type ImageEditorAIHooks, ImageEditorController, type ImageEditorDocumentLoad, type ImageEditorOptions, ImageEditorRenderer, type ImageEditorState, type ImageEditorTool, type ImageEditorToolProviderOptions, type ImageHistogram, type ImagePoint, type ImageProcessVersion, type ImageProjection, type ImageTransform, type InpaintHook, type InpaintOptions, type InvertParams, LATEST_PROCESS_VERSION, LEGACY_PROCESS_VERSION, LUMA_709, type LevelsChannel, type LevelsParams, type LineAnnotation, MAX_KELVIN, MIN_KELVIN, MIRED_PER_TEMPERATURE_UNIT, type Matrix3, type PenAnnotation, type PhotoFilterParams, type PixelOp, type PosterizeParams, type RectAnnotation, type RemoveBackgroundHook, type RemoveBackgroundOptions, type RenderOptions, type Rgb$1 as Rgb, type Rgba, type SerializedImageEditorState, TINT_SCALE, TONE_LUT_SIZE, type TextAnnotation, type ThresholdParams, type UnitLevels, VIBRANCE_GREY, type VibranceParams, type ViewportMetrics, activeAdjustmentLayers, adjustmentKindLabel, adjustmentLayersKey, applyAdjustmentLayers, applyAdjustments, applyDepthMask, applyImageProjectionToContext, applyLegacyAdjustments, applyMatrix3, applyProcess2Adjustments, blackWhiteGray, blendChannel, blendImageData, blendLum, blendPixel, blendRgb, boxToCurvePoint, bradfordAdaptation, buildToneLut, calculateCropDrag, canvasCompositeOperation, canvasToImagePoint, clampControlValue, clampCropToImage, colorBalanceChannel, compileAdjustmentLayer, computeHistogram, controlPosition, controlTrackBackground, createAdjustmentLayer, createImageEditorToolProvider, curveLut, curveLutFromLevels, curvePointToBox, curveSvgPath, defaultAdjustmentParams, evaluateAdjustmentLayers, findAdjustmentControl, findLayerControl, formatControlValue, getAnnotationBounds, getControlPath, getCropCursor, getRotatedSize, getViewportMetrics, getViewportProjection, globalImageCache, hexToRgb, histogramPath, hitTestAnnotation, hitTestCrop, hitTestCurvePoint, hslToRgb, hueRangeTables, hueRangeWeight, hueSaturation, identityCurve, identityLevels, imageEditorStateMigrations, imageToCanvasPoint, insertCurvePoint, invertMatrix3, isAdjustmentKind, isBlendMode, isQuarterTurnSwapped, isSeparableBlendMode, kelvinToTemperature, levelsValue, linearSrgbToXy, linearToSrgb, loadImageEditorDocument, mapCropHandle, migrateSerializedImageEditorState, moveCurvePoint, mulMatrix3, neutralHueRange, normalizeAdjustmentLayer, normalizeAdjustmentLayers, normalizeAngle, normalizeBlendMode, normalizeProcessVersion, normalizeStoredAdjustments, photoFilterMatrix, posterizeValue, projectImagePoint, projectImageRect, rangeLightness, readAdjustmentControls, removeAlpha, removeCurvePoint, rgbToGray, rgbToHsl, sampleLut, sampleToneLut, setControlPath, setLum, srgbToLinear, tempTintToXy, temperatureToKelvin, toneCurve, toneLuts, unprojectCanvasPoint, uvToXy, vibranceLinear, vibrancePixel, wbMatrix, whiteBalanceFromSample, whiteBalanceMatrix, xyToTempTint, xyToUv };