@pixerate/editor 0.102.0 → 0.104.0

package/dist/compositor-B1ZrKR89.d.ts

@@ -0,0 +1,835 @@
+import { B as BlendMode, R as RasterRect, a as TiledSurface, M as MaskSurface, P as PixelSurface, T as TileKey } from './surface-AfHCH7BR.js';
+import { H as Homography, V as Vec2 } from './types-CwMPoRMU.js';
+
+/**
+ * Layer effects (Photoshop's layer styles) as data: drop and inner shadows, outer and inner
+ * glows, bevel & emboss, satin, colour / gradient / pattern overlays and strokes. Rendering lives
+ * in `./render`, PSD mapping in the image editor's PSD module.
+ *
+ * Angles are in degrees, counter-clockwise from 3 o'clock, and give the direction the light
+ * comes *from* (Photoshop's convention). Sizes and distances are in pixels, opacities and
+ * percentages in 0..1, colours are `#rrggbb`.
+ */
+
+/** One point of a contour curve (input → output, both 0..1). */
+interface ContourPoint {
+    input: number;
+    output: number;
+    /** The curve bends sharply here instead of passing smoothly through (Photoshop's corner point). */
+    corner?: boolean;
+}
+/** A transfer curve applied to an effect's coverage. Missing on an effect = linear. */
+interface EffectContour {
+    name: string;
+    points: ContourPoint[];
+}
+type GradientStyle = 'linear' | 'radial' | 'angle' | 'reflected' | 'diamond';
+interface GradientColorStop {
+    /** 0..1 along the gradient. */
+    position: number;
+    color: string;
+}
+interface GradientOpacityStop {
+    position: number;
+    /** 0..1 */
+    opacity: number;
+}
+/** A gradient as overlays, gradient strokes and gradient glows paint it. */
+interface EffectGradient {
+    stops: GradientColorStop[];
+    /** Missing or empty: opaque. */
+    opacityStops?: GradientOpacityStop[];
+    style: GradientStyle;
+    /** Degrees (90 = bottom to top). */
+    angle: number;
+    /** 1 = 100 %. */
+    scale: number;
+    reverse: boolean;
+    /** Align with the layer's bounds (else the canvas). */
+    align: boolean;
+    /** Centre offset as a fraction of the bounds. */
+    offset: {
+        x: number;
+        y: number;
+    };
+}
+/** A pattern reference: the id of a document or built-in pattern (see `builtinPatternIds`). */
+interface EffectPatternRef {
+    patternId: string;
+    /** Display name (PSD keeps it beside the id). */
+    name?: string;
+    /** 1 = 100 %. */
+    scale: number;
+    /** Rotation in degrees (counter-clockwise). */
+    angle?: number;
+    /** Tile from the layer's top-left ("Link with Layer", default) instead of the canvas origin. */
+    link?: boolean;
+    /** Origin offset in pixels. */
+    phase?: {
+        x: number;
+        y: number;
+    };
+}
+/** What a stroke or glow paints with. */
+type EffectFill = {
+    type: 'color';
+    color: string;
+} | {
+    type: 'gradient';
+    gradient: EffectGradient;
+} | ({
+    type: 'pattern';
+} & EffectPatternRef);
+interface EffectBase {
+    /** Unique within the layer. */
+    id: string;
+    enabled: boolean;
+}
+interface Blended {
+    blend: BlendMode;
+    /** 0..1 */
+    opacity: number;
+}
+interface DropShadowEffect extends EffectBase, Blended {
+    kind: 'drop-shadow';
+    color: string;
+    angle: number;
+    useGlobalLight: boolean;
+    distance: number;
+    /** 0..1 of the size grown solid before the blur. */
+    spread: number;
+    size: number;
+    contour?: EffectContour;
+    antiAlias: boolean;
+    /** 0..1 */
+    noise: number;
+    /** The layer hides the shadow beneath its see-through fill ("Layer Knocks Out Drop Shadow"). */
+    knocksOut: boolean;
+}
+interface InnerShadowEffect extends EffectBase, Blended {
+    kind: 'inner-shadow';
+    color: string;
+    angle: number;
+    useGlobalLight: boolean;
+    distance: number;
+    /** 0..1 of the size shrunk solid before the blur. */
+    choke: number;
+    size: number;
+    contour?: EffectContour;
+    antiAlias: boolean;
+    noise: number;
+}
+type GlowTechnique = 'softer' | 'precise';
+interface OuterGlowEffect extends EffectBase, Blended {
+    kind: 'outer-glow';
+    /** Colour or gradient. */
+    fill: Extract<EffectFill, {
+        type: 'color' | 'gradient';
+    }>;
+    technique: GlowTechnique;
+    spread: number;
+    size: number;
+    contour?: EffectContour;
+    antiAlias: boolean;
+    /** 0..1 (default 0.5): the part of the glow the contour spans. */
+    range: number;
+    /** 0..1, varies a gradient glow's colours. Stored only (not rendered). */
+    jitter: number;
+    noise: number;
+}
+interface InnerGlowEffect extends EffectBase, Blended {
+    kind: 'inner-glow';
+    fill: Extract<EffectFill, {
+        type: 'color' | 'gradient';
+    }>;
+    technique: GlowTechnique;
+    choke: number;
+    size: number;
+    contour?: EffectContour;
+    antiAlias: boolean;
+    range: number;
+    jitter: number;
+    noise: number;
+    /** Glow from the edge inwards (default) or from the centre outwards. */
+    source: 'edge' | 'center';
+}
+type BevelStyle = 'inner-bevel' | 'outer-bevel' | 'emboss' | 'pillow-emboss' | 'stroke-emboss';
+type BevelTechnique = 'smooth' | 'chisel-hard' | 'chisel-soft';
+/** The Contour element of Bevel & Emboss: shapes the bevel's height profile. */
+interface BevelContour {
+    contour: EffectContour;
+    /** 0..1 (default 0.5). Stored only. */
+    range: number;
+    antiAlias: boolean;
+}
+/** The Texture element of Bevel & Emboss: a pattern's luminance added to the height. */
+interface BevelTexture extends EffectPatternRef {
+    /** -10..10 (1 = +100 %); negative carves the pattern in. */
+    depth: number;
+    invert: boolean;
+}
+interface BevelEmbossEffect extends EffectBase {
+    kind: 'bevel-emboss';
+    style: BevelStyle;
+    technique: BevelTechnique;
+    /** 0..10 (1 = 100 %). */
+    depth: number;
+    direction: 'up' | 'down';
+    size: number;
+    soften: number;
+    angle: number;
+    /** Light altitude in degrees (0..90). */
+    altitude: number;
+    useGlobalLight: boolean;
+    glossContour?: EffectContour;
+    highlightColor: string;
+    highlightBlend: BlendMode;
+    highlightOpacity: number;
+    shadowColor: string;
+    shadowBlend: BlendMode;
+    shadowOpacity: number;
+    /** Contour element (shapes the bevel's height profile), or missing when off. */
+    contourElement?: BevelContour;
+    /** Texture element, or missing when off. */
+    texture?: BevelTexture;
+}
+interface SatinEffect extends EffectBase, Blended {
+    kind: 'satin';
+    color: string;
+    angle: number;
+    distance: number;
+    size: number;
+    contour?: EffectContour;
+    antiAlias: boolean;
+    invert: boolean;
+}
+interface ColorOverlayEffect extends EffectBase, Blended {
+    kind: 'color-overlay';
+    color: string;
+}
+interface GradientOverlayEffect extends EffectBase, Blended {
+    kind: 'gradient-overlay';
+    gradient: EffectGradient;
+    dither: boolean;
+}
+interface PatternOverlayEffect extends EffectBase, Blended, EffectPatternRef {
+    kind: 'pattern-overlay';
+}
+type StrokePosition = 'outside' | 'inside' | 'center';
+interface StrokeEffect extends EffectBase, Blended {
+    kind: 'stroke';
+    size: number;
+    position: StrokePosition;
+    fill: EffectFill;
+}
+/** One layer effect. Several of the same kind are allowed; the first listed of a kind is on top. */
+type LayerEffect = DropShadowEffect | InnerShadowEffect | OuterGlowEffect | InnerGlowEffect | BevelEmbossEffect | SatinEffect | ColorOverlayEffect | GradientOverlayEffect | PatternOverlayEffect | StrokeEffect;
+type LayerEffectKind = LayerEffect['kind'];
+/** A layer's effects: the master switch, Layer Style › Scale Effects and the effect list. */
+interface LayerEffects {
+    /** The master switch ("effects on"); `false` keeps the effects but renders none. */
+    enabled: boolean;
+    /** Scale Effects: multiplies every size, distance and pattern scale (1 = 100 %; missing = 1). */
+    scale?: number;
+    items: LayerEffect[];
+    /**
+     * The PSD block the effects were read from (`lfx2`, `lfxs` or `lmfx`), kept so export writes it
+     * back verbatim while the effects still map to the same values. Export regenerates it otherwise.
+     */
+    psd?: {
+        key: string;
+        data: Uint8Array;
+    };
+}
+/** The document-wide light that effects with `useGlobalLight` use. */
+interface GlobalLight {
+    /** Degrees. */
+    angle: number;
+    /** Degrees. */
+    altitude: number;
+}
+declare const DEFAULT_GLOBAL_LIGHT: GlobalLight;
+/** Every effect kind, in the order the Layer Style dialog lists them. */
+declare const LAYER_EFFECT_KINDS: readonly LayerEffectKind[];
+declare function layerEffectLabel(kind: LayerEffectKind): string;
+declare function isLayerEffectKind(value: unknown): value is LayerEffectKind;
+/** Photoshop's default black-to-white linear gradient. */
+declare function defaultEffectGradient(): EffectGradient;
+/** A fresh effect id. */
+declare function newEffectId(): string;
+/** An effect of `kind` with Photoshop's default settings. */
+declare function defaultLayerEffect(kind: LayerEffectKind, id?: string): LayerEffect;
+/** True when the master switch is on and at least one effect is enabled. */
+declare function hasActiveEffects(effects: LayerEffects | undefined | null): effects is LayerEffects;
+/** Maximum distance (px) an effect is rendered from the layer's shape. */
+declare const MAX_EFFECT_REACH = 512;
+/** How far (px, before Scale Effects) one effect paints beyond or into the layer's shape. */
+declare function effectReach(e: LayerEffect): number;
+/**
+ * Pixels an effect stack can reach beyond the layer's shape (its enabled effects, scaled), plus
+ * a little slack. 0 when no effect is active. Dirty areas and tile signatures grow by this.
+ */
+declare function effectsMargin(effects: LayerEffects | undefined | null): number;
+/** Scale Effects as a usable factor (missing or invalid = 1). */
+declare function effectsScale(effects: Pick<LayerEffects, 'scale'>): number;
+/** `effect` with its sizes, distances and pattern scales multiplied by `s` (Scale Effects). */
+declare function scaleLayerEffect<E extends LayerEffect>(e: E, s: number): E;
+/** `#rrggbb` (or `#rgb`, `rrggbb`) as 0..1 RGB, or `null`. */
+declare function parseEffectColor(value: unknown): [number, number, number] | null;
+/** 0..1 RGB as `#rrggbb`. */
+declare function effectColorHex(rgb: readonly number[]): string;
+declare class LayerEffectError extends Error {
+    constructor(message: string);
+}
+declare function validateEffectGradient(v: unknown, path: string): void;
+/** Every field an effect of `kind` has (required and optional), including `id` and `kind`. */
+declare function layerEffectFields(kind: LayerEffectKind): string[];
+/**
+ * Checks a complete effect (every field of its kind present and in range). Throws a
+ * {@link LayerEffectError} naming the first wrong field and how to fix it.
+ */
+declare function validateLayerEffect(v: unknown, path?: string): asserts v is LayerEffect;
+/**
+ * Applies `changes` to `effect` and validates the result. `kind` and `id` cannot change. Nested
+ * objects (`fill`, `gradient`, `contour`, `texture`, `phase`, `offset`) are replaced whole; `null`
+ * removes an optional one (`contour`, `glossContour`, bevel `contour` / `texture`).
+ */
+declare function mergeLayerEffect(effect: LayerEffect, changes: Record<string, unknown>): LayerEffect;
+/** A layer's effects with `items` validated; throws on the first bad effect. */
+declare function validateLayerEffects(v: unknown): asserts v is LayerEffects;
+/**
+ * Reads effects from JSON leniently: invalid effects are dropped (so one bad entry does not lose
+ * a document), and missing optional fields take their defaults. `null` when nothing usable.
+ */
+declare function normalizeLayerEffects(raw: unknown): LayerEffects | undefined;
+/** Effects without ids or the PSD block, for comparing what two effect stacks render. */
+declare function effectsFingerprint(effects: LayerEffects | undefined | null): string;
+
+/**
+ * Pattern paint for pattern overlays, pattern strokes and bevel textures: a tile repeated over
+ * the plane from an origin (the layer's top-left when linked, else the canvas origin, plus the
+ * phase), scaled and rotated about it. Samples are bilinear and wrap around, on premultiplied
+ * colour, so whole-pixel placements at 100 % reproduce the tile exactly.
+ *
+ * Patterns come from the document (PSD pattern resources) or from the built-in set below, so a
+ * pattern effect always has something to paint even in a document without patterns.
+ */
+/** A pattern tile: straight-alpha RGBA. */
+interface EffectPattern {
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}
+/** A pattern converted once for sampling (premultiplied 0..1). */
+declare class PatternTile {
+    readonly w: number;
+    readonly h: number;
+    private readonly px;
+    constructor(p: Pick<EffectPattern, 'width' | 'height' | 'data'>);
+    /** Bilinear wrapping sample at tile coordinates (pixel centres at `i + 0.5`), straight alpha into `out`. */
+    sample(u: number, v: number, out: Float32Array | number[]): void;
+}
+/** Where a pattern sits: maps a document point to tile coordinates. */
+declare class PatternPlacement {
+    private readonly ox;
+    private readonly oy;
+    private readonly c;
+    private readonly s;
+    private readonly inv;
+    /** `anchor`: the layer's top-left (used when `link`); `phase` in px; `scale` a fraction; `angle` degrees counter-clockwise. */
+    constructor(anchor: {
+        x: number;
+        y: number;
+    }, link: boolean, phase: {
+        x: number;
+        y: number;
+    }, scale: number, angle: number);
+    /** Tile coordinates of the document point `(x, y)` into `out[0..1]`. */
+    map(x: number, y: number, out: number[]): void;
+}
+/** Ids of the built-in patterns (`checker`, `stripes`, `dots`, `grid`, `noise`). */
+declare function builtinPatternIds(): string[];
+/** A built-in pattern by id, or `null`. */
+declare function builtinPattern(id: string): EffectPattern | null;
+/**
+ * Deterministic per-pixel value in 0..1 hashed from document coordinates, so effect noise is
+ * stable across renders and tiles (photocraft's `hash_noise`).
+ */
+declare function hashNoise(x: number, y: number): number;
+
+/**
+ * Resampling tiled surfaces through geometric maps: Free Transform (scale, rotate, skew, distort,
+ * perspective: one projective map) and Warp (any forward map, such as a Bézier mesh).
+ *
+ * - Inverse mapping per destination tile: each destination tile reads only the source window its
+ *   pixels map into, so memory stays bounded by one tile's footprint, and the result is a new
+ *   copy-on-write surface (an identity or a whole-pixel move returns the source, or shares its
+ *   tiles).
+ * - Nearest, bilinear and Photoshop's Bicubic (the Keys cubic at a = −0.75). Colour is sampled
+ *   premultiplied by alpha, so partially transparent edges don't pick up the colour of the
+ *   transparent pixels around them; outside the source everything is transparent.
+ * - Large reductions with Bicubic are pre-filtered: the source is box-averaged by whole factors
+ *   first and the cubic widened by the rest, so shrinking a layer doesn't alias. Bilinear and
+ *   nearest sample the source directly, as Photoshop's do.
+ * - Masks (one channel) are warped as "value + inside": outside the source and outside the warped
+ *   area they read as the surface's default value, so a reveal-all mask stays white around a
+ *   transformed hole.
+ * - A Distort dragged past the horizon draws only the side of the horizon most of the source maps
+ *   to (no mirrored copy wrapped round infinity).
+ *
+ * No DOM: runs in Node, tests and workers.
+ */
+
+/** Resampling of a transform (Photoshop's interpolation menu). */
+type Interpolation = 'nearest' | 'bilinear' | 'bicubic';
+declare const INTERPOLATIONS: readonly Interpolation[];
+declare function isInterpolation(value: unknown): value is Interpolation;
+/**
+ * The largest result (pixels) one resample may build: about 11 600 × 11 600. Only the size of the
+ * result counts, not where it lands. A scale past it is refused rather than clipped.
+ */
+declare const MAX_TRANSFORM_PIXELS: number;
+/** A transform whose result would be too large; the message gives the size and the limit. */
+declare class TransformTooLargeError extends Error {
+    constructor(message: string);
+}
+interface ResampleOptions {
+    /** Default `bicubic`. */
+    interpolation?: Interpolation;
+    /** The source region to transform (default: the surface's content bounds). Pixels outside it are not moved. */
+    source?: RasterRect;
+    /** Keep only destination pixels inside this rectangle (a preview of the visible area). */
+    clip?: RasterRect;
+    /**
+     * Preview speed-up: sample once per `step × step` block of destination pixels and fill the
+     * block (a power of two, 1..64; default 1, every pixel).
+     */
+    step?: number;
+}
+/**
+ * Photoshop's Bicubic: the Keys cubic at a = −0.75 (Catmull-Rom is −0.5). Measured on Photoshop
+ * 27.11's Free Transform by photocraft: a 200 % step edge matches within 0.5 levels.
+ */
+declare function keysWeight(x: number): number;
+/**
+ * The surface box-averaged by `factor` (a whole number ≥ 1) in both directions: reduced pixel
+ * (i, j) covers pixels [i·factor, (i+1)·factor) of each axis. For previews: transform the reduced
+ * surface through the map composed with a scale by `factor`, so a preview at a low zoom reads a
+ * fraction of the pixels.
+ */
+declare function reduceSurface(src: TiledSurface, factor: number): TiledSurface;
+/** The destination rectangle `transformSurface` fills for `source` under `h`, or `null` when it is empty or unbounded. */
+declare function transformedBounds(source: RasterRect, h: Homography): RasterRect | null;
+/**
+ * The surface's content inside `options.source` (default: all of it) warped by `h` (source →
+ * destination, both in the surface's pixel space). Pixels outside the warped area are the default
+ * (transparent for layers). Throws `TransformTooLargeError` past `MAX_TRANSFORM_PIXELS`.
+ */
+declare function transformSurface(src: TiledSurface, h: Homography, options?: ResampleOptions): TiledSurface;
+/**
+ * The surface's content inside `options.source` (default: all of it) warped through the forward
+ * map `f` (source → destination pixel space; `null` where it is undefined).
+ *
+ * The source rectangle is subdivided into a fine grid whose vertices are mapped forward; each
+ * cell's two triangles are rasterized in destination space with the source position interpolated
+ * barycentrically, then the source is sampled there. Cells are a few source pixels across, so the
+ * piecewise-affine inverse is within a small fraction of a pixel of the true one; affine maps (the
+ * identity included) are reproduced exactly. Where the warp shrinks the source, each pixel instead
+ * averages a grid of bilinear subsamples over its source footprint, so thin lines don't alias.
+ * Where the warp folds over itself the later (lower-right) cell wins.
+ */
+declare function warpSurface(src: TiledSurface, f: (p: Vec2) => Vec2 | null, options?: ResampleOptions): TiledSurface;
+/**
+ * `top` (RGBA, straight alpha) composited over `base` with the Normal blend. A one-channel `base`
+ * (a mask) takes `top`'s red channel as the value, weighted by its alpha: that is how a moved part
+ * of a mask travels (value and coverage) and lands. Only tiles `top` stores are touched, so every
+ * other tile of `base` stays shared.
+ */
+declare function compositeSurfaceOver(base: TiledSurface, top: TiledSurface): TiledSurface;
+
+/**
+ * A layer stack that is not specific to any editor: pixel layers on tiled surfaces, groups (with
+ * pass-through), raster masks with density and feather, clipping, locks, opacity, fill and blend
+ * modes, plus pure tree helpers. Editors extend these types with their own layer kinds (the image
+ * editor adds adjustment and annotation layers, filters and parametric masks).
+ *
+ * Layer objects are immutable: every change builds new objects along the path from the root to
+ * the changed layer and shares everything else.
+ */
+
+/** Blend modes of a layer; groups also accept `pass-through`. */
+type GroupBlendMode = BlendMode | 'pass-through';
+interface LayerLocks {
+    /** Painting and filling are refused. */
+    pixels?: boolean;
+    /** Painting keeps each pixel's alpha. */
+    transparency?: boolean;
+    /** Moving (offset) is refused. */
+    position?: boolean;
+    /** Everything above, plus property changes and deletion. */
+    all?: boolean;
+}
+/**
+ * A layer mask: 8-bit coverage (255 reveals, 0 hides) on a tiled surface, plus non-destructive
+ * density and feather. `source` is an editor-defined parametric mask (generated instead of
+ * painted; the compositor asks its profile for the coverage, and the surface is unused).
+ */
+interface RasterMask<Source = unknown> {
+    surface: MaskSurface;
+    /** Value outside the painted tiles (PSD's default colour); equals `surface.defaultValue`. */
+    defaultValue: 0 | 255;
+    /** 0..1 (missing = 1): at 0.5 hidden areas still show half. */
+    density?: number;
+    /** Gaussian σ in pixels (missing = 0). */
+    feather?: number;
+    /** `false` keeps the mask but ignores it. */
+    enabled?: boolean;
+    /**
+     * `false` unlinks the mask from its layer (Photoshop's chain icon): moving or transforming the
+     * layer's pixels leaves the mask where it is. Missing = linked.
+     */
+    linked?: boolean;
+    source?: Source;
+}
+interface RasterLayerBase {
+    id: string;
+    name: string;
+    visible: boolean;
+    /** 0..1 */
+    opacity: number;
+    blend: BlendMode;
+    /** Clip to the nearest unclipped layer below (Photoshop's clipping mask). */
+    clipped?: boolean;
+    mask?: RasterMask;
+    locks?: LayerLocks;
+    /** Live layer effects (drop shadow, stroke, …), rendered between the content and its blend. */
+    effects?: LayerEffects;
+}
+interface RasterPixelLayer extends RasterLayerBase {
+    type: 'pixel';
+    /** Pixels in layer space; document position = layer position + `offset`. A linked mask moves with it. */
+    surface: PixelSurface;
+    /** Integer move without re-tiling. */
+    offset: {
+        x: number;
+        y: number;
+    };
+    /** 0..1, PSD "Fill" (missing = 1). */
+    fillOpacity?: number;
+}
+interface RasterGroupLayer<L = RasterLayer> extends Omit<RasterLayerBase, 'blend'> {
+    type: 'group';
+    blend: GroupBlendMode;
+    /** Bottom to top. */
+    children: L[];
+    /** UI only. */
+    collapsed?: boolean;
+}
+/** The plain stack: pixel layers and groups. */
+type RasterLayer = RasterPixelLayer | RasterGroupLayer<RasterLayer>;
+/** What the tree helpers need of a layer: an id, a type, and `children` on groups. */
+interface RasterNode {
+    id: string;
+    type: string;
+}
+/** The group members of a layer union. */
+type GroupIn<T> = Extract<T, {
+    type: 'group';
+}>;
+interface LayerLocation<T extends RasterNode = RasterLayer> {
+    layer: T;
+    /** The containing group, or `null` at the top level. */
+    parent: GroupIn<T> | null;
+    /** Index within the parent's children (or the top-level list). */
+    index: number;
+    /** Ancestors from the top level down to the parent. */
+    path: GroupIn<T>[];
+}
+/** Every layer, depth first, bottom to top (a group comes before its children). */
+declare function flattenLayers<T extends RasterNode>(layers: readonly T[]): T[];
+declare function findLayer<T extends RasterNode>(layers: readonly T[], id: string): LayerLocation<T> | null;
+/** Replaces the layer with `id` by `fn(layer)` (or removes it when `fn` returns `null`). */
+declare function mapLayer<T extends RasterNode>(layers: readonly T[], id: string, fn: (layer: T) => T | null): T[];
+/** Inserts `layer` into `parentId`'s children (or the top level) at `index` (default: top). */
+declare function insertLayer<T extends RasterNode>(layers: readonly T[], layer: T, parentId: string | null, index?: number): T[];
+declare function isLayerLocked(layer: {
+    locks?: LayerLocks;
+}, what: keyof LayerLocks): boolean;
+
+/**
+ * The per-tile layer compositor engine. Composites a layer stack (pixel layers and groups with
+ * masks, clipping, blend modes, opacity, fill and pass-through) tile by tile in document space,
+ * in pure TypeScript, so results are deterministic and testable in Node and Workers.
+ *
+ * Editors add their own layer kinds through a {@link CompositorProfile}: layers that filter
+ * what is below them (adjustment layers), content layers drawn by the editor (annotations),
+ * per-layer pixel filters, and parametric mask sources.
+ *
+ * Caches:
+ * - Each top-level *step* (a content layer and the layers clipped to it, a run of filter layers,
+ *   a group) has a per-tile *signature*: its properties plus the identity of every surface tile
+ *   it reads. A tile whose signatures are unchanged returns the cached result (same buffer
+ *   object, so callers can skip uploading it).
+ * - A prefix cache keeps the accumulator *before* the step that changed last time (and, when the
+ *   caller names it, before the active layer). Dragging a slider on layer k, or a stroke on layer
+ *   k, recomposites from step k upwards only; `dirty` rectangles limit that to where it changed.
+ * - Spatial filters and feathered or parametric masks are computed once over the canvas and
+ *   cached by the identity of their inputs.
+ * - Layer effects: a layer's effect maps (shadow, glow, bevel, stroke distance fields) are built
+ *   once over the layer's region (its bounds grown by the effects' margin, within the canvas grown
+ *   the same) and cached by the identity of every surface tile the shape reads; tiles crop them.
+ *   When only some of those tiles changed and every effect is local, the maps are rebuilt only
+ *   within the margin of the change (narrowed by `dirty` when it covers the change) and patched in.
+ *   A tile's signature then reads the layer within the margin around it (or the whole region when
+ *   an effect is laid out over the layer's bounds), and `dirty` rectangles grow by the margin.
+ */
+
+/** What the compositor needs from its host besides the layers. */
+interface RasterSources {
+    /** Canvas (document) size: spatial filters and mask feathering clamp at this rect. */
+    width: number;
+    height: number;
+    /** The pixels of a pixel layer (lets a host resolve layers whose pixels live elsewhere). */
+    surfaceOf?(layer: CompositorLayer): PixelSurface;
+    /** Changes whenever one of the host's callbacks would return something new for the same layers. */
+    version?: number | string;
+    /** The document's global light for effects that use it (default angle 120°, altitude 30°). */
+    globalLight?: GlobalLight;
+    /** A document pattern by id for pattern effects (built-in patterns are found without it). */
+    pattern?(id: string): EffectPattern | null;
+}
+/** The fields the engine reads; editor layer types are wider. */
+interface CompositorLayer extends RasterNode {
+    visible: boolean;
+    opacity: number;
+    blend: string;
+    clipped?: boolean;
+    mask?: RasterMask;
+    /** Pixel layers. */
+    surface?: PixelSurface;
+    offset?: {
+        x: number;
+        y: number;
+    };
+    fillOpacity?: number;
+    /** Layer effects. */
+    effects?: LayerEffects;
+    /** Groups. */
+    children?: readonly CompositorLayer[];
+}
+/** A pixel layer's filters as the engine runs them. */
+interface PixelFilterSpec {
+    /** Identifies the settings (part of the cache key). */
+    key: string;
+    /** Needs neighbouring pixels: runs once over the canvas instead of per tile. */
+    spatial: boolean;
+    /** Filters RGBA `data` (`width × height`) in place. */
+    apply(data: Uint8ClampedArray, width: number, height: number): void;
+}
+/** How an editor's own layer kinds composite. Every hook is optional. */
+interface CompositorProfile<L extends CompositorLayer, S extends RasterSources> {
+    /** Layers that change what is below them; adjacent ones run as one step. */
+    isFilterLayer?(layer: L): boolean;
+    /** Applies a run of visible filter layers to `acc` (RGBA over `r`); `coverage` holds masked ones by id. */
+    applyFilterRun?(layers: L[], acc: Uint8ClampedArray, r: RasterRect, coverage: Map<string, Float32Array> | undefined, sources: S): void;
+    /** RGBA of a content layer that is neither a pixel layer nor a group, over `r`, or `null`. */
+    contentTile?(layer: L, r: RasterRect, sources: S): Uint8ClampedArray | null;
+    /** The blend mode a content layer draws with (default `layer.blend`). */
+    contentBlend?(layer: L): BlendMode;
+    /** Properties of a layer beyond the generic ones that change its pixels (part of its signature). */
+    layerKey?(layer: L): unknown;
+    /** Active filters of a pixel layer, or `null`. */
+    pixelFilters?(layer: L): PixelFilterSpec | null;
+    /** Canvas coverage (0..1, `width × height`) of a parametric mask source, or `null` to reveal all. */
+    maskSourcePlane?(source: unknown, width: number, height: number, sources: S): Float32Array | null;
+    /**
+     * Layer kinds besides `pixel` that composite exactly like pixel layers, from their `surface`,
+     * `offset` and `fillOpacity` (a smart object's rendered pixels). Their tile signatures, effect
+     * regions and `dirty` handling are a pixel layer's.
+     */
+    isPixelLike?(layer: L): boolean;
+}
+interface CompositorOptions {
+    /** Upper bound for cached tile buffers (default 256 MiB). */
+    maxCacheBytes?: number;
+}
+interface CompositeCallOptions {
+    /**
+     * The layer about to be edited (the active layer): every tile composited in this call keeps a
+     * checkpoint below its step, so strokes and slider drags on it start there.
+     */
+    checkpointLayerId?: string | null;
+    /**
+     * Where the layers changed since the previous call, when the caller knows (a stroke's dabs).
+     * Changed tiles are then recomposited only inside these rectangles (grown by the effects' reach),
+     * tiles they miss keep their pixels, and effect maps are rebuilt only around them. Changes outside
+     * them would be missed, so pass nothing when unsure.
+     */
+    dirty?: RasterRect[];
+}
+/**
+ * Blends straight-alpha `src` over `dst` (both RGBA) in place with `mode`, scaling the source
+ * alpha by `alpha` and, per pixel, by `coverage`. Same maths as `blendPixel` (including the
+ * `pigment` paint mix, which caches each 8-bit colour's spectrum).
+ */
+declare function blendTile(dst: Uint8ClampedArray, src: ArrayLike<number>, mode: BlendMode, alpha: number, coverage: ArrayLike<number> | null): void;
+/** Statistics of the last `composite` call (for benchmarks and tests). */
+interface CompositeStats {
+    tiles: number;
+    /** Tiles returned straight from the cache. */
+    cached: number;
+    /** Steps actually run, summed over tiles. */
+    stepsRun: number;
+    /** Layers whose effect maps were built over their whole region. */
+    effectsBuilt: number;
+    /** Layers whose effect maps were rebuilt only around a change and patched in. */
+    effectsPatched: number;
+}
+declare class RasterCompositor<L extends CompositorLayer = CompositorLayer, S extends RasterSources = RasterSources> {
+    private readonly profile;
+    private readonly tiles;
+    private readonly maxCacheBytes;
+    private cacheBytes;
+    private stamp;
+    private sources;
+    private sourcesVersion;
+    private filteredCache;
+    private planeCache;
+    private planeIds;
+    private nextPlaneId;
+    private contentCache;
+    private readonly stepsCache;
+    private readonly propsKeyCache;
+    /** Effect maps by layer id (see the module comment), least recently used first. */
+    private effectCache;
+    /** Effect maps already validated in this call, by layer object. */
+    private effectMemo;
+    private readonly patternTiles;
+    private readonly reachCache;
+    private fxContext;
+    lastStats: CompositeStats;
+    private hint;
+    /** The `dirty` rectangles of the current call, as passed. */
+    private callDirty;
+    private callStats;
+    constructor(profile?: CompositorProfile<L, S>, options?: CompositorOptions);
+    /** Drops every cached tile and plane. */
+    clear(): void;
+    private setSources;
+    /** The composite of `layers` over `rect` as `rect.width × rect.height` RGBA (straight alpha). */
+    composite(layers: readonly L[], rect: RasterRect, sources: S, options?: CompositeCallOptions): Uint8ClampedArray;
+    /**
+     * Composites every tile intersecting `rect` and calls `onTile` with each tile's RGBA buffer
+     * (TILE × TILE). A tile whose inputs did not change since the last call returns the same buffer
+     * object; never mutate it.
+     */
+    compositeTiles(layers: readonly L[], rect: RasterRect, sources: S, onTile: (tx: number, ty: number, data: Uint8ClampedArray, changed: boolean) => void, options?: CompositeCallOptions): void;
+    /** The composite of one tile (cached; do not mutate the result). */
+    tile(layers: readonly L[], tx: number, ty: number, sources: S): Uint8ClampedArray;
+    /**
+     * A layer's effective mask coverage (0..1, after density, feather or parametric evaluation)
+     * over `r` in document space, or `null` when it reveals all of `r`.
+     */
+    maskCoverage(layer: L, r: RasterRect, sources: S): Float32Array | null;
+    /** Pixel layers, and the layer kinds the profile composites like them. */
+    private isPixel;
+    private isFilter;
+    /**
+     * Groups a layer list into compositing steps: clipped layers join the nearest unclipped
+     * content or group layer below; consecutive unclipped filter layers form one run.
+     */
+    private buildSteps;
+    /** The index of the top-level step that holds layer `id` (searching groups and clipped layers), or -1. */
+    private stepIndexOf;
+    /** Properties of a layer that change pixels, minus its surfaces (memoised per object). */
+    private propsKey;
+    private compositeTile;
+    /**
+     * Whether a tile with no part in this call's (grown) `dirty` rectangles changed only in what local
+     * effects read beyond it: every changed step is a pixel layer with local effects whose changes stay
+     * inside `dirty` (and so are farther than its margin), which leaves the tile's pixels as they were.
+     */
+    private changedOnlyNearby;
+    private entryBytes;
+    private evict;
+    private stepSig;
+    private layerSig;
+    private groupSig;
+    private plainGroupSig;
+    private contentSig;
+    private plainContentSig;
+    private hasEffects;
+    /** The largest effects margin of any visible layer in the stack (memoised per root). */
+    private effectsReach;
+    private effectContext;
+    /**
+     * Where a layer's effect maps are built: its bounds (pixel layers; the canvas otherwise) grown by
+     * the effects' margin, within the canvas grown the same.
+     */
+    private effectRegion;
+    /** The signature of a layer's shape (its surface tiles and mask refs) per tile of `region`. */
+    private shapeSigs;
+    /** The surface tiles (and mask refs) a layer's shape reads over `region`. */
+    private shapeRefs;
+    private lightKey;
+    /**
+     * The signature of a layer with effects for tile (tx, ty): its properties and the tiles its shape
+     * reads within the effects' margin around the tile, or over its whole region when an effect is
+     * laid out over the layer's bounds.
+     */
+    private effectSig;
+    /** A layer's effect maps over its region (cached; see the module comment). */
+    private effectMapsOf;
+    /**
+     * Where a layer's shape may differ from the one `prev` was built from: the tiles whose signature
+     * changed (a tile new to the region that reads nothing did not), narrowed to this call's `dirty`
+     * rectangles when `prev` is from the previous call and they cover every change of the shape.
+     */
+    private shapeChanges;
+    /**
+     * Whether a change to a layer stays inside the `dirty` rectangles that name it: a pixel layer
+     * without filters or a feathered or parametric mask (those spread a change beyond it).
+     */
+    private dirtyCoversShape;
+    /** A layer's alpha over `r` after its mask (0..1, quantised to bytes as tiles see it). */
+    private layerShape;
+    /** A content or group layer's own pixels over `r` with its mask applied to alpha, or `null` when empty. */
+    private ownPixels;
+    /**
+     * The part of `r` a layer with effects can change: its shape's bounds grown by the effects'
+     * margin. Beyond it the layer and every effect are transparent, so the backdrop stays as it is.
+     */
+    private effectArea;
+    /**
+     * Composites `layer`'s pixels (with `clipped` applied) and its effects onto `acc` (RGBA over `r`),
+     * only where they can reach. `keepAlpha`: clipped layers keep the base's alpha.
+     */
+    private compositeEffects;
+    /** Composites a layer with active effects onto `acc` over `r`; returns whether `acc` is still empty. */
+    private runEffectStep;
+    private maskRefs;
+    /**
+     * A pixel layer's pixels after spatial filters: the surface and the offset to apply. Layers
+     * with a spatial filter are filtered once over the canvas (in document space, offset 0).
+     */
+    private layerPixels;
+    /** RGBA of a content layer over `r` (document space, inside one tile), or `null` when it has nothing there. */
+    private contentTile;
+    private planeKey;
+    /** Canvas-sized coverage of a feathered or parametric mask (cached). */
+    private planeFor;
+    private maskTile;
+    /** Runs one step onto `acc`; returns whether `acc` is still empty. */
+    private runStep;
+    private runSteps;
+    private contentBlend;
+    private blendOnto;
+    private applyClipped;
+    private applyFilterRun;
+}
+/** Tiles that differ between two surfaces (by tile identity), as tile keys. */
+declare function changedTiles(a: TiledSurface, b: TiledSurface): TileKey[];
+
+export { TransformTooLargeError as $, type GradientColorStop as A, type BevelContour as B, type CompositorLayer as C, DEFAULT_GLOBAL_LIGHT as D, type EffectPattern as E, type GradientOpacityStop as F, type GroupBlendMode as G, type GradientOverlayEffect as H, type Interpolation as I, type GradientStyle as J, INTERPOLATIONS as K, type LayerLocks as L, type InnerGlowEffect as M, type InnerShadowEffect as N, LAYER_EFFECT_KINDS as O, LayerEffectError as P, MAX_EFFECT_REACH as Q, type RasterLayer as R, MAX_TRANSFORM_PIXELS as S, type OuterGlowEffect as T, type PatternOverlayEffect as U, PatternPlacement as V, PatternTile as W, type ResampleOptions as X, type SatinEffect as Y, type StrokeEffect as Z, type StrokePosition as _, type RasterGroupLayer as a, blendTile as a0, builtinPattern as a1, builtinPatternIds as a2, changedTiles as a3, compositeSurfaceOver as a4, defaultEffectGradient as a5, defaultLayerEffect as a6, effectColorHex as a7, effectReach as a8, effectsFingerprint as a9, type CompositorProfile as aA, type GroupIn as aB, type PixelFilterSpec as aC, type RasterNode as aD, effectsMargin as aa, effectsScale as ab, findLayer as ac, flattenLayers as ad, hasActiveEffects as ae, hashNoise as af, insertLayer as ag, isInterpolation as ah, isLayerEffectKind as ai, isLayerLocked as aj, keysWeight as ak, layerEffectFields as al, layerEffectLabel as am, mapLayer as an, mergeLayerEffect as ao, newEffectId as ap, normalizeLayerEffects as aq, parseEffectColor as ar, reduceSurface as as, scaleLayerEffect as at, transformSurface as au, transformedBounds as av, validateEffectGradient as aw, validateLayerEffect as ax, validateLayerEffects as ay, warpSurface as az, type RasterPixelLayer as b, RasterCompositor as c, type RasterSources as d, type RasterLayerBase as e, type RasterMask as f, type GlobalLight as g, type LayerLocation as h, type LayerEffect as i, type LayerEffects as j, type CompositorOptions as k, type LayerEffectKind as l, type BevelEmbossEffect as m, type BevelStyle as n, type BevelTechnique as o, type BevelTexture as p, type ColorOverlayEffect as q, type CompositeCallOptions as r, type CompositeStats as s, type ContourPoint as t, type DropShadowEffect as u, type EffectContour as v, type EffectFill as w, type EffectGradient as x, type EffectPatternRef as y, type GlowTechnique as z };