@pixerate/editor 0.95.0 → 0.96.0

package/dist/raster/index.d.cts

@@ -1,7 +1,732 @@
-import { B as BlendMode } from '../surface-CgAiXVI3.cjs';
-export { a as BLEND_MODES, b as BlendModeInfo, M as MaskSurface, P as PixelSurface, R as RasterRect, c as Rgb, d as Rgba, S as SurfaceDraft, T as TILE, e as TILE_SHIFT, f as Tile, g as TileKey, h as TiledSurface, 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 mixPigment8, w as mixPigmentRgb, x as normalizeBlendMode, y as packRgba, z as readPixel, A as readRegion, C as setLum, D as solidSurface, E as surfaceBytes, F as surfaceFromPixels, G as surfacesEqual, H as tileCoord, I as tileKey, J as tileRect, K as tilesInRect, L as translateSurface, N as uniformTile, O as writeRegion } from '../surface-CgAiXVI3.cjs';
-import { L as LayerEffect, G as GlobalLight, P as PatternTile, a as LayerEffects, E as EffectContour, b as GradientStyle } from '../zlib-B3LIoxF-.cjs';
-export { B as BevelContour, c as BevelEmbossEffect, d as BevelStyle, e as BevelTechnique, f as BevelTexture, g as BlurEdge, C as CURVE_LUT_SIZE, h as ColorOverlayEffect, i as CompositeCallOptions, j as CompositeStats, k as CompositorLayer, l as CompositorOptions, m as CompositorProfile, n as ContourPoint, D as DEFAULT_GLOBAL_LIGHT, o as DIRECT_GAUSSIAN_MAX_SIGMA, p as DecodedPng, q as DropShadowEffect, r as EffectFill, s as EffectGradient, t as EffectPattern, u as EffectPatternRef, v as GlowTechnique, w as GradientColorStop, x as GradientOpacityStop, y as GradientOverlayEffect, z as GroupBlendMode, A as GroupIn, I as InnerGlowEffect, F as InnerShadowEffect, H as LAYER_EFFECT_KINDS, J as LayerEffectError, K as LayerEffectKind, M as LayerLocation, N as LayerLocks, O as MAX_EFFECT_REACH, Q as OuterGlowEffect, R as PatternOverlayEffect, S as PatternPlacement, T as PixelFilterSpec, U as RasterCompositor, V as RasterGroupLayer, W as RasterLayer, X as RasterLayerBase, Y as RasterMask, Z as RasterNode, _ as RasterPixelLayer, $ as RasterSources, a0 as SatinEffect, a1 as StrokeEffect, a2 as StrokePosition, a3 as ZlibError, a4 as adler32, a5 as base64ToBytes, a6 as blendTile, a7 as builtinPattern, a8 as builtinPatternIds, a9 as bytesToBase64, aa as changedTiles, ab as curveLut, ac as decodePng, ad as defaultEffectGradient, ae as defaultLayerEffect, af as deflate, ag as deflateRaw, ah as effectColorHex, ai as effectReach, aj as effectsFingerprint, ak as effectsMargin, al as effectsScale, am as encodePng, an as findLayer, ao as flattenLayers, ap as gaussianBlur, aq as hasActiveEffects, ar as hashNoise, as as inflate, at as inflateRaw, au as insertLayer, av as isLayerEffectKind, aw as isLayerLocked, ax as isPng, ay as layerEffectFields, az as layerEffectLabel, aA as mapLayer, aB as mergeLayerEffect, aC as newEffectId, aD as normalizeLayerEffects, aE as parseDataUrl, aF as parseEffectColor, aG as pngDataUrl, aH as scaleLayerEffect, aI as validateEffectGradient, aJ as validateLayerEffect, aK as validateLayerEffects } from '../zlib-B3LIoxF-.cjs';
+import { B as BlendMode, M as MaskSurface, P as PixelSurface, R as RasterRect, T as TiledSurface, h as TileKey } from '../surface-DIA-XatS.cjs';
+export { a as BLEND_MODES, b as BlendModeInfo, c as Rgb, d as Rgba, S as SurfaceDraft, e as TILE, f as TILE_SHIFT, g as Tile, 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 mixPigment8, w as mixPigmentRgb, x as normalizeBlendMode, y as packRgba, z as readPixel, A as readRegion, C as setLum, D as solidSurface, E as surfaceBytes, F as surfaceFromPixels, G as surfacesEqual, H as tileCoord, I as tileKey, J as tileRect, K as tilesInRect, L as translateSurface, N as uniformTile, O as writeRegion } from '../surface-DIA-XatS.cjs';
+
+/**
+ * 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;
+
+/**
+ * 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;
+    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 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.
+ *   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;
+}
+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. 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;
+}
+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;
+    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;
+    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;
+    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 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;
+    /** 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[];
+
+/** Above this σ a Gaussian is approximated by three box passes (cost independent of σ). */
+declare const DIRECT_GAUSSIAN_MAX_SIGMA = 8;
+/** How a blur treats pixels beyond the image: `zero`, or `clamp` (replicate the border). */
+type BlurEdge = 'zero' | 'clamp';
+type Edge = BlurEdge;
+/**
+ * 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;
+
+/**
+ * Curve lookup tables shared by Curves adjustments and layer-effect contours.
+ */
+/** Entries of a curve LUT (input 0..1 in `size - 1` steps). */
+declare const CURVE_LUT_SIZE = 4096;
+/**
+ * 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;
 
 /**
  * CPU renderer for layer effects.
@@ -113,4 +838,70 @@ declare function renderLayerEffects(effects: LayerEffects, layer: {
     fillOpacity?: number;
 }, backdrop: Uint8ClampedArray, canvas: EffectRect, ctx: EffectContext): void;
 
-export { BlendMode, type EffectCompositeInput, type EffectContext, EffectContour, type EffectMaps, type EffectRect, GlobalLight, GradientStyle, LayerEffect, LayerEffects, PatternTile, STROKE_CHAMFER_MAX, activeEffectItems, buildEffectMaps, compositeLayerEffects, contourLut, effectsAreLocal, gradientT, renderLayerEffects };
+/**
+ * Dependency-free, synchronous PNG encode / decode for layer pixels and masks, plus base64 and
+ * data-URL helpers. Canvas `toDataURL` is lossy for partly transparent pixels (it goes through
+ * premultiplied alpha), so layer assets use this codec and round-trip exactly.
+ *
+ * Encodes 8-bit greyscale (masks) or RGBA (layers). Decodes non-interlaced 1/2/4/8/16-bit
+ * greyscale, RGB, palette, grey + alpha and RGBA, always to 8-bit RGBA or grey.
+ */
+interface DecodedPng {
+    width: number;
+    height: number;
+    /** 4 for RGBA output, 1 for greyscale without alpha when `keepGray` was asked for. */
+    channels: 1 | 4;
+    data: Uint8ClampedArray;
+}
+/** PNG bytes for `width × height` pixels of 1 (grey) or 4 (RGBA) bytes each. */
+declare function encodePng(width: number, height: number, data: ArrayLike<number>, channels?: 1 | 4): Uint8Array;
+declare function isPng(bytes: Uint8Array): boolean;
+/**
+ * Decodes a PNG. Output is RGBA (4 channels) unless `keepGray` is set and the image is
+ * greyscale without alpha, in which case it is one byte per pixel.
+ */
+declare function decodePng(bytes: Uint8Array, options?: {
+    keepGray?: boolean;
+    maxPixels?: number;
+}): DecodedPng;
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToBytes(text: string): Uint8Array;
+/** The bytes and MIME type of a `data:` URL (base64 or percent-encoded). */
+declare function parseDataUrl(url: string): {
+    mime: string;
+    bytes: Uint8Array;
+} | null;
+declare function pngDataUrl(width: number, height: number, data: ArrayLike<number>, channels?: 1 | 4): string;
+
+/**
+ * Synchronous zlib (RFC 1950) and raw deflate (RFC 1951), dependency-free, for the image editor's
+ * layer PNGs and PSD ZIP channels. `CompressionStream` is asynchronous and not everywhere, and
+ * layer pixels must serialize inside the synchronous `toJSON()`.
+ *
+ * - `inflate` handles stored, fixed and dynamic blocks and refuses to produce more than
+ *   `maxOutput` bytes (a decompression bomb guard).
+ * - `deflate` is a greedy LZ77 (hash chains, 32 KiB window) with one dynamic Huffman block per
+ *   64 Ki symbols. It favours simplicity over the last few percent of ratio.
+ */
+declare class ZlibError extends Error {
+    constructor(message: string);
+}
+/** Inflates raw deflate data (no zlib header). */
+declare function inflateRaw(data: Uint8Array, options?: {
+    maxOutput?: number;
+    sizeHint?: number;
+}): Uint8Array;
+/** Adler-32 checksum (zlib trailer). */
+declare function adler32(data: Uint8Array): number;
+/** Inflates zlib data (header, deflate stream, Adler-32 trailer). */
+declare function inflate(data: Uint8Array, options?: {
+    maxOutput?: number;
+    sizeHint?: number;
+    verify?: boolean;
+}): Uint8Array;
+/** Raw deflate (no zlib header). `level` 0 stores the data uncompressed. */
+declare function deflateRaw(data: Uint8Array, level?: 0 | 1): Uint8Array;
+/** zlib stream: header, raw deflate, Adler-32. */
+declare function deflate(data: Uint8Array, level?: 0 | 1): Uint8Array;
+
+export { type BevelContour, type BevelEmbossEffect, type BevelStyle, type BevelTechnique, type BevelTexture, BlendMode, type BlurEdge, CURVE_LUT_SIZE, type ColorOverlayEffect, type CompositeCallOptions, type CompositeStats, type CompositorLayer, type CompositorOptions, type CompositorProfile, type ContourPoint, DEFAULT_GLOBAL_LIGHT, DIRECT_GAUSSIAN_MAX_SIGMA, type DecodedPng, type DropShadowEffect, type EffectCompositeInput, type EffectContext, type EffectContour, type EffectFill, type EffectGradient, type EffectMaps, type EffectPattern, type EffectPatternRef, type EffectRect, type GlobalLight, type GlowTechnique, type GradientColorStop, type GradientOpacityStop, type GradientOverlayEffect, type GradientStyle, type GroupBlendMode, type GroupIn, type InnerGlowEffect, type InnerShadowEffect, LAYER_EFFECT_KINDS, type LayerEffect, LayerEffectError, type LayerEffectKind, type LayerEffects, type LayerLocation, type LayerLocks, MAX_EFFECT_REACH, MaskSurface, type OuterGlowEffect, type PatternOverlayEffect, PatternPlacement, PatternTile, type PixelFilterSpec, PixelSurface, RasterCompositor, type RasterGroupLayer, type RasterLayer, type RasterLayerBase, type RasterMask, type RasterNode, type RasterPixelLayer, RasterRect, type RasterSources, STROKE_CHAMFER_MAX, type SatinEffect, type StrokeEffect, type StrokePosition, TileKey, TiledSurface, ZlibError, activeEffectItems, adler32, base64ToBytes, blendTile, buildEffectMaps, builtinPattern, builtinPatternIds, bytesToBase64, changedTiles, compositeLayerEffects, contourLut, curveLut, decodePng, defaultEffectGradient, defaultLayerEffect, deflate, deflateRaw, effectColorHex, effectReach, effectsAreLocal, effectsFingerprint, effectsMargin, effectsScale, encodePng, findLayer, flattenLayers, gaussianBlur, gradientT, hasActiveEffects, hashNoise, inflate, inflateRaw, insertLayer, isLayerEffectKind, isLayerLocked, isPng, layerEffectFields, layerEffectLabel, mapLayer, mergeLayerEffect, newEffectId, normalizeLayerEffects, parseDataUrl, parseEffectColor, pngDataUrl, renderLayerEffects, scaleLayerEffect, validateEffectGradient, validateLayerEffect, validateLayerEffects };