@pixerate/editor 0.250.0 → 0.251.0

package/dist/brushes/migrate.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Version 1 brushes (`PaintBrush`, the flat engine form) to facet brushes. Files, documents and
+ * recorded strokes written before the facet model still load: each v1 brush becomes the sparse
+ * facet brush that resolves back to it.
+ *
+ * What the engine reads survives exactly. Settings of engine blocks the brush's engine never
+ * reads (a dab brush's mixer settings) are dropped, and the category is derived again
+ * (`resolveCategory`), so a v1 brush filed under a category its settings do not match moves.
+ */
+import { type PaintBrushInput } from '../paint-editor/brushes.cjs';
+import type { Brush } from './types.cjs';
+/**
+ * The facet brush a v1 brush (any `PaintBrush`, or the JSON of one) amounts to: its engine's
+ * settings, stored only where they differ from that engine's defaults.
+ * `resolveBrush(migrateBrushV1(b))` paints exactly as `b` does.
+ */
+export declare function migrateBrushV1(raw: PaintBrushInput): Brush;

package/dist/brushes/migrate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Version 1 brushes (`PaintBrush`, the flat engine form) to facet brushes. Files, documents and
+ * recorded strokes written before the facet model still load: each v1 brush becomes the sparse
+ * facet brush that resolves back to it.
+ *
+ * What the engine reads survives exactly. Settings of engine blocks the brush's engine never
+ * reads (a dab brush's mixer settings) are dropped, and the category is derived again
+ * (`resolveCategory`), so a v1 brush filed under a category its settings do not match moves.
+ */
+import { type PaintBrushInput } from '../paint-editor/brushes.js';
+import type { Brush } from './types.js';
+/**
+ * The facet brush a v1 brush (any `PaintBrush`, or the JSON of one) amounts to: its engine's
+ * settings, stored only where they differ from that engine's defaults.
+ * `resolveBrush(migrateBrushV1(b))` paints exactly as `b` does.
+ */
+export declare function migrateBrushV1(raw: PaintBrushInput): Brush;

package/dist/brushes/normalize.d.cts

@@ -0,0 +1,15 @@
+/**
+ * `normalizeBrushSpec`: a brush with every given field checked against `BRUSH_JSON_SCHEMA`. It
+ * stays sparse (missing fields are not filled in): numbers are clamped into range, integers
+ * rounded, unknown fields, bad values and facets the brush does not use are dropped, and each
+ * change is reported in `problems` so a caller (or an agent) sees what was fixed. Only an id,
+ * name or kind it cannot make sense of throws.
+ */
+import { type Brush, type BrushTool } from './types.cjs';
+/** The tools that work on the wet layer. */
+export declare const WET_BRUSH_TOOLS: readonly BrushTool[];
+/**
+ * A brush with every given field in range (see the module comment). Throws when the id, name or
+ * kind cannot be used; every other fix is reported in `problems`.
+ */
+export declare function normalizeBrushSpec(raw: unknown, problems?: string[]): Brush;

package/dist/brushes/normalize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `normalizeBrushSpec`: a brush with every given field checked against `BRUSH_JSON_SCHEMA`. It
+ * stays sparse (missing fields are not filled in): numbers are clamped into range, integers
+ * rounded, unknown fields, bad values and facets the brush does not use are dropped, and each
+ * change is reported in `problems` so a caller (or an agent) sees what was fixed. Only an id,
+ * name or kind it cannot make sense of throws.
+ */
+import { type Brush, type BrushTool } from './types.js';
+/** The tools that work on the wet layer. */
+export declare const WET_BRUSH_TOOLS: readonly BrushTool[];
+/**
+ * A brush with every given field in range (see the module comment). Throws when the id, name or
+ * kind cannot be used; every other fix is reported in `problems`.
+ */
+export declare function normalizeBrushSpec(raw: unknown, problems?: string[]): Brush;

package/dist/brushes/presets.d.cts

@@ -0,0 +1,12 @@
+/**
+ * The built-in brushes as facet specs. Each resolves (`resolveBrush`) to exactly the paint
+ * editor's built-in brush of the same id (`BUILTIN_BRUSHES`, which `tests/brushes.test.ts`
+ * checks), so the engine paints them as it always has. Medium and variety are new: they file
+ * each brush under what it is for browsing and filtering. Only what differs from the engine's
+ * defaults is written down.
+ *
+ * Our own settings; none come from another product.
+ */
+import type { Brush } from './types.cjs';
+/** The built-in brush library, in the paint editor's order. */
+export declare const BRUSH_PRESETS: readonly Brush[];

package/dist/brushes/presets.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The built-in brushes as facet specs. Each resolves (`resolveBrush`) to exactly the paint
+ * editor's built-in brush of the same id (`BUILTIN_BRUSHES`, which `tests/brushes.test.ts`
+ * checks), so the engine paints them as it always has. Medium and variety are new: they file
+ * each brush under what it is for browsing and filtering. Only what differs from the engine's
+ * defaults is written down.
+ *
+ * Our own settings; none come from another product.
+ */
+import type { Brush } from './types.js';
+/** The built-in brush library, in the paint editor's order. */
+export declare const BRUSH_PRESETS: readonly Brush[];

package/dist/brushes/resolve.d.cts

@@ -0,0 +1,56 @@
+/**
+ * From a facet `Brush` to the flat form the paint engine reads (`ResolvedBrush`, today's
+ * `PaintBrush`). The engine is derived from the tip, the marks and the behaviour
+ * (`resolveEngine`); the category the libraries group by is derived too (`resolveCategory`).
+ *
+ * `BRUSH_FIELDS` maps each facet field to the engine field it sets, for the engines that read it.
+ * `migrateBrushV1` reads the same map the other way, so the two directions cannot drift apart.
+ */
+import { type PaintBrushCategory, type PaintBrushEngine, type WetMediumKind, type WetTool } from '../paint-editor/brushes.cjs';
+import type { Brush, BrushTool, ResolvedBrush } from './types.cjs';
+/** One facet field and the engine field it sets. */
+export interface BrushField {
+    /** Dot path in the facet brush. */
+    facet: string;
+    /** Dot path in the resolved brush. */
+    engine: string;
+    /** The engines that read it. */
+    engines: readonly PaintBrushEngine[];
+    /** When the two forms differ: facet value → engine value, and back. */
+    map?: {
+        toEngine(v: unknown): unknown;
+        toFacet(v: unknown): unknown;
+    };
+    /** Read only on these tip shapes. */
+    shapes?: readonly string[];
+}
+/** Every facet field and where it lands in the resolved brush. */
+export declare const BRUSH_FIELDS: readonly BrushField[];
+/** The wet tool each wet-layer tool brush is. */
+export declare const WET_TOOL_OF: Readonly<Partial<Record<BrushTool, WetTool>>>;
+export declare function getPath(o: unknown, path: string): unknown;
+export declare function setPath(o: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * The engine that renders a brush: tools by what they do; marks by how they are laid
+ * (particles, objects), the tip (bristle), the surface (thick, wet) and the paint exchange (a
+ * reservoir makes a Mixer Brush); everything else paints dabs.
+ */
+export declare function resolveEngine(brush: Pick<Brush, 'kind' | 'tool' | 'tip' | 'marks' | 'behaviour'>): PaintBrushEngine;
+/** The wet medium a wet brush paints: `behaviour.wet.medium`, else its variety when that is a wet medium. */
+export declare function resolveWetMedium(brush: Pick<Brush, 'variety' | 'behaviour'>): WetMediumKind | undefined;
+/**
+ * The library category a brush is grouped under: tools by what they do; light brushes; then by
+ * engine (particles are procedural, objects stickers, bristle, thick impasto, wet oil or
+ * watercolour, the Mixer Brush); dab brushes by variety, then medium.
+ */
+export declare function resolveCategory(brush: Brush, engine?: PaintBrushEngine): PaintBrushCategory;
+export interface ResolveBrushOptions {
+    /** Mark the result built-in (a library's presets). */
+    builtin?: boolean;
+}
+/**
+ * The flat engine form of a brush. Missing fields take the engine's defaults, and every value is
+ * clamped into range, so any brush resolves (check it with `normalizeBrushSpec` first to hear
+ * what was out of range).
+ */
+export declare function resolveBrush(brush: Brush, options?: ResolveBrushOptions): ResolvedBrush;

package/dist/brushes/resolve.d.ts

@@ -0,0 +1,56 @@
+/**
+ * From a facet `Brush` to the flat form the paint engine reads (`ResolvedBrush`, today's
+ * `PaintBrush`). The engine is derived from the tip, the marks and the behaviour
+ * (`resolveEngine`); the category the libraries group by is derived too (`resolveCategory`).
+ *
+ * `BRUSH_FIELDS` maps each facet field to the engine field it sets, for the engines that read it.
+ * `migrateBrushV1` reads the same map the other way, so the two directions cannot drift apart.
+ */
+import { type PaintBrushCategory, type PaintBrushEngine, type WetMediumKind, type WetTool } from '../paint-editor/brushes.js';
+import type { Brush, BrushTool, ResolvedBrush } from './types.js';
+/** One facet field and the engine field it sets. */
+export interface BrushField {
+    /** Dot path in the facet brush. */
+    facet: string;
+    /** Dot path in the resolved brush. */
+    engine: string;
+    /** The engines that read it. */
+    engines: readonly PaintBrushEngine[];
+    /** When the two forms differ: facet value → engine value, and back. */
+    map?: {
+        toEngine(v: unknown): unknown;
+        toFacet(v: unknown): unknown;
+    };
+    /** Read only on these tip shapes. */
+    shapes?: readonly string[];
+}
+/** Every facet field and where it lands in the resolved brush. */
+export declare const BRUSH_FIELDS: readonly BrushField[];
+/** The wet tool each wet-layer tool brush is. */
+export declare const WET_TOOL_OF: Readonly<Partial<Record<BrushTool, WetTool>>>;
+export declare function getPath(o: unknown, path: string): unknown;
+export declare function setPath(o: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * The engine that renders a brush: tools by what they do; marks by how they are laid
+ * (particles, objects), the tip (bristle), the surface (thick, wet) and the paint exchange (a
+ * reservoir makes a Mixer Brush); everything else paints dabs.
+ */
+export declare function resolveEngine(brush: Pick<Brush, 'kind' | 'tool' | 'tip' | 'marks' | 'behaviour'>): PaintBrushEngine;
+/** The wet medium a wet brush paints: `behaviour.wet.medium`, else its variety when that is a wet medium. */
+export declare function resolveWetMedium(brush: Pick<Brush, 'variety' | 'behaviour'>): WetMediumKind | undefined;
+/**
+ * The library category a brush is grouped under: tools by what they do; light brushes; then by
+ * engine (particles are procedural, objects stickers, bristle, thick impasto, wet oil or
+ * watercolour, the Mixer Brush); dab brushes by variety, then medium.
+ */
+export declare function resolveCategory(brush: Brush, engine?: PaintBrushEngine): PaintBrushCategory;
+export interface ResolveBrushOptions {
+    /** Mark the result built-in (a library's presets). */
+    builtin?: boolean;
+}
+/**
+ * The flat engine form of a brush. Missing fields take the engine's defaults, and every value is
+ * clamped into range, so any brush resolves (check it with `normalizeBrushSpec` first to hear
+ * what was out of range).
+ */
+export declare function resolveBrush(brush: Brush, options?: ResolveBrushOptions): ResolvedBrush;

package/dist/brushes/schema.d.cts

@@ -0,0 +1,29 @@
+/**
+ * JSON Schema of a `Brush`: strict (`additionalProperties: false` at every level), every field
+ * described with its units and default. `normalizeBrushSpec` clamps and checks against the same
+ * ranges, so the schema, the normaliser and the engine agree.
+ */
+import type { JsonSchema } from '../tools/schema.cjs';
+/** Most colours in a brush's palette. */
+export declare const MAX_BRUSH_PALETTE = 16;
+/** Variety and tag ids: lowercase letters, digits and dashes. */
+export declare const BRUSH_WORD: RegExp;
+/** A sticker ref `provider:id`, or a bare editor stamp (read as `editor:<stamp>`). */
+export declare const BRUSH_STAMP_PATTERN: string;
+/** JSON Schema of a `Brush`. */
+export declare const BRUSH_JSON_SCHEMA: JsonSchema;
+/** The facet schemas, for tools that take one facet. */
+export declare const BRUSH_FACET_SCHEMAS: {
+    readonly tip: JsonSchema;
+    readonly marks: {
+        readonly continuous: JsonSchema;
+        readonly particles: JsonSchema;
+        readonly objects: JsonSchema;
+    };
+    readonly dynamics: JsonSchema;
+    readonly behaviour: JsonSchema;
+    readonly light: JsonSchema;
+    readonly motion: JsonSchema;
+    readonly colour: JsonSchema;
+    readonly paint: JsonSchema;
+};

package/dist/brushes/schema.d.ts

@@ -0,0 +1,29 @@
+/**
+ * JSON Schema of a `Brush`: strict (`additionalProperties: false` at every level), every field
+ * described with its units and default. `normalizeBrushSpec` clamps and checks against the same
+ * ranges, so the schema, the normaliser and the engine agree.
+ */
+import type { JsonSchema } from '../tools/schema.js';
+/** Most colours in a brush's palette. */
+export declare const MAX_BRUSH_PALETTE = 16;
+/** Variety and tag ids: lowercase letters, digits and dashes. */
+export declare const BRUSH_WORD: RegExp;
+/** A sticker ref `provider:id`, or a bare editor stamp (read as `editor:<stamp>`). */
+export declare const BRUSH_STAMP_PATTERN: string;
+/** JSON Schema of a `Brush`. */
+export declare const BRUSH_JSON_SCHEMA: JsonSchema;
+/** The facet schemas, for tools that take one facet. */
+export declare const BRUSH_FACET_SCHEMAS: {
+    readonly tip: JsonSchema;
+    readonly marks: {
+        readonly continuous: JsonSchema;
+        readonly particles: JsonSchema;
+        readonly objects: JsonSchema;
+    };
+    readonly dynamics: JsonSchema;
+    readonly behaviour: JsonSchema;
+    readonly light: JsonSchema;
+    readonly motion: JsonSchema;
+    readonly colour: JsonSchema;
+    readonly paint: JsonSchema;
+};

package/dist/brushes/types.d.cts

@@ -0,0 +1,323 @@
+/**
+ * The brush model: one brush type made of facets people and agents can reason about (what it is,
+ * its tip, how it lays marks, how it feels, what the material does, light, motion and colour).
+ * Every facet but identity and tip is optional and sparse: a missing field takes the default the
+ * engine has always used, so a brush stores only what makes it what it is.
+ *
+ * Medium and variety are descriptive (browsing, filtering). What the renderer does is decided by
+ * the tip, the marks and the behaviour: `resolveEngine` derives the engine, and `resolveBrush`
+ * turns a brush into the flat form the paint engine reads (`ResolvedBrush`).
+ *
+ * Type-only imports keep this module free of the renderers.
+ */
+import type { ColorValue } from '../color/dual.cjs';
+import type { PaintGradientSource } from '../paint/gradient-paint.cjs';
+import type { MixingModel } from '../paint/exchange.cjs';
+import type { BlendMode } from '../raster/blend.cjs';
+import type { BrushRotation, ImpastoTool, PaintBrush, WetMediumKind } from '../paint-editor/brushes.cjs';
+import type { PaintEffectPaint } from '../paint-editor/effect-paint.cjs';
+import type { DotRotation, DotTextureOrder, ParticleKind, ParticleRender, RibbonPairs } from '../paint-editor/mark-settings.cjs';
+import type { StickerRef } from '../stickers/types.cjs';
+/** `mark`: lays a material; `tool`: works on paint already down (erases, blends, smudges, wets…). */
+export type BrushKind = 'mark' | 'tool';
+export declare const BRUSH_KINDS: readonly BrushKind[];
+/** What a mark brush lays: wet or thick `paint`, `ink`, a `dry` medium (pencil, pastel, charcoal) or a `spray`. */
+export type BrushMedium = 'paint' | 'ink' | 'dry' | 'spray';
+export declare const BRUSH_MEDIA: readonly BrushMedium[];
+/** What a tool does to paint already down. */
+export type BrushTool = 'eraser' | 'blender' | 'smudge' | 'water' | 'dryer' | 'blow' | 'blot' | 'wet-blend' | 'wet-drag';
+export declare const BRUSH_TOOLS: readonly BrushTool[];
+/**
+ * The tip's shape. `round`, `flat` and `chisel` are ellipses (their `roundness` and `angle` set
+ * the ellipse; the name is for people); `bristle` is a tuft of bristles; `stamp` lays textured
+ * stamps (with `marks` `objects` or `particles`).
+ */
+export type BrushTipShape = 'round' | 'flat' | 'chisel' | 'bristle' | 'stamp';
+export declare const BRUSH_TIP_SHAPES: readonly BrushTipShape[];
+/** How the tip is laid along the path. */
+export type BrushMarksKind = 'continuous' | 'particles' | 'objects';
+export declare const BRUSH_MARKS_KINDS: readonly BrushMarksKind[];
+/** What the material does on the surface: stays where it lands (`dry`), flows and dries (`wet`) or stands up in relief (`thick`). */
+export type BrushSurface = 'dry' | 'wet' | 'thick';
+export declare const BRUSH_SURFACES: readonly BrushSurface[];
+/**
+ * A sticker a `stamp` tip lays: a sticker ref `provider:id` (`editor:star`, or a host library's
+ * sticker). Objects marks take any sticker; particle marks only the editor's own stamps.
+ */
+export type BrushStamp = StickerRef;
+/** The tuft of a `bristle` tip (each 0..1 unless noted). */
+export interface BrushBristles {
+    /** Bristles in the tuft, 3..128 (default 32). */
+    count?: number;
+    /** Stiff bristles follow the tip; soft ones lag and bend into curves at turns (default 0.5). */
+    stiffness?: number;
+    /** How far pressure spreads the tuft (default 0.5). */
+    splay?: number;
+    /** Each bristle's line width as a fraction of the tip size (default 0.06). */
+    thickness?: number;
+    /** Paint per bristle: 1 never runs dry; lower, bristles run out along the stroke (default 0.6). */
+    load?: number;
+    /** Random variation between bristles (default 0.4). */
+    jitter?: number;
+}
+/** The tip: its shape and the dab it lays. */
+export interface BrushTip {
+    shape: BrushTipShape;
+    /** Diameter in px, 1..2500 (default 20). */
+    size?: number;
+    /** Edge hardness 0 (soft) .. 1 (hard, default). */
+    hardness?: number;
+    /** Dab spacing as a fraction of the diameter, 0.01..10 (default 0.1). */
+    spacing?: number;
+    /** Tip angle in degrees, -360..360 (default 0). */
+    angle?: number;
+    /** Roundness 0.01..1: 1 round (default), lower a flat ellipse. */
+    roundness?: number;
+    /** Stroke opacity ceiling 0..1 (default 1). */
+    opacity?: number;
+    /** Build-up per dab 0..1 (default 1). */
+    flow?: number;
+    /** How the stroke paints onto the layer (default `normal`). */
+    blend?: BlendMode;
+    /** `bristle` tips: the tuft. */
+    bristle?: BrushBristles;
+    /** `stamp` tips: sticker refs (objects: any sticker, one picked at random per mark; particles: up to 4 editor stamps, in `marks.stampOrder`). */
+    stamps?: BrushStamp[];
+}
+/** Dabs laid along the path (the default). */
+export interface BrushContinuousMarks {
+    kind: 'continuous';
+}
+/** Particles that move with the pen and draw as they go (each 0..1 unless noted). */
+export interface BrushParticleMarks {
+    kind: 'particles';
+    /** How the particles move (default `spring`). */
+    physics?: ParticleKind;
+    /** How they draw (default `line`). */
+    render?: ParticleRender;
+    /** Particles, 1..64 (default 12). */
+    count?: number;
+    /** Mark size as a fraction of the tip size (default 0.08). */
+    size?: number;
+    /** How far apart they start, as a fraction of the tip size (default 0.5). */
+    spread?: number;
+    /** Spring, string and elastic stiffness (default 0.4). */
+    stiffness?: number;
+    /** How quickly motion dies down (default 0.25). */
+    damping?: number;
+    /** Orbit and flow speed (default 0.5). */
+    speed?: number;
+    /** Pull downwards, -1 (up) .. 1 (default 0). */
+    gravity?: number;
+    /** Flow particles' lifetime (default 0.5). */
+    life?: number;
+    /** Sequence: spacing of the beads (default 0.3). */
+    interval?: number;
+    /** Ribbon: fill opacity between the paths (default 0.5). */
+    ribbonFill?: number;
+    /** Ribbon: which paths are joined (default `adjacent`). */
+    ribbonPairs?: RibbonPairs;
+    /** Wave: sideways swing as a fraction of the tip size (default 0: none). */
+    waveAmplitude?: number;
+    /** Wave: wavelength in px of pen travel, 4..2000 (default 60). */
+    waveLength?: number;
+    /** Wave: how far out of step the particles' waves are (default 0). */
+    wavePhaseJitter?: number;
+    /** Stamp tips: the stamps in turn or at random (default `sequence`). */
+    stampOrder?: DotTextureOrder;
+    /** Stamp tips: how each stamp turns (default `random`). */
+    stampRotation?: DotRotation;
+}
+/** Each mark stays an editable object (a sticker) on a sticker layer (each 0..1 unless noted). */
+export interface BrushObjectMarks {
+    kind: 'objects';
+    /** About `density × 4` marks per tip diameter of travel (default 0.4). */
+    density?: number;
+    /** Random size change (default 0.4). */
+    sizeJitter?: number;
+    /** Random turn as a fraction of ±180° (default 1). */
+    rotationJitter?: number;
+    /** How far from the path marks land, in tip diameters, 0..2 (default 0.5). */
+    scatter?: number;
+    /** Random colour change, hue and lightness (default 0.2). */
+    colourJitter?: number;
+}
+export type BrushMarks = BrushContinuousMarks | BrushParticleMarks | BrushObjectMarks;
+/** Pen feel. Every amount is 0 (off) .. 1 unless noted. */
+export interface BrushDynamics {
+    /** Pressure scales the size (default true). */
+    pressureSize?: boolean;
+    /** Pressure scales the opacity (default false). */
+    pressureOpacity?: boolean;
+    /** Position smoothing 0..0.95 (default 0). */
+    smoothing?: number;
+    /** Pressure smoothing 0..0.95 (default 0). */
+    pressureSmoothing?: number;
+    /** What turns the tip: a fixed angle, the stroke direction or the pen barrel (default `fixed`). */
+    rotation?: BrushRotation;
+    /** Size at zero pressure as a fraction of the full 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 (default 0). */
+    tiltRoundness?: number;
+    /** Laying the pen down lightens the mark (default 0). */
+    tiltOpacity?: number;
+    /** -1..1: positive grows the tip on fast strokes, 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;
+}
+/** A Mixer Brush's paint reservoir: the brush is loaded with colour and mixes what it picks up into it. */
+export interface BrushReservoir {
+    /** How much paint it holds, 0..1 (default 0.5); below 1 it drains per dab. */
+    load?: number;
+    /** Refill with the paint colour at the start of each stroke (default true). */
+    refill?: boolean;
+    /** Load the current colour at all (default true; false: it only moves paint already down). */
+    loadsColour?: boolean;
+}
+/** Paint exchange with the canvas: picking paint up and mixing it into what the brush lays. */
+export interface BrushExchange {
+    /** Pick-up ratio 0..1 (default 0; with a reservoir 0.5). */
+    pickup?: number;
+    /** Mix ratio 0..1 (default 0.5). */
+    mix?: number;
+    /** Keep the picked-up paint for the next stroke (default false). */
+    dirty?: boolean;
+    /** A reservoir makes this a Mixer Brush. */
+    reservoir?: BrushReservoir;
+}
+/** Wet surface settings (each 0..1 unless noted). */
+export interface BrushWet {
+    /** The wet medium (default: the variety when it is one, else `watercolor`). */
+    medium?: WetMediumKind;
+    /** Water laid down (default 0.5). */
+    water?: number;
+    /** Pigment concentration (default 0.5). */
+    pigment?: number;
+    /** Body: 0 transparent .. 1 opaque (default 0). */
+    body?: number;
+    /** How much dried paint the water lifts again (default 0). */
+    rewet?: number;
+    /** Paint loading: 1 never runs out (default 1). */
+    load?: number;
+    /** Thinner: more transparent, runnier paint (default 0). */
+    thinner?: number;
+}
+/** Thick (impasto) surface settings (each 0..1 unless noted). */
+export interface BrushThick {
+    /** What lays the paint (default `brush`). */
+    applicator?: ImpastoTool;
+    /** Relief per stroke (default 0.6). */
+    thickness?: number;
+    /** Shine (default 0.4). */
+    gloss?: number;
+    /** Metallic highlights (default 0). */
+    metallic?: number;
+    /** Paint loading (default 0.9). */
+    load?: number;
+    /** Thinner (default 0). */
+    thinner?: number;
+    /** Knife and brush: how much paint is dragged along (default 0.4). */
+    drag?: number;
+    /** Light paint: brighter rims, as on backlit glass (default 0). */
+    rim?: number;
+    /** Light paint: see-through middles (default 0). */
+    clarity?: number;
+}
+/** What the material does on the surface, and how tools work. */
+export interface BrushBehaviour {
+    /** Default `dry`. */
+    surface?: BrushSurface;
+    /** Paper grain response 0 (ignores it) .. 1 (catches only the peaks), default 0. */
+    grain?: number;
+    /** How colours mix: `pigment` (Kubelka-Munk) or `rgb`. Default `pigment`; Mixer Brush and smudge `rgb`. */
+    mixing?: MixingModel;
+    exchange?: BrushExchange;
+    /** `surface: 'wet'` and the wet tools. */
+    wet?: BrushWet;
+    /** `surface: 'thick'`. */
+    thick?: BrushThick;
+    /** Tools: how strongly the blender, smudge or wet tool works, 0..1 (default 0.5; smudge 0.7). */
+    strength?: number;
+    /** Blender: neighbourhood radius as a fraction of the tip diameter, 0..1 (default 0.35). */
+    distance?: number;
+    /** Smudge: share of the carried paint kept per dab, 0..1 (default 0.85). */
+    length?: number;
+}
+/** Light the brush gives off with its colour. */
+export interface BrushLight {
+    /** Light per dab, 0..1 (default 0: none). */
+    amount?: number;
+    /** Pressure scales the light (default false). */
+    pressure?: boolean;
+    /** Suggested layer spill, applied when the layer has none of its own: radius 0..512 px (0 off), strength 0..2. */
+    spill?: {
+        radius?: number;
+        strength?: number;
+    };
+    /** Suggest a glow layer effect for the brush's layer (glow stays a layer effect). */
+    glow?: boolean;
+}
+/** Animation after painting. */
+export interface BrushMotion {
+    /** Effect paint keeps playing on stroke layers. */
+    live?: boolean;
+    /** Suggested playback rate, 1..60 frames per second. */
+    fps?: number;
+    /** Particle waves: how fast they run, 0..1 (default 0). */
+    waveSpeed?: number;
+}
+/**
+ * A colour a brush can carry: a solid colour (hex, `#rrggbbaa`, `rgba()` or a light / dark
+ * `DualColor`), a gradient, or effect paint.
+ */
+export type BrushPaint = ColorValue | PaintGradientSource | PaintEffectPaint;
+/** The brush's colours. The user's colour still wins unless `own` is set. */
+export interface BrushColour {
+    /**
+     * The colour the brush starts with. A gradient is always painted (its `paint` / `secondary`
+     * stops take the user's colours); a solid colour or effect paint is suggested to the host.
+     */
+    default?: BrushPaint;
+    /** Up to 16 suggested colours. */
+    palette?: BrushPaint[];
+    /** The brush always paints its own colour (a rainbow marker). */
+    own?: boolean;
+}
+/** A brush: identity, what it is, and its facets. */
+export interface Brush {
+    /** Library id: lowercase letters, digits and dashes, up to 64 characters. */
+    id: string;
+    /** Display name, up to 80 characters. */
+    name: string;
+    description?: string;
+    tags?: string[];
+    kind: BrushKind;
+    /** Marks only: what it lays. */
+    medium?: BrushMedium;
+    /** What kind of that medium (`oil`, `watercolor`, `pencil`, `highlighter`…): lowercase letters, digits and dashes. */
+    variety?: string;
+    /** Tools only: what it does. */
+    tool?: BrushTool;
+    tip: BrushTip;
+    marks?: BrushMarks;
+    dynamics?: BrushDynamics;
+    behaviour?: BrushBehaviour;
+    light?: BrushLight;
+    motion?: BrushMotion;
+    colour?: BrushColour;
+}
+/** The flat form the paint engine reads: every engine block, filled. */
+export type ResolvedBrush = PaintBrush;