@pixerate/editor 0.109.0 → 0.110.0

package/dist/paint-editor/index.d.cts

@@ -1,9 +1,9 @@
-import { R as RasterLayer, a as RasterGroupLayer, b as RasterPixelLayer, C as CompositorLayer, c as RasterCompositor, d as RasterSources, L as LayerLocks } from '../render-C-fO_mes.cjs';
-import { B as BrushSettings, M as MixerSettings, C as CoverageMap, D as Dab, S as StrokePoint, a as MixerLoad } from '../mixer-5ziHU8OS.cjs';
-export { b as MAX_BRUSH_SIZE } from '../mixer-5ziHU8OS.cjs';
-import { R as RasterRect, a as TiledSurface, B as BlendMode, b as BlendModeInfo } from '../surface-CkKOHGPm.cjs';
-export { c as BLEND_MODES, d as PAINTERLY_BLEND_MODES, e as Tile, i as isBlendMode, f as isPainterlyBlendMode, s as standardBlendMode } from '../surface-CkKOHGPm.cjs';
-import { I as ImageEditorAssetStore, S as SerializedLayer, P as PsdExportResult } from '../export-DSUc4fQD.cjs';
+import { R as RasterLayer, a as RasterGroupLayer, b as RasterPixelLayer, C as CompositorLayer, c as RasterCompositor, d as RasterSources, L as LayerLocks } from '../render-BEriFuqK.cjs';
+import { B as BrushSettings, M as MixerSettings, a as MixingModel, b as BlenderSettings, S as SmudgeSettings, C as CoverageMap, D as Dab, c as StrokePoint, d as MixerLoad, P as PaintTileTarget, R as RgbTriple } from '../blending-aOE6Y3UE.cjs';
+export { e as MAX_BRUSH_SIZE } from '../blending-aOE6Y3UE.cjs';
+import { R as RasterRect, a as TiledSurface, B as BlendMode, c as BlendModeInfo } from '../surface-C8RRg_Bh.cjs';
+export { d as BLEND_MODES, e as PAINTERLY_BLEND_MODES, f as Tile, i as isBlendMode, g as isPainterlyBlendMode, s as standardBlendMode } from '../surface-C8RRg_Bh.cjs';
+import { I as ImageEditorAssetStore, S as SerializedLayer, P as PsdExportResult } from '../export-DRiLzP_j.cjs';
 import { g as PresenceStore, e as PresenceClock, d as PresenceActorInfo, c as PresenceActor, f as PresenceState } from '../presence-Cb6WhcrQ.cjs';
 import { a as AgentToolProvider } from '../registry-BqA1AZt0.cjs';
 import '../types-CwMPoRMU.cjs';
@@ -150,11 +150,49 @@ declare function renderPaper(paper: PaperSettings, rect: {
  * the blending brushes. The built-in presets are our own settings; none come from another product.
  */
 
-/** How a brush makes marks: dabs into a stroke buffer, removing alpha, or the Mixer Brush engine. */
-type PaintBrushEngine = 'dab' | 'eraser' | 'mixer';
+/**
+ * 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';
 declare const PAINT_BRUSH_ENGINES: readonly PaintBrushEngine[];
-type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'custom';
+type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'paint' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'custom';
 declare const PAINT_BRUSH_CATEGORIES: readonly PaintBrushCategory[];
+/** 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[];
@@ -202,17 +240,39 @@ interface PaintBrush {
     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;
     /** 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;
-/** Brush settings to change or read: any subset of a brush, its tip, dynamics and mixer. */
-type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer'>> & {
+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'>> & {
     tip?: Partial<BrushSettings>;
     dynamics?: Partial<BrushDynamics>;
     mixer?: Partial<MixerSettings>;
+    behavior?: BrushBehaviorInput;
+    blender?: Partial<BlenderSettings>;
+    smudge?: Partial<SmudgeSettings>;
 };
+/** Whether a brush can pick paint up from the canvas (the pick-up / mix ratios apply): dab and mixer brushes. */
+declare function isWetCapable(brush: Pick<PaintBrush, 'engine'>): boolean;
+/**
+ * Whether a dab brush paints dab by dab through the exchange (it picks up paint or is
+ * multi-coloured) instead of building one coverage buffer of one colour.
+ */
+declare function usesPaintExchange(brush: PaintBrush): boolean;
 /** 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. */
@@ -306,6 +366,10 @@ 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;
 }
 /**
  * Walks pen samples into dabs, incrementally (any chunking gives the same dabs). Dab angles are in
@@ -390,6 +454,8 @@ interface RecordedStroke {
     seed: number;
     /** Extra copies painted with the stroke (mirror / kaleidoscope), as affine maps of the points. */
     copies?: Affine[];
