@pixerate/editor 0.265.0 → 0.266.1

package/dist/image-editor/index.js

@@ -8,7 +8,7 @@ import {
   parseOpenTypeFont,
   removeAnchorsKeepingShape,
   traceField
-} from "../chunk-BLR4KWYQ.js";
+} from "../chunk-EZOJBP4D.js";
 import {
   ADJUSTMENT_KEYS,
   ADJUSTMENT_KINDS,
@@ -410,7 +410,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-WY23AUCA.js";
+} from "../chunk-R44Y3EFS.js";
 import {
   ColorGmm,
   DEFAULT_REFINE_EDGE_PARAMS,
@@ -770,14 +770,14 @@ import {
   warpMeshParamAt,
   warpMeshRows,
   warpPresetMesh
-} from "../chunk-7PW6VCNW.js";
+} from "../chunk-T2LDTEXK.js";
 import {
   IMAGE_PROFILE,
   checkBrush,
   closest,
   createBrushLibrary,
   resolveBrush
-} from "../chunk-J4SGJCPW.js";
+} from "../chunk-CIJBSUM5.js";
 import "../chunk-ACFSFUQH.js";
 import "../chunk-M6DNZNVY.js";
 import {

package/dist/paint-editor/brush-model.d.cts

@@ -0,0 +1,273 @@
+/**
+ * The flat engine brush (`PaintBrush`) the paint engine reads, its settings and
+ * `normalizePaintBrush`. Kept apart from the built-in library (`./brushes`) so the facet
+ * resolver (`brushes/resolve`) can import it while `BUILTIN_BRUSHES` resolves the facet presets.
+ */
+import { type BrushSettings } from '../paint/brush.cjs';
+import { type BlenderSettings, type SmudgeSettings } from '../paint/blending.cjs';
+import type { MixingModel } from '../paint/exchange.cjs';
+import { type PaintGradientSource, type PaintSource } from '../paint/gradient-paint.cjs';
+import { type MixerSettings } from '../paint/mixer.cjs';
+import { type BristleSettings, type ParticleSettings, type StickerSettings } from './mark-settings.cjs';
+/**
+ * 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).
+ */
+export type PaintBrushEngine = 'dab' | 'eraser' | 'mixer' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker';
+export declare const PAINT_BRUSH_ENGINES: readonly PaintBrushEngine[];
+export type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'paint' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'watercolor' | 'wet-tool' | 'oil' | 'impasto' | 'procedural' | 'bristle' | 'sticker' | 'light' | 'custom';
+export 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).
+ */
+export type WetTool = 'paint' | 'water' | 'dry' | 'blow' | 'blend' | 'smudge' | 'blot';
+export 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).
+ */
+export type WetMediumKind = 'watercolor' | 'gouache' | 'oil';
+export declare const WET_MEDIA: readonly WetMediumKind[];
+/** Wet engine settings, each 0..1. */
+export 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;
+}
+export declare const DEFAULT_WET_BRUSH: Readonly<WetBrushSettings>;
+export 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).
+ */
+export type ImpastoTool = 'brush' | 'tube' | 'knife' | 'roller' | 'gloop';
+export declare const IMPASTO_TOOLS: readonly ImpastoTool[];
+/** Impasto engine settings, each 0..1. */
+export 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;
+    /** Light paint: the bead's light is stronger where its surface turns away, as on backlit glass (0..1, default 0). */
+    rim: number;
+    /** Light paint: the middle of a bead lets the layers below show through, its edges stay solid (0..1, default 0). */
+    clarity: number;
+}
+export declare const DEFAULT_IMPASTO: Readonly<ImpastoSettings>;
+/** Light paint: how much light a brush lays with its colour (see `doc.light`). */
+export interface LightSettings {
+    /** Light each dab lays, scaled by its coverage and flow (0..1, default 0: none). */
+    amount: number;
+    /** Pressure scales the light (default false). */
+    pressure: boolean;
+}
+export declare const DEFAULT_LIGHT: Readonly<LightSettings>;
+export declare function normalizeLight(raw?: Partial<LightSettings>, base?: LightSettings): LightSettings;
+export 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. */
+export type MultiColorMode = 'off' | 'tip' | 'dab';
+export declare const MULTI_COLOR_MODES: readonly MultiColorMode[];
+export 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;
+}
+export 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.
+ */
+export 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;
+}
+export declare const DEFAULT_BEHAVIOR: Readonly<BrushBehavior>;
+/** What turns the tip: a fixed angle, the direction of the stroke, or the pen's barrel rotation. */
+export type BrushRotation = 'fixed' | 'stroke' | 'barrel';
+export declare const BRUSH_ROTATIONS: readonly BrushRotation[];
+/** Pen dynamics and jitter. Every amount is 0 (off) .. 1 unless noted. */
+export 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;
+}
+export declare const DEFAULT_DYNAMICS: Readonly<BrushDynamics>;
+export 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;
+    /** Light paint: the light it lays with its colour (amount 0: none). */
+    light: LightSettings;
+    /**
+     * Dab engine: a stamp tip. Each dab (and each spray droplet) is this sticker's shape, an editor
+     * stamp (`editor:star`) or any sticker ref from the sticker library, laid in the paint colour;
+     * `null` (default): the round computed tip.
+     */
+    stamp: string | null;
+    /** Dab engine: spray marks. Each dab lays a seeded scatter of droplets across the tip; `null` (default): one mark per dab. */
+    spray: SpraySettings | null;
+    /**
+     * 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;
+}
+export declare function normalizeDynamics(raw?: Partial<BrushDynamics>, base?: BrushDynamics): BrushDynamics;
+export declare const BRUSH_ID: RegExp;
+export declare function normalizeMultiColor(raw?: Partial<MultiColorSettings>, base?: MultiColorSettings): MultiColorSettings;
+/** Behaviour input: any subset, with a partial multi-colour block. */
+export type BrushBehaviorInput = Partial<Omit<BrushBehavior, 'multicolor'>> & {
+    multicolor?: Partial<MultiColorSettings>;
+};
+export declare function normalizeBehavior(raw?: BrushBehaviorInput, base?: BrushBehavior): BrushBehavior;
+/** Brush settings to change or read: any subset of a brush and of its blocks. */
+/** Spray marks (dab engine). */
+export interface SpraySettings {
+    /** Droplets per dab: 1 + density × 31 (0..1, default 0.5). */
+    density: number;
+    /** Droplet size as a fraction of the tip size, 0.02..1 (default 0.12). */
+    size: number;
+}
+export declare const DEFAULT_SPRAY: Readonly<SpraySettings>;
+export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'spray'>> & {
+    spray?: Partial<SpraySettings> | null;
+    light?: Partial<LightSettings>;
+    /** 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. */
+export declare function isWetCapable(brush: Pick<PaintBrush, 'engine'>): boolean;
+/** Whether a brush paints wet media (on the layer's wet layer). */
+export 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.
+ */
+export 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). */
+export 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.
+ */
+export 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.
+ */
+export 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). */
+export declare function normalizePaintBrush(raw?: PaintBrushInput, base?: PaintBrush): PaintBrush;

