@pixerate/editor 0.135.0 → 0.137.0

package/dist/brushes-DJmUbIgz.d.ts

@@ -0,0 +1,744 @@
+import { D as Dab, C as CoverageMap, B as BrushSettings, S as StrokePoint, P as PaintTileTarget, a as PaintGradientSource, T as TileMedium, M as MixerSettings, b as MixingModel, c as BlenderSettings, d as SmudgeSettings, e as PaintSource } from './blending-NgF3qo3d.js';
+import { R as RasterRect, T as TiledSurface } from './surface-1MRncXpF.js';
+
+/**
+ * Paper: a generated grain height map (0 = valley, 1 = peak) that tiles across the canvas, a paper
+ * colour, grain depth, and the three properties wet media will read later (absorption,
+ * permeability, roughness). Dry media catch the peaks: a light stroke only marks the high grain, a
+ * firm one fills the valleys too. Everything is generated from a pattern and a seed, so a paper is
+ * a few numbers in the document, never a bitmap, and no third-party texture is bundled.
+ */
+/** Grain generators. Each is our own procedural pattern (no scanned textures). */
+type GrainPattern = 'smooth' | 'cold-pressed' | 'hot-pressed' | 'rough' | 'vellum' | 'laid' | 'ingres' | 'sanded' | 'canvas' | 'linen' | 'gesso';
+declare const GRAIN_PATTERNS: readonly GrainPattern[];
+/** Paper families, as a library groups them. */
+type PaperFamily = 'watercolor' | 'drawing' | 'pastel' | 'canvas' | 'panel' | 'smooth';
+declare const PAPER_FAMILIES: readonly PaperFamily[];
+/** How a height map is tuned for one kind of media. */
+interface GrainTuning {
+    /** Height contrast around the middle, 0..3 (default 1). */
+    contrast: number;
+    /** Swap peaks and valleys (default false). */
+    invert: boolean;
+}
+type PaperTiling = 'repeat' | 'mirror';
+interface PaperSettings {
+    /** The library preset this paper started from (`custom` when it matches none). */
+    preset: string;
+    name: string;
+    family: PaperFamily;
+    pattern: GrainPattern;
+    /** Grain seed: another seed gives another sheet of the same paper. */
+    seed: number;
+    /** Paper colour #rrggbb. */
+    color: string;
+    /** Grain scale: 1 is the pattern's natural size, 2 twice as coarse (0.25..8). */
+    scale: number;
+    /** How the grain tile repeats: `repeat` or `mirror` (alternate tiles flipped, so seams vanish). */
+    tiling: PaperTiling;
+    /** Grain depth 0..1: how much grain-responsive dry media skip the valleys (0: none). */
+    depth: number;
+    /** How much the grain shades the paper colour on screen and in exports, 0..1. */
+    shading: number;
+    /** The height map as dry media read it. */
+    dry: GrainTuning;
+    /** The height map as wet media will read it (stored now; wet media is a later phase). */
+    wet: GrainTuning;
+    /** Wet media: how fast the paper takes up water, 0..1. */
+    absorption: number;
+    /** Wet media: how far water spreads inside the paper, 0..1. */
+    permeability: number;
+    /** Wet media: how much the grain catches pigment, 0..1. */
+    roughness: number;
+    /** Metallic paper (gold or silver leaf, pearlescent card): the grain catches the light, 0..1 (default 0). */
+    metallic?: number;
+}
+/** Side of the generated grain tile in pixels (at scale 1). */
+declare const GRAIN_TILE = 256;
+type PaperPreset = PaperSettings;
+/** The built-in paper library: generated papers in families. */
+declare const PAPER_LIBRARY: readonly PaperPreset[];
+declare const DEFAULT_PAPER: Readonly<PaperSettings>;
+/** A paper from the library by id, or `undefined`. */
+declare function paperPreset(id: string): PaperSettings | undefined;
+declare function clonePaper(p: PaperSettings): PaperSettings;
+/**
+ * A paper with every field in range. Missing fields come from `base` (default: the library preset
+ * named by `raw.preset`, else cold pressed).
+ */
+declare function normalizePaper(raw?: Partial<PaperSettings> | Record<string, unknown>, base?: PaperSettings): PaperSettings;
+/** The raw height map of a pattern (`GRAIN_TILE` square, 0..1), generated once per pattern and seed. */
+declare function grainHeights(pattern: GrainPattern, seed: number, size?: number): Float32Array;
+/**
+ * A paper's height field over the canvas (document pixels), tuned for one kind of media. Read it
+ * with `at(x, y)`: bilinear, tiled by `paper.tiling`, at `paper.scale`.
+ */
+declare class PaperGrain {
+    readonly size = 256;
+    private readonly heights;
+    private readonly scale;
+    private readonly mirror;
+    readonly flat: boolean;
+    constructor(paper: PaperSettings, media?: 'dry' | 'wet');
+    /** Tile cell index for a coordinate in grain pixels (mirrored on odd tiles when mirroring). */
+    private wrap;
+    /** Height 0..1 at document position (x, y). */
+    at(x: number, y: number): number;
+}
+/**
+ * How much of a dry dab lands at grain height `h` (0..1): the media catches the peaks first, and
+ * pressure pushes it into the valleys. `depth` is the paper's grain depth times the brush's grain
+ * response; at 0 everything lands (1).
+ */
+declare function grainCatch(h: number, depth: number, pressure: number): number;
+/** `#rrggbb` → [r, g, b] 0..255. */
+declare function hexToRgb8(hex: string): [number, number, number];
+/**
+ * The paper as opaque RGBA over `rect` (document pixels): its colour, darkened in the valleys by
+ * `shading`.
+ */
+declare function renderPaper(paper: PaperSettings, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, grain?: PaperGrain, light?: {
+    azimuth: number;
+    elevation: number;
+}): Uint8ClampedArray;
+
+/**
+ * The paint editor's dry-media stroke engine, on the shared brush engine (`@pixerate/editor/paint`):
+ *
+ * - Pen input: pressure, tilt (`tiltX` / `tiltY` or `altitude` / `azimuth`), barrel rotation
+ *   (`twist`) and time (for velocity). Position and pressure are smoothed separately.
+ * - `PenDabWalker` walks the points into the shared `Dab`s at `spacing × diameter`, with every
+ *   pen channel interpolated, and applies the brush's dynamics, rotation mode and jitter.
+ *   Jitter is a pure hash of the stroke seed and the dab index, so a stroke replays exactly.
+ * - `DryStroke` rasterizes each dab with the shared round tip, multiplies it by how much of it the
+ *   paper grain catches (`grainCatch`), and builds it up in the shared `CoverageMap`; the session
+ *   then composites the coverage with the shared `applyStrokeToTile`.
+ * - Symmetry: one stroke can paint several copies of its points (mirror and kaleidoscope), each
+ *   with its own walker, into the same coverage, so the copies are one stroke and one undo step.
+ *
+ * Pure data in, pixels out: no DOM, no framework.
+ */
+
+/** One pen sample in document pixels. Every channel but x and y is optional. */
+interface PenPoint {
+    x: number;
+    y: number;
+    /** 0..1 (missing: 1, a mouse). */
+    pressure?: number;
+    /** Milliseconds since any fixed origin (for velocity; missing: no velocity dynamics). */
+    t?: number;
+    /** Pointer Events tilt in degrees, -90..90 (used when `altitude` / `azimuth` are missing). */
+    tiltX?: number;
+    tiltY?: number;
+    /** Radians from the surface: π/2 is upright, 0 lies flat. */
+    altitude?: number;
+    /** Radians clockwise from the +x axis (screen y points down): where the pen leans. */
+    azimuth?: number;
+    /** Barrel rotation in degrees clockwise, 0..359. */
+    twist?: number;
+}
+/** A pen's lean as altitude and azimuth, or `null` when the sample has no tilt. */
+declare function penOrientation(p: PenPoint): {
+    altitude: number;
+    azimuth: number;
+} | null;
+/** Pointer Events `tiltX` / `tiltY` (degrees) → altitude and azimuth (radians). */
+declare function tiltToOrientation(tiltX: number, tiltY: number): {
+    altitude: number;
+    azimuth: number;
+};
+/**
+ * Exponential smoothing of position and of pressure, each by its own amount (0..0.95). Feed raw
+ * samples; the first sample passes through.
+ */
+declare class PenSmoother {
+    private pos;
+    private pressure;
+    private readonly a;
+    private readonly ap;
+    constructor(position: number, pressure: number);
+    push(p: PenPoint): PenPoint;
+    /** Where the smoothed position is now (or `null` before the first sample). */
+    get position(): {
+        x: number;
+        y: number;
+    } | null;
+}
+/** A linear map of document vectors `[a, b, c, d]`: (x, y) → (a·x + b·y, c·x + d·y). */
+type Linear2 = readonly [number, number, number, number];
+/** How one copy of a stroke maps the input: a point map and its linear part (for dab angles). */
+interface StrokeCopy {
+    map(p: PenPoint): PenPoint;
+    linear: Linear2;
+}
+declare const IDENTITY_COPY: StrokeCopy;
+/** A dab with the pen state it was made at (the shared `Dab` plus pressure for the grain). */
+interface PenDab extends Dab {
+    pressure: number;
+    /** Direction of travel at the dab, radians counter-clockwise with y up (as `angle`). */
+    direction: number;
+    /** The dab's index within its copy of the stroke (0, 1, 2 …). */
+    index: number;
+    /** Path length (px, along the smoothed samples of this copy) travelled to the dab: what gradient paint maps by distance. */
+    travel: number;
+    /** ms since the stroke's first timed sample, or `null` when the samples carry no time. */
+    time: number | null;
+    /** Pen lean, 0 upright .. 1 flat. */
+    lean: number;
+    /** Pen speed (px/ms), or `null` when the samples carry no time. */
+    speed: number | null;
+}
+/**
+ * Walks pen samples into dabs, incrementally (any chunking gives the same dabs). Dab angles are in
+ * the shared rasterizer's convention: radians, counter-clockwise with y up.
+ */
+declare class PenDabWalker {
+    readonly brush: PaintBrush;
+    private readonly seed;
+    private readonly linear;
+    private last;
+    private nextAt;
+    private pendingFirst;
+    private index;
+    private dir;
+    private lastT;
+    private firstT;
+    private speed;
+    private travelled;
+    constructor(brush: PaintBrush, seed?: number, linear?: Linear2);
+    private sample;
+    private diameter;
+    private stepLen;
+    /** A rasterizer angle (CCW, y up) mapped through this copy's linear part. */
+    private mapAngle;
+    private dab;
+    push(p: PenPoint, out: PenDab[]): void;
+    finish(out: PenDab[]): void;
+}
+interface DryStrokeOptions {
+    /** The paper's dry height field, or `null` for no grain. */
+    grain: PaperGrain | null;
+    /** The paper's grain depth, 0..1 (multiplied by the brush's grain response). */
+    paperDepth: number;
+    /** Jitter seed (record it to replay the stroke exactly). */
+    seed?: number;
+    /** Copies of the stroke (symmetry); default one identity copy. */
+    copies?: readonly StrokeCopy[];
+}
+/**
+ * One dab-engine stroke (dab and eraser brushes): smoothing, the dab walk of every copy, grain and
+ * build-up in a shared coverage map.
+ */
+declare class DryStroke {
+    readonly brush: PaintBrush;
+    private readonly options;
+    readonly coverage: CoverageMap;
+    dabCount: number;
+    private readonly smoother;
+    private readonly walkers;
+    private readonly copies;
+    private readonly depth;
+    private buf;
+    private lastRaw;
+    private lastFed;
+    constructor(brush: PaintBrush, options: DryStrokeOptions);
+    /** Feeds raw pen samples; returns the document rectangles the new dabs touched. */
+    push(points: readonly PenPoint[]): RasterRect[];
+    /** Ends the stroke: the smoothed path catches up with the last raw sample; a single tap paints one dab. */
+    finish(): RasterRect[];
+    private paint;
+}
+/** The shared engine's tip for the Mixer Brush engine (it smooths and walks by itself, so smoothing is applied before). */
+declare function mixerTip(brush: PaintBrush): BrushSettings;
+/** Pen samples → the shared engine's stroke points (pressure only). */
+declare function toStrokePoint(p: PenPoint): StrokePoint;
+
+/**
+ * Stickers: textured stamps sprayed along a stroke onto a sticker layer, where each stays an object
+ * that can be moved, turned, resized, recoloured or deleted afterwards. A sticker layer is a pixel
+ * layer whose pixels are drawn from its stickers (`renderStickers`), so the compositor, exports and
+ * every layer operation see ordinary pixels.
+ *
+ * The stamps are our own procedural shapes (dot, star, heart, leaf, petal flower, confetti, splat,
+ * sparkle, ring), each with a little shading and a seeded paper-like texture, so no artwork is
+ * bundled. The spray (`StickerSpray`) is deterministic: the same points, seed and brush give the
+ * same stickers.
+ */
+
+type StampKind = 'dot' | 'star' | 'heart' | 'leaf' | 'flower' | 'confetti' | 'splat' | 'sparkle' | 'ring';
+declare const STAMP_KINDS: readonly StampKind[];
+/** One sticker (document pixels). */
+interface Sticker {
+    id: string;
+    stamp: StampKind;
+    x: number;
+    y: number;
+    /** Diameter in pixels. */
+    size: number;
+    /** Degrees clockwise. */
+    rotation: number;
+    /** #rrggbb */
+    color: string;
+    /** 0..1 */
+    opacity: number;
+    /** Texture seed. */
+    seed: number;
+}
+/** Sticker spray settings (each 0..1 unless noted). */
+interface StickerSettings {
+    /** The stamps to spray (picked at random per sticker). */
+    stamps: StampKind[];
+    /** Stickers per tip diameter of travel. */
+    density: number;
+    /** Random size change. */
+    sizeJitter: number;
+    /** Random turn, as a fraction of ±180°. */
+    rotationJitter: number;
+    /** How far from the path stickers land, in tip diameters (0..2). */
+    scatter: number;
+    /** Random colour change (hue and lightness). */
+    colorJitter: number;
+}
+declare const DEFAULT_STICKER: Readonly<StickerSettings>;
+declare function normalizeStickerSettings(raw?: Partial<StickerSettings>, base?: StickerSettings): StickerSettings;
+/**
+ * Coverage of a stamp at a point (u, v) of its unit square (−1..1, y down), 0..1, before shading.
+ * `t` is the sticker's seed for shapes with random parts (splat, confetti).
+ */
+declare function stampCoverage(kind: StampKind, u: number, v: number, t: number): number;
+/** The pixel rectangle a sticker covers. */
+declare function stickerRect(s: Sticker): RasterRect;
+/**
+ * Draws one sticker through a `TileMedium` (straight source-over): the stamp's coverage, lit a
+ * little from the top left and given a fine seeded texture, in its colour and opacity.
+ */
+declare function drawSticker(medium: TileMedium, s: Sticker): RasterRect;
+interface StickerSprayInit {
+    brush: PaintBrush;
+    target: PaintTileTarget;
+    /** The paint colour #rrggbb. */
+    color: string;
+    seed: number;
+    copies: readonly StrokeCopy[];
+    /** The next sticker number on the layer (ids `st<n>`). */
+    nextId: number;
+    /** Gradient paint (resolved): each sticker takes its dab's colour (across the tip: by its offset). */
+    paint?: PaintGradientSource | null;
+}
+/** A sticker-spray stroke: drops stickers along the path and draws them as it goes. */
+declare class StickerSpray {
+    readonly init: StickerSprayInit;
+    dabCount: number;
+    readonly stickers: Sticker[];
+    private readonly smoother;
+    private readonly walkers;
+    private readonly copies;
+    private readonly medium;
+    private lastRaw;
+    private lastFed;
+    private next;
+    constructor(init: StickerSprayInit);
+    push(points: readonly PenPoint[]): RasterRect[];
+    finish(): RasterRect[];
+    private drop;
+    private sampler;
+    /** A sticker's colour: the paint colour, or gradient paint at its dab (`dx`, `dy` from the dab's centre). */
+    private colorAt;
+}
+/** A sticker list rendered over a transparent layer, through a tile target. */
+declare function renderStickers(stickers: readonly Sticker[], target: PaintTileTarget): void;
+/** Checks and rounds a sticker change; throws a sentence naming the bad field. */
+declare function normalizeStickerUpdate(u: Partial<Omit<Sticker, 'id'>>): Partial<Omit<Sticker, 'id'>>;
+/** A sticker layer's pixels: its stickers drawn bottom first over a transparent layer. */
+declare function stickerSurface(stickers: readonly Sticker[]): TiledSurface;
+
+/**
+ * Procedural brush engines: marks made by small simulations driven by the pen, rather than by
+ * stamping the tip.
+ *
+ * - **Particle brushes** (`engine: 'particle'`): a handful of particles follow the pen by their own
+ *   rules. `string`: strands of masses on springs, dragged behind the pen like hair or wet string;
+ *   `spring`: each particle tied to the pen by a spring, overshooting and wobbling; `orbit`:
+ *   particles circling the pen (spirograph curls); `flow`: particles thrown off the pen and carried
+ *   by a swirling flow field until they fade. Each is drawn as `dot`s, a continuous `line`, or a
+ *   `sequence` of beads spaced along its path.
+ * - **Bristle brushes** (`engine: 'bristle'`): a tuft of bristles, each its own thin line. Pressure
+ *   splays the tuft, tilt flattens it, and bristles lag behind the tip by their stiffness, so they
+ *   bend into curves at turns; each bristle carries its own paint and runs dry at its own pace, so
+ *   long strokes break into dry-brush streaks.
+ *
+ * Both are deterministic (seeded) and step the simulation by distance travelled, not by how the
+ * input was sampled, so a replay paints the same marks. They build up a `CoverageMap` like the dab
+ * engine, so opacity, blend modes, locks, stencils and symmetry work as for any dry brush.
+ */
+
+interface ProceduralStrokeOptions {
+    grain: PaperGrain | null;
+    paperDepth: number;
+    seed?: number;
+    copies?: readonly StrokeCopy[];
+    /** Gradient paint (resolved): each mark takes the colour of the pen dab that made it. */
+    paint?: PaintGradientSource | null;
+}
+/** What a coverage-building stroke engine provides to the stroke session. */
+interface CoverageStroke {
+    readonly coverage: CoverageMap;
+    dabCount: number;
+    push(points: readonly PenPoint[]): RasterRect[];
+    finish(): RasterRect[];
+}
+/** Shared plumbing: smoothing, the dab walk per copy (for size, pressure, direction), grain, and stamping marks. */
+declare abstract class MarkStroke implements CoverageStroke {
+    readonly brush: PaintBrush;
+    protected readonly options: ProceduralStrokeOptions;
+    readonly coverage: CoverageMap;
+    dabCount: number;
+    protected readonly smoother: PenSmoother;
+    protected readonly copies: readonly StrokeCopy[];
+    protected readonly walkers: PenDabWalker[];
+    protected readonly depth: number;
+    private buf;
+    private lastRaw;
+    private lastFed;
+    protected readonly seed: number;
+    private readonly sampler;
+    private readonly tipTable;
+    /** The pen dab the marks being made belong to, and its gradient colour. */
+    private pen;
+    private penColor;
+    constructor(brush: PaintBrush, options: ProceduralStrokeOptions);
+    push(points: readonly PenPoint[]): RasterRect[];
+    private step;
+    /** The colour of a mark at (x, y): its pen dab's, or across the tip by its offset from the pen. */
+    private markColor;
+    finish(): RasterRect[];
+    /** One simulation step of copy `copy` with the pen at dab `d`. */
+    protected abstract advance(copy: number, d: PenDab, rects: RasterRect[]): void;
+    /** Stamps one round mark of radius `r` at (x, y) with flow `alpha` towards `opacity`. */
+    protected mark(x: number, y: number, r: number, alpha: number, opacity: number, pressure: number, rects: RasterRect[]): void;
+    /** Marks along a segment, spaced by a fraction of the radius. */
+    protected segment(x0: number, y0: number, x1: number, y1: number, r: number, alpha: number, opacity: number, pressure: number, rects: RasterRect[]): void;
+}
+type ParticleKind = 'string' | 'spring' | 'orbit' | 'flow';
+declare const PARTICLE_KINDS: readonly ParticleKind[];
+type ParticleRender = 'dot' | 'line' | 'sequence';
+declare const PARTICLE_RENDERS: readonly ParticleRender[];
+/** Particle engine settings (each 0..1 unless noted). */
+interface ParticleSettings {
+    kind: ParticleKind;
+    render: ParticleRender;
+    /** Particles, 1..64. */
+    count: number;
+    /** Mark size as a fraction of the tip size. */
+    size: number;
+    /** How far apart the particles start, as a fraction of the tip size. */
+    spread: number;
+    /** Spring and string stiffness (stiff follows closely; soft swings wide). */
+    stiffness: number;
+    /** How quickly motion dies down. */
+    damping: number;
+    /** Orbit and flow speed. */
+    speed: number;
+    /** Pull downwards (−1 up .. 1 down). */
+    gravity: number;
+    /** Flow particles' lifetime. */
+    life: number;
+    /** Sequence: spacing of the beads along each path. */
+    interval: number;
+}
+declare const DEFAULT_PARTICLE: Readonly<ParticleSettings>;
+declare function normalizeParticle(raw?: Partial<ParticleSettings>, base?: ParticleSettings): ParticleSettings;
+/** A particle-brush stroke. */
+declare class ParticleStroke extends MarkStroke {
+    private readonly sets;
+    private readonly s;
+    private spawn;
+    constructor(brush: PaintBrush, options: ProceduralStrokeOptions);
+    private init;
+    protected advance(copy: number, d: PenDab, rects: RasterRect[]): void;
+}
+/** Bristle engine settings (each 0..1 unless noted). */
+interface BristleSettings {
+    /** Bristles in the tuft, 3..128. */
+    count: number;
+    /** Stiff bristles follow the tip; soft ones lag and bend into curves at turns. */
+    stiffness: number;
+    /** How far pressure spreads the tuft. */
+    splay: number;
+    /** Width of each bristle's line as a fraction of the tip size. */
+    thickness: number;
+    /** Paint per bristle: 1 never runs dry; lower, bristles run out along the stroke (dry brush). */
+    load: number;
+    /** Random variation between bristles (length, paint, position). */
+    jitter: number;
+}
+declare const DEFAULT_BRISTLE: Readonly<BristleSettings>;
+declare function normalizeBristle(raw?: Partial<BristleSettings>, base?: BristleSettings): BristleSettings;
+/** A bristle-brush stroke: every bristle draws its own line. */
+declare class BristleStroke extends MarkStroke {
+    private readonly tufts;
+    private readonly s;
+    constructor(brush: PaintBrush, options: ProceduralStrokeOptions);
+    protected advance(copy: number, d: PenDab, rects: RasterRect[]): void;
+}
+
+/**
+ * Paint editor brushes: the shared engine's tip settings (`@pixerate/editor/paint`) plus what a
+ * natural-media brush adds: paper grain response, pen dynamics (pressure, tilt, barrel rotation,
+ * velocity), separate pressure smoothing, a rotation mode, jitter, and Mixer Brush settings for
+ * the blending brushes. The built-in presets are our own settings; none come from another product.
+ */
+
+/**
+ * How a brush makes marks: `dab` (dabs into a stroke buffer, or dab by dab through the pick-up /
+ * mix exchange when its behaviour asks for it), `eraser` (removes alpha), `mixer` (the Mixer
+ * Brush), `blender` (mixes the colours under and near the tip) or `smudge` (drags paint along).
+ */
+type PaintBrushEngine = 'dab' | 'eraser' | 'mixer' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker';
+declare const PAINT_BRUSH_ENGINES: readonly PaintBrushEngine[];
+type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'paint' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'watercolor' | 'wet-tool' | 'oil' | 'impasto' | 'procedural' | 'bristle' | 'sticker' | 'custom';
+declare const PAINT_BRUSH_CATEGORIES: readonly PaintBrushCategory[];
+/**
+ * What a wet brush does to the wet layer: `paint` (water and pigment), `water` (clear water;
+ * with `rewet` it lifts dried paint), `dry` (a hair dryer: takes water, the pigment settles),
+ * `blow` (pushes the water along the stroke), `blend` (evens out the wet pigment under the tip),
+ * `smudge` (drags wet paint along) or `blot` (a tissue: takes up wet paint).
+ */
+type WetTool = 'paint' | 'water' | 'dry' | 'blow' | 'blend' | 'smudge' | 'blot';
+declare const WET_TOOLS: readonly WetTool[];
+/**
+ * The wet medium a wet brush paints: its layer takes the medium's wet settings the first time it
+ * holds wet paint (`watercolor`: runny, dries in seconds, granulates and darkens at edges;
+ * `gouache`: opaque, flatter; `oil`: thick, barely flows, stays wet for a long time and blends into
+ * the wet paint it meets).
+ */
+type WetMediumKind = 'watercolor' | 'gouache' | 'oil';
+declare const WET_MEDIA: readonly WetMediumKind[];
+/** Wet engine settings, each 0..1. */
+interface WetBrushSettings {
+    tool: WetTool;
+    /** Water the brush lays down (wetness): 0.2 a damp brush, 1 a dripping one. */
+    water: number;
+    /** Pigment concentration: 0 clear water .. 1 paint straight from the tube. */
+    pigment: number;
+    /** Body: 0 a transparent watercolour .. 1 opaque gouache that hides what is under it. */
+    body: number;
+    /** Strength of the dry, blow, blend, smudge and blot tools. */
+    strength: number;
+    /** How much dried paint the water lifts again (re-wetting): 0 none (staining) .. 1. */
+    rewet: number;
+    /** The medium (its layer's wet settings the first time it holds wet paint). */
+    medium: WetMediumKind;
+    /** Paint loading: 1 never runs out; lower, the brush runs dry along a long stroke (reload each stroke). */
+    load: number;
+    /** Thinner (water for watercolour, solvent for oil): thins the paint, so it is more transparent and runnier. */
+    thinner: number;
+}
+declare const DEFAULT_WET_BRUSH: Readonly<WetBrushSettings>;
+declare function normalizeWetBrush(raw?: Partial<WetBrushSettings>, base?: WetBrushSettings): WetBrushSettings;
+/**
+ * What an impasto brush does on a thick-paint layer: `brush` (paint with body: colour and relief),
+ * `tube` (squeezes blobs of paint straight from the tube), `knife` (a palette knife: scrapes the
+ * relief flat and smears the paint along), `roller` (a flat, even band with a stipple), `gloop`
+ * (a thick, glossy, rounded line).
+ */
+type ImpastoTool = 'brush' | 'tube' | 'knife' | 'roller' | 'gloop';
+declare const IMPASTO_TOOLS: readonly ImpastoTool[];
+/** Impasto engine settings, each 0..1. */
+interface ImpastoSettings {
+    tool: ImpastoTool;
+    /** How thick the paint stands up (relief per stroke). */
+    thickness: number;
+    /** Shine of the paint when lit (0 matte .. 1 wet-looking gloss). */
+    gloss: number;
+    /** Metallic paint: highlights take the paint's colour (gold, copper, silver). */
+    metallic: number;
+    /** Paint loading: 1 never runs out; lower, the stroke thins and fades as the brush empties. */
+    load: number;
+    /** Thinner: flatter, more transparent paint that levels out. */
+    thinner: number;
+    /** Knife and brush: how much of the paint under the tool is dragged along (0..1). */
+    drag: number;
+}
+declare const DEFAULT_IMPASTO: Readonly<ImpastoSettings>;
+declare function normalizeImpasto(raw?: Partial<ImpastoSettings>, base?: ImpastoSettings): ImpastoSettings;
+/** Multi-coloured brush: `tip` lays the colours across the tip, `dab` changes colour from dab to dab. */
+type MultiColorMode = 'off' | 'tip' | 'dab';
+declare const MULTI_COLOR_MODES: readonly MultiColorMode[];
+interface MultiColorSettings {
+    /** `off` (default), `tip` (the colours side by side across the tip, like a brush loaded with several paints; the stripes follow the stroke) or `dab` (the colour changes along the stroke). */
+    mode: MultiColorMode;
+    /** 2..8 colours #rrggbb. Fewer than 2: the paint colour and the secondary colour. */
+    colors: string[];
+    /** `dab` mode: `sequence` (default) runs through the colours in order, blending between them; `random` picks one per run of dabs (seeded, so replays match). */
+    order: 'sequence' | 'random';
+    /** `dab` mode: dabs per colour, 1..500 (default 12). */
+    length: number;
+    /** How softly neighbouring colours blend, 0 (hard stripes or steps) .. 1 (smooth gradient, default). */
+    softness: number;
+}
+declare const DEFAULT_MULTI_COLOR: Readonly<MultiColorSettings>;
+/**
+ * How a brush handles paint on the canvas. The pick-up / mix ratios are the shared exchange's
+ * (`@pixerate/editor/paint` `PaintExchange`); wet media will use the same ones. On a Mixer Brush
+ * they are its `mixer.wet`, `mixer.mix`, `!mixer.cleanEachStroke` and `mixer.mixing`, kept in sync.
+ */
+interface BrushBehavior {
+    /** Pick-up ratio, 0..1: how much of the paint under each dab the brush lifts and carries (0: none, default). */
+    pickup: number;
+    /** Mix ratio, 0..1: how much of the carried paint goes into what the brush lays down, against its own colour (default 0.5). */
+    mix: number;
+    /** Dirty brush: keep the carried paint after the stroke, so the next stroke starts with the last colour the brush touched (default false). */
+    dirty: boolean;
+    /** How picked-up paint, multi-colour gradients and the deposit mix: `pigment` (default, Kubelka-Munk) or `rgb`. */
+    mixing: MixingModel;
+    /** Multi-coloured brush. */
+    multicolor: MultiColorSettings;
+}
+declare const DEFAULT_BEHAVIOR: Readonly<BrushBehavior>;
+/** What turns the tip: a fixed angle, the direction of the stroke, or the pen's barrel rotation. */
+type BrushRotation = 'fixed' | 'stroke' | 'barrel';
+declare const BRUSH_ROTATIONS: readonly BrushRotation[];
+/** Pen dynamics and jitter. Every amount is 0 (off) .. 1 unless noted. */
+interface BrushDynamics {
+    /** Size at zero pressure as a fraction of the full size, when pressure controls size (default 0). */
+    minSize: number;
+    /** How much pressure scales flow (default 0). */
+    pressureFlow: number;
+    /** Laying the pen down widens the tip, up to 2.5× (default 0). */
+    tiltSize: number;
+    /** Laying the pen down flattens the tip along the tilt direction (default 0). */
+    tiltRoundness: number;
+    /** Laying the pen down lightens the mark, as when shading with the side of a pencil (default 0). */
+    tiltOpacity: number;
+    /** -1..1: positive grows the tip when the pen moves fast, negative thins it (default 0). */
+    velocitySize: number;
+    /** -1..1: positive darkens fast marks, negative lightens them (default 0). */
+    velocityOpacity: number;
+    /** Random size change per dab (default 0). */
+    sizeJitter: number;
+    /** Random angle per dab, as a fraction of ±180° (default 0). */
+    angleJitter: number;
+    /** Random opacity drop per dab (default 0). */
+    opacityJitter: number;
+    /** Random offset across the stroke in diameters, 0..4 (default 0). */
+    scatter: number;
+}
+declare const DEFAULT_DYNAMICS: Readonly<BrushDynamics>;
+interface PaintBrush {
+    /** Library id (lowercase letters, digits and dashes). */
+    id: string;
+    name: string;
+    category: PaintBrushCategory;
+    engine: PaintBrushEngine;
+    /** The shared engine's tip: size, hardness, spacing, angle, roundness, opacity, flow, position smoothing, pressure to size / opacity, blend. */
+    tip: BrushSettings;
+    /** How strongly the mark follows the paper grain, 0 (ignores it) .. 1 (catches only the peaks at light pressure). */
+    grain: number;
+    /** Pressure smoothing 0..0.95, separate from the tip's position smoothing (default 0). */
+    pressureSmoothing: number;
+    rotation: BrushRotation;
+    dynamics: BrushDynamics;
+    /** Mixer engine only: the Mixer Brush settings. */
+    mixer: MixerSettings;
+    /** Mixer engine only: load the current colour each stroke (false: a smudge or blender that only moves paint). */
+    loadsColor: boolean;
+    /** Pick-up and mix ratios, dirty brush and multi-colour (dab and mixer engines). */
+    behavior: BrushBehavior;
+    /** Blender engine only: strength, blend distance and mixing. */
+    blender: BlenderSettings;
+    /** Smudge engine only: strength, length and mixing. */
+    smudge: SmudgeSettings;
+    /** Wet engine only: the wet tool, water, pigment, body and strength. */
+    wet: WetBrushSettings;
+    /** Impasto engine only: the tool, thickness, gloss, metallic, loading, thinner and drag. */
+    impasto: ImpastoSettings;
+    /** Particle engine only: the particles' kind, how they are drawn, and their physics. */
+    particle: ParticleSettings;
+    /** Bristle engine only: the tuft. */
+    bristle: BristleSettings;
+    /** Sticker engine only: the stamps and how they are sprayed. */
+    sticker: StickerSettings;
+    /**
+     * The brush's own gradient paint (`@pixerate/editor/paint` `PaintGradientSource`), used instead
+     * of the editor's paint; `null` (default): the editor's paint. Stops may be `paint` / `secondary`
+     * (the editor's two colours). This is what the multi-colour brush became.
+     */
+    paint: PaintGradientSource | null;
+    /** True for the built-in presets (they cannot be removed or overwritten). */
+    builtin?: boolean;
+}
+declare function normalizeDynamics(raw?: Partial<BrushDynamics>, base?: BrushDynamics): BrushDynamics;
+declare const BRUSH_ID: RegExp;
+declare function normalizeMultiColor(raw?: Partial<MultiColorSettings>, base?: MultiColorSettings): MultiColorSettings;
+/** Behaviour input: any subset, with a partial multi-colour block. */
+type BrushBehaviorInput = Partial<Omit<BrushBehavior, 'multicolor'>> & {
+    multicolor?: Partial<MultiColorSettings>;
+};
+declare function normalizeBehavior(raw?: BrushBehaviorInput, base?: BrushBehavior): BrushBehavior;
+/** Brush settings to change or read: any subset of a brush and of its blocks. */
+type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint'>> & {
+    /** A gradient (or `null` for the editor's paint); a plain colour source clears it. */
+    paint?: PaintSource | null;
+    tip?: Partial<BrushSettings>;
+    dynamics?: Partial<BrushDynamics>;
+    mixer?: Partial<MixerSettings>;
+    behavior?: BrushBehaviorInput;
+    blender?: Partial<BlenderSettings>;
+    smudge?: Partial<SmudgeSettings>;
+    wet?: Partial<WetBrushSettings>;
+    impasto?: Partial<ImpastoSettings>;
+    particle?: Partial<ParticleSettings>;
+    bristle?: Partial<BristleSettings>;
+    sticker?: Partial<StickerSettings>;
+};
+/** Whether a brush can pick paint up from the canvas (the pick-up / mix ratios apply): dab, mixer and wet brushes. */
+declare function isWetCapable(brush: Pick<PaintBrush, 'engine'>): boolean;
+/** Whether a brush paints wet media (on the layer's wet layer). */
+declare function isWetBrush(brush: Pick<PaintBrush, 'engine'>): boolean;
+/**
+ * Whether a dab brush paints dab by dab through the exchange (it picks up paint or paints a
+ * gradient) instead of building one coverage buffer of one colour.
+ */
+declare function usesPaintExchange(brush: PaintBrush, gradient?: boolean): boolean;
+/** Whether strokes of a brush paint colour, so gradient paint applies (not erasers, blenders, smudges or the wet tools other than paint). */
+declare function brushTakesPaint(brush: Pick<PaintBrush, 'engine' | 'loadsColor' | 'wet'>): boolean;
+/**
+ * The multi-colour settings a gradient paints the same as (the inverse of `multiColorToPaint`), or
+ * `null` when the gradient has no multi-colour equivalent. Brushes report it as
+ * `behavior.multicolor`, so older readers keep working.
+ */
+declare function paintToMultiColor(g: PaintGradientSource | null): MultiColorSettings | null;
+/**
+ * The gradient paint a multi-coloured brush (`behavior.multicolor`, before gradient paint) paints
+ * the same pixels with: `tip` → `across-tip`; `dab` in sequence → `distance` in dabs, repeating
+ * through the colours and back to the first; `dab` at random → `random` per run of dabs, with hard
+ * stops. Without 2 colours of its own it uses the editor's paint and second colours.
+ */
+declare function multiColorToPaint(mc: MultiColorSettings, mixing: MixingModel): PaintGradientSource | null;
+/** A brush with every field in range; missing fields come from `base` (default: a plain round dab brush). */
+declare function normalizePaintBrush(raw?: PaintBrushInput, base?: PaintBrush): PaintBrush;
+/** The built-in brush library. */
+declare const BUILTIN_BRUSHES: readonly PaintBrush[];
+declare const DEFAULT_BRUSH_ID = "pencil-6b";
+
+/** A brush as plain JSON (for export, agents and saved libraries): no `builtin` flag. */
+declare function brushToJSON(brush: PaintBrush): Omit<PaintBrush, 'builtin'>;
+/** The JSON file a brush library exports to and imports from. */
+interface BrushLibraryFile {
+    format: 'pixerate-brushes';
+    version: 1;
+    brushes: Array<Omit<PaintBrush, 'builtin'>>;
+}
+/**
+ * Brushes read from a brush library file (or a bare array of brushes). Each is normalised; ones
+ * without a valid id or name are reported in `problems` and skipped.
+ */
+declare function parseBrushLibrary(raw: unknown, problems?: string[]): PaintBrush[];
+
+export { type PaintBrushCategory as $, DEFAULT_WET_BRUSH as A, type BrushLibraryFile as B, type CoverageStroke as C, DEFAULT_BEHAVIOR as D, DryStroke as E, type DryStrokeOptions as F, GRAIN_PATTERNS as G, GRAIN_TILE as H, type ImpastoTool as I, type GrainPattern as J, type GrainTuning as K, IDENTITY_COPY as L, type MultiColorSettings as M, IMPASTO_TOOLS as N, type ImpastoSettings as O, type PaintBrush as P, type Linear2 as Q, MULTI_COLOR_MODES as R, type StrokeCopy as S, type MultiColorMode as T, PAINT_BRUSH_CATEGORIES as U, PAINT_BRUSH_ENGINES as V, type WetMediumKind as W, PAPER_FAMILIES as X, PAPER_LIBRARY as Y, PARTICLE_KINDS as Z, PARTICLE_RENDERS as _, type PenPoint as a, type PaintBrushEngine as a0, type PaperFamily as a1, type PaperTiling as a2, type ParticleSettings as a3, ParticleStroke as a4, type PenDab as a5, PenDabWalker as a6, PenSmoother as a7, type ProceduralStrokeOptions as a8, STAMP_KINDS as a9, normalizeStickerUpdate as aA, normalizeWetBrush as aB, paintToMultiColor as aC, paperPreset as aD, parseBrushLibrary as aE, penOrientation as aF, renderPaper as aG, renderStickers as aH, stampCoverage as aI, stickerRect as aJ, stickerSurface as aK, tiltToOrientation as aL, toStrokePoint as aM, usesPaintExchange as aN, type StickerSettings as aa, StickerSpray as ab, type StickerSprayInit as ac, WET_MEDIA as ad, WET_TOOLS as ae, type WetBrushSettings as af, brushTakesPaint as ag, brushToJSON as ah, clonePaper as ai, drawSticker as aj, grainCatch as ak, grainHeights as al, hexToRgb8 as am, isWetBrush as an, isWetCapable as ao, mixerTip as ap, multiColorToPaint as aq, normalizeBehavior as ar, normalizeBristle as as, normalizeDynamics as at, normalizeImpasto as au, normalizeMultiColor as av, normalizePaintBrush as aw, normalizePaper as ax, normalizeParticle as ay, normalizeStickerSettings as az, PaperGrain as b, type PaperSettings as c, type Sticker as d, type PaintBrushInput as e, type ParticleKind as f, type ParticleRender as g, type StampKind as h, type WetTool as i, BRUSH_ID as j, BRUSH_ROTATIONS as k, BUILTIN_BRUSHES as l, type BristleSettings as m, BristleStroke as n, type BrushBehavior as o, type BrushBehaviorInput as p, type BrushDynamics as q, type BrushRotation as r, DEFAULT_BRISTLE as s, DEFAULT_BRUSH_ID as t, DEFAULT_DYNAMICS as u, DEFAULT_IMPASTO as v, DEFAULT_MULTI_COLOR as w, DEFAULT_PAPER as x, DEFAULT_PARTICLE as y, DEFAULT_STICKER as z };