+    /** What the brush carried at the start (Mixer Brush and wet-capable brushes), so a replay mixes the same. */
+    load?: MixerLoad;
 }
 declare function applyAffine(m: Affine, x: number, y: number): {
     x: number;
@@ -485,15 +551,91 @@ declare function createPaintDocument(options?: Partial<PaintCanvas> & {
     paper?: Partial<PaperSettings>;
 }): PaintDocumentState;
 
+/**
+ * The paint editor's dab-by-dab stroke engine: every brush whose dabs read what earlier dabs laid
+ * down. The Mixer Brush, the blender, the smudge, and dab brushes that pick up paint or are
+ * multi-coloured all run here, with the same pen input as dry media (`PenDabWalker`: pressure,
+ * tilt, barrel rotation, velocity, rotation modes, jitter), paper grain and symmetry copies.
+ *
+ * - `mixer` and wet-capable `dab` brushes go through the shared pick-up / mix exchange
+ *   (`PaintExchange` over a `TileMedium`): each dab picks up from the layer, mixes its paint from
+ *   the brush colour (or the multi-colour gradient) and the carried paint, and lays it down. A
+ *   Mixer Brush deposits per dab (photocraft's model); a dab brush keeps the stroke's opacity
+ *   ceiling: a shared `CoverageMap` builds up as for dry media and each dab lays only the
+ *   increase, `k = (c₁ − c₀)·o / (1 − c₀·o)`, so a one-colour Normal stroke matches the dry engine.
+ * - `blender` calls `blenderDab`, `smudge` a `SmudgeTip` per copy.
+ *
+ * Pixels go through the session's live tiles (`PaintTileTarget`). Pure data in, pixels out:
+ * points, seed, colours and the starting load replay exactly.
+ */
+
+interface PaintDabStrokeOptions {
+    /** Where the stroke reads and writes pixels. */
+    target: PaintTileTarget;
+    /** The paint colour, sRGB 0..1. */
+    color: RgbTriple;
+    /** The secondary colour (a multi-colour brush without its own colours uses both). */
+    secondary: RgbTriple;
+    /** What the brush carries at the start (mixer and wet-capable dab brushes). */
+    load: MixerLoad;
+    grain: PaperGrain | null;
+    paperDepth: number;
+    seed?: number;
+    copies?: readonly StrokeCopy[];
+}
+/** Colours of a multi-colour brush, resolved against the paint and secondary colours. */
+declare function multiColorPalette(mc: MultiColorSettings, color: RgbTriple, secondary: RgbTriple): RgbTriple[];
+/** The tip gradient of a multi-colour brush: `GRADIENT_STEPS` colours across the tip. */
+declare function multiColorGradient(palette: readonly RgbTriple[], softness: number, mixing: MixingModel): RgbTriple[];
+/** The colour of dab `index` of a `dab`-mode multi-colour brush. */
+declare function multiColorForDab(mc: MultiColorSettings, palette: readonly RgbTriple[], index: number, seed: number, mixing: MixingModel): RgbTriple;
+declare class PaintDabStroke {
+    readonly brush: PaintBrush;
+    private readonly options;
+    dabCount: number;
+    private readonly smoother;
+    private readonly copies;
+    private readonly states;
+    private readonly medium;
+    private readonly depth;
+    private readonly coverage;
+    private readonly palette;
+    private readonly gradient;
+    private readonly fieldLut;
+    private readonly scratch;
+    private readonly mixing;
+    private tip;
+    private cov;
+    private field;
+    private readonly paint;
+    private lastRaw;
+    private lastFed;
+    constructor(brush: PaintBrush, options: PaintDabStrokeOptions);
+    /** What copy 0's brush carries after the dabs so far (mixer and wet-capable dab brushes). */
+    get load(): MixerLoad | null;
+    push(points: readonly PenPoint[]): RasterRect[];
+    /** Ends the stroke: the smoothed path catches up with the last raw sample; a tap paints one dab. */
+    finish(): RasterRect[];
+    private paintDabs;
+    /** The tip's pure coverage (`tip`) and, with grain, what the paper catches of it (`cov`). */
+    private rasterize;
+    private dab;
+    /** Fills `this.field` with the tip gradient (mixed with the carried paint) per pixel; returns the paint weight. */
+    private tipField;
+    /** A dab brush's deposit: only what this dab adds to the stroke's coverage, under its opacity ceiling. */
+    private depositWithCeiling;
+}
+
 /**
  * A live stroke on one pixel layer. Points arrive while the pen moves; the layer shows the stroke
  * so far through a live surface (no history); `end()` commits it as one undo step.
  *
  * - Dab and eraser brushes: the coverage is cumulative, so each update recomposites the touched
  *   region from the pre-stroke tile (`applyStrokeToTile` with `into` and `region`).
- * - Mixer engine brushes (Mixer Brush, blender, smudge): dabs read what earlier dabs laid down, so
- *   they paint into live tile copies; every tile written since the last update gets a new `Tile`
- *   object, because the compositor caches by tile identity.
+ * - Dab-by-dab brushes (`PaintDabStroke`: the Mixer Brush, blender, smudge, and dab brushes that
+ *   pick up paint or are multi-coloured): dabs read what earlier dabs laid down, so they paint
+ *   into live tile copies; every tile written since the last update gets a new `Tile` object,
+ *   because the compositor caches by tile identity.
  */
 
 interface StrokeSessionHost {
@@ -525,8 +667,10 @@ interface StrokeSessionInit {
     copies: readonly StrokeCopy[];
     /** Applied to each raw sample before it is painted and recorded (perspective snapping). */
     inputFilter?: (p: PenPoint) => PenPoint;
-    /** Mixer engine: the brush load at the start of the stroke. */
+    /** Mixer and wet-capable dab brushes: what the brush carries at the start of the stroke. */
     mixerLoad: MixerLoad;
+    /** The secondary colour 0..255 RGBA (a multi-colour brush without its own colours uses it). */
+    secondary?: readonly [number, number, number, number];
 }
 interface PaintStrokeResult {
     layerId: string;
@@ -535,7 +679,7 @@ interface PaintStrokeResult {
     dabs: number;
     /** Id of the recorded stroke (see `list_strokes` / `replay_strokes`), or `null` when nothing changed. */
     strokeId: string | null;
-    /** Mixer engine brushes: what the brush carries after the stroke. */
+    /** Mixer and wet-capable dab brushes: what the brush carries after the stroke (cleaned unless it is dirty). */
     mixerLoad?: MixerLoad;
 }
 declare class PaintStrokeSession {
@@ -549,8 +693,7 @@ declare class PaintStrokeSession {
     private readonly touched;
     private readonly fresh;
     private readonly dry;
-    private readonly mixers;
-    private readonly mixerSmoother;
+    private readonly wet;
     private readonly apply;
     private readonly copies;
     private bounds;
@@ -558,7 +701,7 @@ declare class PaintStrokeSession {
     private closed;
     result: PaintStrokeResult | null;
     constructor(host: StrokeSessionHost, init: StrokeSessionInit);
-    private mixerTarget;
+    private tileTarget;
     get open(): boolean;
     /** Adds raw pen samples (document pixels). */
     push(points: readonly PenPoint[]): void;
@@ -570,6 +713,12 @@ declare class PaintStrokeSession {
 }
 /** The Mixer Brush load a stroke starts with. */
 declare function mixerLoadForStroke(brush: PaintBrush, current: MixerLoad, color: readonly [number, number, number]): MixerLoad;
+/**
+ * What any brush carries at the start of a stroke: the Mixer Brush as `mixerLoadForStroke`; a
+ * wet-capable dab brush the paint colour, full, plus the carried paint when it is dirty; other
+ * brushes nothing.
+ */
+declare function brushLoadForStroke(brush: PaintBrush, current: MixerLoad, color: readonly [number, number, number]): MixerLoad;
 
 /**
  * Compositing for the paint editor, on the shared `RasterCompositor`: the paper is a content layer
@@ -668,6 +817,8 @@ interface SerializeOptions {
     /** Painting guides (symmetry, perspective, tracing and reference images as PNG data URLs). */
     guides?: unknown;
     swatches?: unknown;
+    /** The mixing pad: `{ current?: png data URL, saved: [{ id, name, png }] }`. */
+    mixingPad?: unknown;
 }
 /** The document as JSON with inline PNG data URLs. */
 declare function serializePaintDocument(state: PaintDocumentState, options?: SerializeOptions): SerializedPaintDocument;
@@ -679,6 +830,8 @@ interface LoadedPaintDocument {
     /** The saved guides and swatches, as stored (the controller validates them). */
     guides?: unknown;
     swatches?: unknown;
+    /** The saved mixing pad, as stored (the controller validates it). */
+    mixingPad?: unknown;
     /** What could not be read (the rest still loads). */
     problems: string[];
 }
@@ -1036,13 +1189,33 @@ declare const DEFAULT_SWATCHES: readonly Swatch[];
 /**
  * The mixing pad: a small canvas beside the painting to put paint on, smear it with a palette
  * knife and pick the mixed colour from. Paint is laid with the Mixer Brush in pigment mode and the
- * knife is a pigment smudge, so blue and yellow pushed together make green. It is scratch space:
- * not part of the painting and not in its undo history.
+ * knife smears it with pigment mixing, so blue and yellow pushed together make green. It is
+ * scratch space: not part of the painting's undo history, but saved with the document, and pads
+ * can be kept by name (`MixingPad.toPng` / `fromPng`).
+ *
+ * `mix` puts measured blobs of paint down (areas in proportion to their parts) and works them
+ * together with the knife, the way a painter mixes a pile on the palette.
  */
 
 type MixingPadTool = 'paint' | 'knife';
 declare const MIXING_PAD_WIDTH = 360;
 declare const MIXING_PAD_HEIGHT = 220;
+/** One paint in a `mix`: a colour and its parts. */
+interface PadMixPart {
+    color: string;
+    parts: number;
+}
+interface PadMixOptions {
+    /** Centre of the pile in pad pixels (default the pad's centre). */
+    x?: number;
+    y?: number;
+    /** Radius of the pile in pad pixels, 12..100 (default 40). */
+    radius?: number;
+    /** Knife passes over the pile, 1..20 (default 3): more passes, finer streaks around the mixed core. */
+    passes?: number;
+    /** Wipe the pile's area first (default true); false mixes into what is already there. */
+    clear?: boolean;
+}
 declare class MixingPad {
     readonly width = 360;
     readonly height = 220;
@@ -1062,9 +1235,36 @@ declare class MixingPad {
             height: number;
         } | null;
     };
+    /** Paints `points` with `brush` in `color` on the pad. */
+    private run;
     /** The average colour within `radius` pixels of (x, y), or `null` where the pad is bare. */
     pick(x: number, y: number, radius?: number): string | null;
     clear(): void;
+    /**
+     * Mixes paints the way a painter does on a palette: blobs whose areas are in proportion to
+     * their parts, side by side around (x, y), spiral knife passes that fold them together, and then the centre worked until it is fully mixed: a soft-edged core
+     * of the Kubelka-Munk mix of the parts (`mixPigments`), with partly mixed streaks around it.
+     * Returns that colour (picked back from the centre) and the pile's bounds.
+     *
+     * The core is laid, not smeared, because smearing alone drifts: the knife samples in RGB and a
+     * mixed colour's scattering is re-estimated from its luminance, so repeated small mixes favour
+     * the lighter paint (see GOTCHAS).
+     */
+    mix(paints: readonly PadMixPart[], options?: PadMixOptions): {
+        color: string | null;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    /** The pad's pixels as a PNG data URL (with alpha), for saving. */
+    toPng(): string;
+    /** Replaces the pad with a PNG (data URL or base64) of the pad's size, as `toPng` writes. */
+    fromPng(png: string): void;
+    /** Whether nothing is on the pad. */
+    get empty(): boolean;
     /** The pad over white, `width × height` RGBA. */
     pixels(): Uint8ClampedArray;
 }
@@ -1125,6 +1325,8 @@ interface PaintEditorState {
     swatches: readonly Swatch[];
     /** Changes whenever the mixing pad does. */
     mixingPadVersion: number;
+    /** Mixing pads kept by name (saved with the document). */
+    savedMixingPads: readonly SavedMixingPadInfo[];
     /** A stroke is in progress. */
     stroking: boolean;
     /** Increments on every change. */
@@ -1166,6 +1368,8 @@ interface PaintStrokeInit {
         x: number;
         y: number;
     };
+    /** What the brush carries at the start (default: from the editor's brush load); replays pass the recorded one. */
+    load?: MixerLoad;
 }
 interface LayerUpdate {
     name?: string;
@@ -1210,6 +1414,11 @@ interface PixelImage {
     height: number;
     data: Uint8ClampedArray;
 }
+/** A mixing pad kept by name. */
+interface SavedMixingPadInfo {
+    id: string;
+    name: string;
+}
 declare class PaintEditorController {
     private doc;
     private extensions;
@@ -1218,6 +1427,8 @@ declare class PaintEditorController {
     private readonly historyLimit;
     private brush;
     private userBrushes;
+    /** The library list in the state (the same array until the user brushes change, so thumbnails are not redrawn). */
+    private library;
     private color;
     private secondaryColor;
     private mixerLoad;
@@ -1236,6 +1447,8 @@ declare class PaintEditorController {
     private guides;
     private swatches;
     private readonly pad;
+    private savedPads;
+    private nextPadId;
     private tracingVersion;
     private tracingCache;
     private readonly imagePixels;
@@ -1372,6 +1585,11 @@ declare class PaintEditorController {
     resetView(): PaintView;
     setHand(hand: Hand): Hand;
     private strokeBrush;
+    /**
+     * After a stroke: a Mixer Brush that loads colour keeps its whole load; any other dirty brush
+     * keeps only the paint it carries (the reservoir stays the Mixer Brush's).
+     */
+    private keepLoad;
     /** Extra copies every new stroke paints (the painting guides add mirror and kaleidoscope copies). */
     protected strokeCopies(): Affine[];
     private sessionFor;
@@ -1531,6 +1749,35 @@ declare class PaintEditorController {
         setColor?: boolean;
     }): string | null;
     clearMixingPad(): void;
+    /**
+     * Mixes paints on the pad like a painter: blobs in proportion to their `parts`, knife passes,
+     * and a fully mixed core of the Kubelka-Munk mix (see `MixingPad.mix`). With `setColor` the
+     * mix becomes the paint colour. Returns the mixed colour and the pile's bounds.
+     */
+    mixOnPad(paints: readonly {
+        color: string;
+        parts: number;
+    }[], options?: PadMixOptions & {
+        setColor?: boolean;
+    }): {
+        color: string;
+        bounds: RasterRect;
+    };
+    /** The mixing pad as a PNG data URL (with alpha). */
+    mixingPadPng(): string;
+    /** Replaces the mixing pad with a PNG (data URL or base64, 360 × 220). */
+    setMixingPadPng(png: string): void;
+    /** The mixing pads kept by name. */
+    listMixingPads(): SavedMixingPadInfo[];
+    /** Keeps the mixing pad as it is now under `name` (saved with the document). Returns its id. */
+    saveMixingPad(name?: string): SavedMixingPadInfo;
+    private requirePad;
+    /** Puts a kept pad back on the mixing pad (replacing what is there). */
+    loadMixingPad(id: string): SavedMixingPadInfo;
+    /** Forgets a kept pad. */
+    removeMixingPad(id: string): SavedMixingPadInfo;
+    private mixingPadJSON;
+    private readMixingPad;
     /** A layer's tile surface (live while stroking), for thumbnails. */
     layerSurface(id: string): TiledSurface | null;
 }
@@ -1784,5 +2031,37 @@ interface BlendMenuGroup {
  * description as a tooltip. Both bindings render this as `<optgroup>`s.
  */
 declare const BLEND_MENU_GROUPS: readonly BlendMenuGroup[];
+/** The engine-specific part of the brush panel: which sliders and toggles the active brush has. */
+interface BrushEngineControls {
+    /** Section heading. */
+    title: string;
+    sliders: readonly SliderControl[];
+    /** Where the RGB / pigment choice is stored, or `null` when the engine has none. */
+    mixingPath: 'behavior.mixing' | 'blender.mixing' | 'smudge.mixing' | null;
+    /** The dirty-brush toggle (`behavior.dirty`). */
+    dirty: boolean;
+    /** The multi-colour controls (`behavior.multicolor`). */
+    multicolor: boolean;
+    /** Load / Clean buttons and a swatch of what the brush carries. */
+    load: boolean;
+}
+/**
+ * The controls the active brush's engine adds to the brush panel (`null` for the eraser):
+ * blender strength and blend distance; smudge strength and length; the Mixer Brush's pick-up,
+ * mix and load; a dab brush's pick-up and mix ratios. Every engine but the eraser has an RGB /
+ * pigment choice; dab and mixer brushes also have the dirty and multi-colour controls. Pick-up
+ * and mix always go through `behavior`, which keeps a Mixer Brush's `mixer` block in sync.
+ */
+declare function brushEngineControls(brush: Pick<PaintBrush, 'engine'>): BrushEngineControls | null;
+/** The multi-colour sliders for a mode: softness, and dabs per colour in `dab` mode. */
+declare function multiColorSliders(mode: string): readonly SliderControl[];
+/** A brush change setting `path` (e.g. `smudge.mixing`, `behavior.dirty`) to any value, keeping the rest of its block. */
+declare function patchBrushValue(brush: PaintBrush, path: string, value: unknown): PaintBrushInput;
+/** What the brush carries (picked-up paint, else loaded paint) as #rrggbb, or `null` when it is clean and empty. */
+declare function brushLoadColor(load: MixerLoad): string | null;
+/** Sample sizes (square, in pad pixels) for picking from the mixing pad. */
+declare const PAD_SAMPLE_SIZES: readonly number[];
+/** The averaging radius `mixingPadPick` takes for a sample size: 1 → 0, 3 → 1, 5 → 2 … */
+declare function padSampleRadius(size: number): number;
 
-export { type Affine, BLEND_MENU_GROUPS, BRUSH_ID, BRUSH_ROTATIONS, BRUSH_SLIDERS, BUILTIN_BRUSHES, type BlendMenuGroup, BlendMode, BlendModeInfo, type BrushDynamics, type BrushLibraryFile, type BrushRotation, type BrushThumbnail, type ColorWheel, DEFAULT_BRUSH_ID, DEFAULT_DPI, DEFAULT_DYNAMICS, DEFAULT_PAPER, DEFAULT_SWATCHES, DEFAULT_VIEW, DryStroke, type DryStrokeOptions, type FillLayerOptions, GRAIN_PATTERNS, GRAIN_TILE, type GrainPattern, type GrainTuning, HARMONY_KINDS, type Hand, type HarmonyColor, type HarmonyKind, IDENTITY_AFFINE, IDENTITY_COPY, type ImageEncoder, type ImageFormat, type ImageNode, type LayerUpdate, type Linear2, type LoadedPaintDocument, MAX_CANVAS_SIDE, MAX_COORDINATE, MAX_IMAGE_SIDE, MAX_ZOOM, MIN_CANVAS_SIDE, MIN_ZOOM, MIXING_PAD_HEIGHT, MIXING_PAD_WIDTH, MixingPad, type MixingPadTool, PAINT_BRUSH_CATEGORIES, PAINT_BRUSH_ENGINES, PAINT_FORMAT, PAINT_SCHEMA_VERSION, PAINT_TOOLS, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, PAPER_SLIDERS, type Paint2DContext, type PaintAgentCommand, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintBrushInput, type PaintCanvas, PaintCanvasPresenter, PaintDirector, type PaintDirectorOptions, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, PaintGesture, type PaintGroupLayer, type PaintGuides, type PaintLayer, type PaintLayerInfo, type PaintPerformanceResult, type PaintPixelLayer, type PaintPointerEvent, PaintPresence, type PaintPresenceActor, type PaintPresenceState, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintTool, type PaintView, type PaperFamily, PaperGrain, type PaperNode, type PaperSettings, type PaperTiling, type PenDab, PenDabWalker, type PenPoint, PenSmoother, type PerspectiveGuide, PerspectiveSnapper, type PixelImage, type Point2, type PointerSample, type RecordedStroke, type ReferenceImage, type RenderOptions, type ReplayOptions, type Rgb255, SNAP_DECIDE_DISTANCE, SYMMETRY_MODES, type SerializeOptions, type SerializedPaintDocument, type SliderControl, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, type Swatch, type SymmetryGuide, type SymmetryMode, TRACING_NODE_ID, TileableNoise, type TracingImage, type ViewLayer, type ViewportBox, affineCopy, applyAffine, brushToJSON, clonePaper, colorHarmony, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, decodeImageBlob, defaultGuides, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downloadBytes, downsampleRgba, fitZoom, grainCatch, grainHeights, guideOverlay, handlePaintShortcut, hash2, hexToRgb8, hslToRgb, hsvToRgb, hueToWheel, invertAffine, isPalmTouch, mapPenPoint, mix32, mixerLoadForStroke, mixerTip, newPaintLayerId, normalizeBrushStroke, normalizeCanvas, normalizeDynamics, normalizePaintBrush, normalizePaper, normalizePerspective, normalizeRotation, normalizeSymmetry, normalizeView, paperGrain, paperKey, paperNode, paperPreset, parseBrushLibrary, parseHexColor, patchPath, penOrientation, perspectiveDirections, perspectiveGuideLines, pointerToPenPoint, rand01, randSigned, readPath, renderBrushThumbnail, renderColorWheel, renderPaper, rgbToHexColor, rgbToHsl, rgbToHsv, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, strokeDuration, strokeSchedule, sweepPath, symmetryAxisAngles, symmetryAxisSegments, symmetryCopies, thumbnailStroke, tiltToOrientation, toStrokePoint, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument, wheelAngle, wheelPick, wheelPoint, wheelToHue };
+export { type Affine, BLEND_MENU_GROUPS, BRUSH_ID, BRUSH_ROTATIONS, BRUSH_SLIDERS, BUILTIN_BRUSHES, type BlendMenuGroup, BlendMode, BlendModeInfo, type BrushBehavior, type BrushBehaviorInput, type BrushDynamics, type BrushEngineControls, type BrushLibraryFile, type BrushRotation, type BrushThumbnail, type ColorWheel, DEFAULT_BEHAVIOR, DEFAULT_BRUSH_ID, DEFAULT_DPI, DEFAULT_DYNAMICS, DEFAULT_MULTI_COLOR, DEFAULT_PAPER, DEFAULT_SWATCHES, DEFAULT_VIEW, DryStroke, type DryStrokeOptions, type FillLayerOptions, GRAIN_PATTERNS, GRAIN_TILE, type GrainPattern, type GrainTuning, HARMONY_KINDS, type Hand, type HarmonyColor, type HarmonyKind, IDENTITY_AFFINE, IDENTITY_COPY, type ImageEncoder, type ImageFormat, type ImageNode, type LayerUpdate, type Linear2, type LoadedPaintDocument, MAX_CANVAS_SIDE, MAX_COORDINATE, MAX_IMAGE_SIDE, MAX_ZOOM, MIN_CANVAS_SIDE, MIN_ZOOM, MIXING_PAD_HEIGHT, MIXING_PAD_WIDTH, MULTI_COLOR_MODES, MixingPad, type MixingPadTool, type MultiColorMode, type MultiColorSettings, PAD_SAMPLE_SIZES, PAINT_BRUSH_CATEGORIES, PAINT_BRUSH_ENGINES, PAINT_FORMAT, PAINT_SCHEMA_VERSION, PAINT_TOOLS, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, PAPER_SLIDERS, type PadMixOptions, type PadMixPart, type Paint2DContext, type PaintAgentCommand, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintBrushInput, type PaintCanvas, PaintCanvasPresenter, PaintDabStroke, type PaintDabStrokeOptions, PaintDirector, type PaintDirectorOptions, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, PaintGesture, type PaintGroupLayer, type PaintGuides, type PaintLayer, type PaintLayerInfo, type PaintPerformanceResult, type PaintPixelLayer, type PaintPointerEvent, PaintPresence, type PaintPresenceActor, type PaintPresenceState, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintTool, type PaintView, type PaperFamily, PaperGrain, type PaperNode, type PaperSettings, type PaperTiling, type PenDab, PenDabWalker, type PenPoint, PenSmoother, type PerspectiveGuide, PerspectiveSnapper, type PixelImage, type Point2, type PointerSample, type RecordedStroke, type ReferenceImage, type RenderOptions, type ReplayOptions, type Rgb255, SNAP_DECIDE_DISTANCE, SYMMETRY_MODES, type SavedMixingPadInfo, type SerializeOptions, type SerializedPaintDocument, type SliderControl, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, type Swatch, type SymmetryGuide, type SymmetryMode, TRACING_NODE_ID, TileableNoise, type TracingImage, type ViewLayer, type ViewportBox, affineCopy, applyAffine, brushEngineControls, brushLoadColor, brushLoadForStroke, brushToJSON, clonePaper, colorHarmony, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, decodeImageBlob, defaultGuides, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downloadBytes, downsampleRgba, fitZoom, grainCatch, grainHeights, guideOverlay, handlePaintShortcut, hash2, hexToRgb8, hslToRgb, hsvToRgb, hueToWheel, invertAffine, isPalmTouch, isWetCapable, mapPenPoint, mix32, mixerLoadForStroke, mixerTip, multiColorForDab, multiColorGradient, multiColorPalette, multiColorSliders, newPaintLayerId, normalizeBehavior, normalizeBrushStroke, normalizeCanvas, normalizeDynamics, normalizeMultiColor, normalizePaintBrush, normalizePaper, normalizePerspective, normalizeRotation, normalizeSymmetry, normalizeView, padSampleRadius, paperGrain, paperKey, paperNode, paperPreset, parseBrushLibrary, parseHexColor, patchBrushValue, patchPath, penOrientation, perspectiveDirections, perspectiveGuideLines, pointerToPenPoint, rand01, randSigned, readPath, renderBrushThumbnail, renderColorWheel, renderPaper, rgbToHexColor, rgbToHsl, rgbToHsv, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, strokeDuration, strokeSchedule, sweepPath, symmetryAxisAngles, symmetryAxisSegments, symmetryCopies, thumbnailStroke, tiltToOrientation, toStrokePoint, usesPaintExchange, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument, wheelAngle, wheelPick, wheelPoint, wheelToHue };