package/dist/paint-editor/brush-model.d.ts

@@ -0,0 +1,273 @@
+/**
+ * The flat engine brush (`PaintBrush`) the paint engine reads, its settings and
+ * `normalizePaintBrush`. Kept apart from the built-in library (`./brushes`) so the facet
+ * resolver (`brushes/resolve`) can import it while `BUILTIN_BRUSHES` resolves the facet presets.
+ */
+import { type BrushSettings } from '../paint/brush.js';
+import { type BlenderSettings, type SmudgeSettings } from '../paint/blending.js';
+import type { MixingModel } from '../paint/exchange.js';
+import { type PaintGradientSource, type PaintSource } from '../paint/gradient-paint.js';
+import { type MixerSettings } from '../paint/mixer.js';
+import { type BristleSettings, type ParticleSettings, type StickerSettings } from './mark-settings.js';
+/**
+ * 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).
+ */
+export type PaintBrushEngine = 'dab' | 'eraser' | 'mixer' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker';
+export declare const PAINT_BRUSH_ENGINES: readonly PaintBrushEngine[];
+export type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'paint' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'watercolor' | 'wet-tool' | 'oil' | 'impasto' | 'procedural' | 'bristle' | 'sticker' | 'light' | 'custom';
+export 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).
+ */
+export type WetTool = 'paint' | 'water' | 'dry' | 'blow' | 'blend' | 'smudge' | 'blot';
+export 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).
+ */
+export type WetMediumKind = 'watercolor' | 'gouache' | 'oil';
+export declare const WET_MEDIA: readonly WetMediumKind[];
+/** Wet engine settings, each 0..1. */
+export 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;
+}
+export declare const DEFAULT_WET_BRUSH: Readonly<WetBrushSettings>;
+export 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).
+ */
+export type ImpastoTool = 'brush' | 'tube' | 'knife' | 'roller' | 'gloop';
+export declare const IMPASTO_TOOLS: readonly ImpastoTool[];
+/** Impasto engine settings, each 0..1. */
+export 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;
+    /** Light paint: the bead's light is stronger where its surface turns away, as on backlit glass (0..1, default 0). */
+    rim: number;
+    /** Light paint: the middle of a bead lets the layers below show through, its edges stay solid (0..1, default 0). */
+    clarity: number;
+}
+export declare const DEFAULT_IMPASTO: Readonly<ImpastoSettings>;
+/** Light paint: how much light a brush lays with its colour (see `doc.light`). */
+export interface LightSettings {
+    /** Light each dab lays, scaled by its coverage and flow (0..1, default 0: none). */
+    amount: number;
+    /** Pressure scales the light (default false). */
+    pressure: boolean;
+}
+export declare const DEFAULT_LIGHT: Readonly<LightSettings>;
+export declare function normalizeLight(raw?: Partial<LightSettings>, base?: LightSettings): LightSettings;
+export 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. */
+export type MultiColorMode = 'off' | 'tip' | 'dab';
+export declare const MULTI_COLOR_MODES: readonly MultiColorMode[];
+export 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;
+}
+export 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.
+ */
+export 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;
+}
+export declare const DEFAULT_BEHAVIOR: Readonly<BrushBehavior>;
+/** What turns the tip: a fixed angle, the direction of the stroke, or the pen's barrel rotation. */
+export type BrushRotation = 'fixed' | 'stroke' | 'barrel';
+export declare const BRUSH_ROTATIONS: readonly BrushRotation[];
+/** Pen dynamics and jitter. Every amount is 0 (off) .. 1 unless noted. */
+export 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;
+}
+export declare const DEFAULT_DYNAMICS: Readonly<BrushDynamics>;
+export 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;
+    /** Light paint: the light it lays with its colour (amount 0: none). */
+    light: LightSettings;
+    /**
+     * Dab engine: a stamp tip. Each dab (and each spray droplet) is this sticker's shape, an editor
+     * stamp (`editor:star`) or any sticker ref from the sticker library, laid in the paint colour;
+     * `null` (default): the round computed tip.
+     */
+    stamp: string | null;
+    /** Dab engine: spray marks. Each dab lays a seeded scatter of droplets across the tip; `null` (default): one mark per dab. */
+    spray: SpraySettings | null;
+    /**
+     * 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;
+}
+export declare function normalizeDynamics(raw?: Partial<BrushDynamics>, base?: BrushDynamics): BrushDynamics;
+export declare const BRUSH_ID: RegExp;
+export declare function normalizeMultiColor(raw?: Partial<MultiColorSettings>, base?: MultiColorSettings): MultiColorSettings;
+/** Behaviour input: any subset, with a partial multi-colour block. */
+export type BrushBehaviorInput = Partial<Omit<BrushBehavior, 'multicolor'>> & {
+    multicolor?: Partial<MultiColorSettings>;
+};
+export declare function normalizeBehavior(raw?: BrushBehaviorInput, base?: BrushBehavior): BrushBehavior;
+/** Brush settings to change or read: any subset of a brush and of its blocks. */
+/** Spray marks (dab engine). */
+export interface SpraySettings {
+    /** Droplets per dab: 1 + density × 31 (0..1, default 0.5). */
+    density: number;
+    /** Droplet size as a fraction of the tip size, 0.02..1 (default 0.12). */
+    size: number;
+}
+export declare const DEFAULT_SPRAY: Readonly<SpraySettings>;
+export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'spray'>> & {
+    spray?: Partial<SpraySettings> | null;
+    light?: Partial<LightSettings>;
+    /** 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. */
+export declare function isWetCapable(brush: Pick<PaintBrush, 'engine'>): boolean;
+/** Whether a brush paints wet media (on the layer's wet layer). */
+export 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.
+ */
+export 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). */
+export 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.
+ */
+export 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.
+ */
+export 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). */
+export declare function normalizePaintBrush(raw?: PaintBrushInput, base?: PaintBrush): PaintBrush;