@pixerate/editor 0.251.0 → 0.253.0

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

@@ -0,0 +1,57 @@
+/**
+ * The brush panel's slider tables and the controls each engine adds (`brushEngineControls`),
+ * as plain data: paths into the engine brush. No renderer is imported, so the brush editor
+ * descriptor (`@pixerate/editor/brushes` `brushEditorSections`) reuses them without bundling the
+ * paint engine.
+ */
+import type { PaintBrush, PaintBrushInput } from './brushes.cjs';
+/** One slider of a panel: a path into the brush (or paper) settings. */
+export interface SliderControl {
+    path: string;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+}
+export declare const BRUSH_SLIDERS: readonly SliderControl[];
+export 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`; the panels show the brush gradient, `brush.paint`, instead). */
+    multicolor: boolean;
+    /** Load / Clean buttons and a swatch of what the brush carries. */
+    load: boolean;
+    /** The wet tool menu (`wet.tool`, `WET_TOOLS`) and medium menu (`wet.medium`, `WET_MEDIA`). */
+    wetTool?: boolean;
+    /** The impasto tool menu (`impasto.tool`, `IMPASTO_TOOLS`). */
+    impastoTool?: boolean;
+    /**
+     * The particle menus: kind and render (`particle.kind`, `particle.render`), ribbon pairs
+     * (`particle.ribbonPairs`), and the textured-dot stamps, order and rotation
+     * (`particle.dotTextures` up to `MAX_DOT_TEXTURES` of `STAMP_KINDS`, `dotTextureOrder`, `dotRotation`).
+     */
+    particleMenus?: boolean;
+    /** The sticker picker for the brush's stickers (`sticker.stamps`, refs from the sticker library; `toggleStickerRef`). */
+    stickerStamps?: boolean;
+    /** Light paint: the "light follows pressure" toggle (`light.pressure`); the Light slider is in `sliders`. */
+    light?: 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.
+ */
+export declare function brushEngineControls(brush: Pick<PaintBrush, 'engine'> & {
+    wet?: PaintBrush['wet'];
+}): BrushEngineControls | null;
+/** The multi-colour sliders for a mode: softness, and dabs per colour in `dab` mode. */
+export 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. */
+export declare function patchBrushValue(brush: PaintBrush, path: string, value: unknown): PaintBrushInput;

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

@@ -0,0 +1,57 @@
+/**
+ * The brush panel's slider tables and the controls each engine adds (`brushEngineControls`),
+ * as plain data: paths into the engine brush. No renderer is imported, so the brush editor
+ * descriptor (`@pixerate/editor/brushes` `brushEditorSections`) reuses them without bundling the
+ * paint engine.
+ */
+import type { PaintBrush, PaintBrushInput } from './brushes.js';
+/** One slider of a panel: a path into the brush (or paper) settings. */
+export interface SliderControl {
+    path: string;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+}
+export declare const BRUSH_SLIDERS: readonly SliderControl[];
+export 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`; the panels show the brush gradient, `brush.paint`, instead). */
+    multicolor: boolean;
+    /** Load / Clean buttons and a swatch of what the brush carries. */
+    load: boolean;
+    /** The wet tool menu (`wet.tool`, `WET_TOOLS`) and medium menu (`wet.medium`, `WET_MEDIA`). */
+    wetTool?: boolean;
+    /** The impasto tool menu (`impasto.tool`, `IMPASTO_TOOLS`). */
+    impastoTool?: boolean;
+    /**
+     * The particle menus: kind and render (`particle.kind`, `particle.render`), ribbon pairs
+     * (`particle.ribbonPairs`), and the textured-dot stamps, order and rotation
+     * (`particle.dotTextures` up to `MAX_DOT_TEXTURES` of `STAMP_KINDS`, `dotTextureOrder`, `dotRotation`).
+     */
+    particleMenus?: boolean;
+    /** The sticker picker for the brush's stickers (`sticker.stamps`, refs from the sticker library; `toggleStickerRef`). */
+    stickerStamps?: boolean;
+    /** Light paint: the "light follows pressure" toggle (`light.pressure`); the Light slider is in `sliders`. */
+    light?: 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.
+ */
+export declare function brushEngineControls(brush: Pick<PaintBrush, 'engine'> & {
+    wet?: PaintBrush['wet'];
+}): BrushEngineControls | null;
+/** The multi-colour sliders for a mode: softness, and dabs per colour in `dab` mode. */
+export 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. */
+export declare function patchBrushValue(brush: PaintBrush, path: string, value: unknown): PaintBrushInput;

package/dist/paint-editor/brush-library-tools.d.cts

@@ -0,0 +1,15 @@
+/**
+ * The shared brush library's agent tools for a paint editor (`createPaintBrushLibraryToolProvider`),
+ * with `preview_brush` painted by this editor.
+ */
+import { type BrushLibraryToolProviderOptions } from '../brushes/tools.cjs';
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { PaintEditorController } from './controller.cjs';
+export type PaintBrushLibraryToolProviderOptions = Omit<BrushLibraryToolProviderOptions, 'renderPreview'>;
+/**
+ * The brush library tools for a paint editor (`@pixerate/editor/brushes`' provider on the
+ * editor's `brushLibrary`, `PAINT_PROFILE`), with `preview_brush` painting the test stroke on the
+ * editor's paper. Register it next to `createPaintEditorToolProvider`: it lists, saves, shares and
+ * previews the brushes `set_brush` picks.
+ */
+export declare function createPaintBrushLibraryToolProvider(controller: PaintEditorController, options?: PaintBrushLibraryToolProviderOptions): AgentToolProvider;

package/dist/paint-editor/brush-library-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The shared brush library's agent tools for a paint editor (`createPaintBrushLibraryToolProvider`),
+ * with `preview_brush` painted by this editor.
+ */
+import { type BrushLibraryToolProviderOptions } from '../brushes/tools.js';
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { PaintEditorController } from './controller.js';
+export type PaintBrushLibraryToolProviderOptions = Omit<BrushLibraryToolProviderOptions, 'renderPreview'>;
+/**
+ * The brush library tools for a paint editor (`@pixerate/editor/brushes`' provider on the
+ * editor's `brushLibrary`, `PAINT_PROFILE`), with `preview_brush` painting the test stroke on the
+ * editor's paper. Register it next to `createPaintEditorToolProvider`: it lists, saves, shares and
+ * previews the brushes `set_brush` picks.
+ */
+export declare function createPaintBrushLibraryToolProvider(controller: PaintEditorController, options?: PaintBrushLibraryToolProviderOptions): AgentToolProvider;

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

@@ -0,0 +1,29 @@
+/**
+ * The paint editor's side of the shared brush library (`@pixerate/editor/brushes`): the
+ * controller's synchronous copy of the library (each brush as stored, as facets, and as the
+ * engine paints it), and facet brushes for engine brushes edited by their settings.
+ */
+import type { StorageAdapter } from '../persistence/storage.cjs';
+import type { Brush } from '../brushes/types.cjs';
+import { type PaintBrush } from './brushes.cjs';
+/** A library brush as the paint editor keeps it: its facets and the engine form it paints with. */
+export interface LibraryBrush {
+    spec: Brush;
+    brush: PaintBrush;
+    builtin: boolean;
+}
+export declare const copyJSON: <T>(v: T) => T;
+export declare function libraryBrush(spec: Brush, builtin: boolean, resolved?: PaintBrush): LibraryBrush;
+/** The built-in presets, paired with the engine brushes they resolve to (`BUILTIN_BRUSHES`, in the same order). */
+export declare function builtinLibraryBrushes(): readonly LibraryBrush[];
+/** Storage that starts with these brushes (a version 1 file) and keeps the rest in memory; none without brushes. */
+export declare function seededStorage(brushes: readonly PaintBrush[]): Pick<StorageAdapter, 'get' | 'set'> | undefined;
+/**
+ * The facet brush an engine brush edited by its settings amounts to (`migrateBrushV1`), keeping
+ * what the engine doesn't read from the brush it was edited from: description, tags, medium and
+ * variety, suggested colours, light spill and glow, and motion hints. Hints that would change how
+ * it paints are left out.
+ */
+export declare function brushSpecOf(next: PaintBrush, from: Brush): Brush;
+/** The engine settings `next` changes on `base`, as `normalizePaintBrush(changes, base)` takes them (lists whole). */
+export declare function engineChanges(base: PaintBrush, next: PaintBrush): Omit<Partial<PaintBrush>, 'id'>;

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

@@ -0,0 +1,29 @@
+/**
+ * The paint editor's side of the shared brush library (`@pixerate/editor/brushes`): the
+ * controller's synchronous copy of the library (each brush as stored, as facets, and as the
+ * engine paints it), and facet brushes for engine brushes edited by their settings.
+ */
+import type { StorageAdapter } from '../persistence/storage.js';
+import type { Brush } from '../brushes/types.js';
+import { type PaintBrush } from './brushes.js';
+/** A library brush as the paint editor keeps it: its facets and the engine form it paints with. */
+export interface LibraryBrush {
+    spec: Brush;
+    brush: PaintBrush;
+    builtin: boolean;
+}
+export declare const copyJSON: <T>(v: T) => T;
+export declare function libraryBrush(spec: Brush, builtin: boolean, resolved?: PaintBrush): LibraryBrush;
+/** The built-in presets, paired with the engine brushes they resolve to (`BUILTIN_BRUSHES`, in the same order). */
+export declare function builtinLibraryBrushes(): readonly LibraryBrush[];
+/** Storage that starts with these brushes (a version 1 file) and keeps the rest in memory; none without brushes. */
+export declare function seededStorage(brushes: readonly PaintBrush[]): Pick<StorageAdapter, 'get' | 'set'> | undefined;
+/**
+ * The facet brush an engine brush edited by its settings amounts to (`migrateBrushV1`), keeping
+ * what the engine doesn't read from the brush it was edited from: description, tags, medium and
+ * variety, suggested colours, light spill and glow, and motion hints. Hints that would change how
+ * it paints are left out.
+ */
+export declare function brushSpecOf(next: PaintBrush, from: Brush): Brush;
+/** The engine settings `next` changes on `base`, as `normalizePaintBrush(changes, base)` takes them (lists whole). */
+export declare function engineChanges(base: PaintBrush, next: PaintBrush): Omit<Partial<PaintBrush>, 'id'>;

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

@@ -18,7 +18,10 @@ import { type LayerLocks } from '../raster/layers.cjs';
 import { type LayerEffect, type LayerEffectKind, type LayerEffects } from '../raster/effects/model.cjs';
 import type { EffectPattern } from '../raster/effects/patterns.cjs';
 import { TiledSurface, type RasterRect, type Tile } from '../raster/surface.cjs';
-import { type PaintBrushInput, type BrushLibraryFile, type PaintBrush } from './brushes.cjs';
+import { type PaintBrushInput, type PaintBrush } from './brushes.cjs';
+import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.cjs';
+import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.cjs';
+import type { Brush } from '../brushes/types.cjs';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.cjs';
 import { type ImageEncoder, type ImageFormat } from './encode.cjs';
 import type { PenPoint } from './engine.cjs';
@@ -57,7 +60,12 @@ export interface PaintEditorOptions extends Partial<PaintCanvas> {
     paper?: Partial<PaperSettings> | string;
     /** Active brush id (default `pencil-6b`). */
     brushId?: string;
-    /** Saved user brushes to start the library with. */
+    /**
+     * The brush library: built-in presets plus saved brushes, on any storage. Pass one library to
+     * every editor so a brush saved in one shows in all of them (default: a library in memory).
+     */
+    brushLibrary?: BrushLibrary;
+    /** Saved user brushes to start the default library with (or to add to `brushLibrary`). */
     brushes?: readonly PaintBrush[];
     /** Paint colour #rrggbb (default #1f2937). */
     color?: string;
@@ -296,8 +304,17 @@ export declare class PaintEditorController {
     private undoStack;
     private redoStack;
     private readonly historyLimit;
+    /** The brush library this editor lists, saves into and paints from (shared with other editors when the host passes one). */
+    readonly brushLibrary: BrushLibrary;
     private brush;
-    private userBrushes;
+    /** The active brush as facets (what `getBrushSpec` and saving use). */
+    private brushSpec;
+    /** The library's brushes as last read, each as stored (facets) and as the engine paints it. */
+    private brushEntries;
+    /** The brush id asked for at construction, while the library had not listed it yet. */
+    private pendingBrushId;
+    private brushesLoaded;
+    private readonly unsubscribeLibrary;
     /** The library list in the state (the same array until the user brushes change, so thumbnails are not redrawn). */
     private library;
     private color;
@@ -673,39 +690,81 @@ export declare class PaintEditorController {
         source: PaintEffectSource;
         amount: number;
     }>;
+    private findEntry;
     private findBrush;
-    /** A library brush by id (`undefined` when unknown). */
-    getBrush(id: string): PaintBrush | undefined;
+    private requireEntry;
     private requireBrush;
+    /** Reads the library again (after a change anywhere it is shared). */
+    private refreshBrushes;
+    /** Resolves once the brush library has been read (user brushes kept in storage are listed from then on). */
+    whenBrushesLoaded(): Promise<void>;
+    /** A library brush by id, as the engine paints it (`undefined` when unknown). */
+    getBrush(id: string): PaintBrush | undefined;
+    /** A library brush by id as stored (its facets), or without an id the active brush as edited. */
+    getBrushSpec(id?: string): Brush | undefined;
     /**
-     * Chooses the active brush (`id`: a library brush) and / or changes its settings. Editor state,
-     * not an undo step. Returns the active brush.
+     * Chooses the active brush (`id`: a library brush) and / or changes its engine settings. Editor
+     * state, not an undo step. Returns the active brush. `setBrushFacets` changes it by facets.
      */
     setBrush(update?: {
         id?: string;
     } & Omit<PaintBrushInput, 'id'>): PaintBrush;
-    /** Saves the active brush (or `brush`) into the user library under `id` / `name`. */
+    /**
+     * Chooses the active brush (`id`: a library brush) and / or lays a facet patch over it (objects
+     * merge, lists and values replace, as the library's `update_brush` does). Editor state, not an
+     * undo step. `unset` removes whole facets first. Returns the active brush as the engine paints
+     * it, its facets, and what was clamped or dropped.
+     */
+    setBrushFacets(patch?: BrushPatch, id?: string, unset?: readonly UnsettableBrushFacet[]): {
+        brush: PaintBrush;
+        spec: Brush;
+        problems: string[];
+    };
+    /**
+     * Makes `spec` (a whole facet brush, as the brush editor edits it) the active brush, keeping the
+     * active brush's id. Editor state, not an undo step. Returns it as the engine paints it, its
+     * facets, and what was clamped or dropped.
+     */
+    setBrushSpec(spec: Brush): {
+        brush: PaintBrush;
+        spec: Brush;
+        problems: string[];
+    };
+    /**
+     * The engine settings a facet patch changes on a brush (`from`: a library brush id or a brush as
+     * painted; default the active brush), as `paintStroke`'s and `updateStroke`'s `brush` take them.
+     */
+    brushChanges(patch: BrushPatch, from?: string | PaintBrush): Omit<PaintBrushInput, 'id'>;
+    private readBrushPatch;
+    private useBrush;
+    /**
+     * Saves the active brush (or `brush`, engine settings on top of it) into the brush library under
+     * `id` / `name`, replacing a user brush with that id. Built-in ids are refused. Resolves with the
+     * saved brush.
+     */
     saveBrush(options: {
         id: string;
         name?: string;
         brush?: PaintBrushInput;
-    }): PaintBrush;
-    removeBrush(id: string): void;
-    /** The user's saved brushes. */
+    }): Promise<PaintBrush>;
+    /** Removes a user brush from the brush library (built-in brushes can't be removed). */
+    removeBrush(id: string): Promise<void>;
+    /** The user's saved brushes, as the engine paints them. */
     getUserBrushes(): PaintBrush[];
-    /** A brush library file of the given brushes (default: the user's brushes). */
-    exportBrushes(ids?: readonly string[]): BrushLibraryFile;
+    /** A brush library file (version 2) of the given brushes (default: the user's brushes). */
+    exportBrushes(ids?: readonly string[]): Promise<BrushLibraryFile>;
     /**
-     * Adds the brushes of a library file to the user library. A brush whose id is taken is skipped
-     * unless `replace` (built-in ids are always skipped). Returns the ids added and the problems.
+     * Adds the brushes of a library file (version 1 or 2) to the brush library. A brush whose id is
+     * taken is skipped unless `replace` (built-in ids are always skipped). Resolves with the ids
+     * added or replaced, the ids skipped and the problems.
      */
     importBrushes(file: unknown, options?: {
         replace?: boolean;
-    }): {
+    }): Promise<{
         added: string[];
         skipped: string[];
         problems: string[];
-    };
+    }>;
     /** A thumbnail of a brush: a test stroke on the current paper. */
     brushThumbnail(id: string, options?: {
         width?: number;

package/dist/paint-editor/controller.d.ts

@@ -18,7 +18,10 @@ import { type LayerLocks } from '../raster/layers.js';
 import { type LayerEffect, type LayerEffectKind, type LayerEffects } from '../raster/effects/model.js';
 import type { EffectPattern } from '../raster/effects/patterns.js';
 import { TiledSurface, type RasterRect, type Tile } from '../raster/surface.js';
-import { type PaintBrushInput, type BrushLibraryFile, type PaintBrush } from './brushes.js';
+import { type PaintBrushInput, type PaintBrush } from './brushes.js';
+import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.js';
+import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.js';
+import type { Brush } from '../brushes/types.js';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.js';
 import { type ImageEncoder, type ImageFormat } from './encode.js';
 import type { PenPoint } from './engine.js';
@@ -57,7 +60,12 @@ export interface PaintEditorOptions extends Partial<PaintCanvas> {
     paper?: Partial<PaperSettings> | string;
     /** Active brush id (default `pencil-6b`). */
     brushId?: string;
-    /** Saved user brushes to start the library with. */
+    /**
+     * The brush library: built-in presets plus saved brushes, on any storage. Pass one library to
+     * every editor so a brush saved in one shows in all of them (default: a library in memory).
+     */
+    brushLibrary?: BrushLibrary;
+    /** Saved user brushes to start the default library with (or to add to `brushLibrary`). */
     brushes?: readonly PaintBrush[];
     /** Paint colour #rrggbb (default #1f2937). */
     color?: string;
@@ -296,8 +304,17 @@ export declare class PaintEditorController {
     private undoStack;
     private redoStack;
     private readonly historyLimit;
+    /** The brush library this editor lists, saves into and paints from (shared with other editors when the host passes one). */
+    readonly brushLibrary: BrushLibrary;
     private brush;
-    private userBrushes;
+    /** The active brush as facets (what `getBrushSpec` and saving use). */
+    private brushSpec;
+    /** The library's brushes as last read, each as stored (facets) and as the engine paints it. */
+    private brushEntries;
+    /** The brush id asked for at construction, while the library had not listed it yet. */
+    private pendingBrushId;
+    private brushesLoaded;
+    private readonly unsubscribeLibrary;
     /** The library list in the state (the same array until the user brushes change, so thumbnails are not redrawn). */
     private library;
     private color;
@@ -673,39 +690,81 @@ export declare class PaintEditorController {
         source: PaintEffectSource;
         amount: number;
     }>;
+    private findEntry;
     private findBrush;
-    /** A library brush by id (`undefined` when unknown). */
-    getBrush(id: string): PaintBrush | undefined;
+    private requireEntry;
     private requireBrush;
+    /** Reads the library again (after a change anywhere it is shared). */
+    private refreshBrushes;
+    /** Resolves once the brush library has been read (user brushes kept in storage are listed from then on). */
+    whenBrushesLoaded(): Promise<void>;
+    /** A library brush by id, as the engine paints it (`undefined` when unknown). */
+    getBrush(id: string): PaintBrush | undefined;
+    /** A library brush by id as stored (its facets), or without an id the active brush as edited. */
+    getBrushSpec(id?: string): Brush | undefined;
     /**
-     * Chooses the active brush (`id`: a library brush) and / or changes its settings. Editor state,
-     * not an undo step. Returns the active brush.
+     * Chooses the active brush (`id`: a library brush) and / or changes its engine settings. Editor
+     * state, not an undo step. Returns the active brush. `setBrushFacets` changes it by facets.
      */
     setBrush(update?: {
         id?: string;
     } & Omit<PaintBrushInput, 'id'>): PaintBrush;
-    /** Saves the active brush (or `brush`) into the user library under `id` / `name`. */
+    /**
+     * Chooses the active brush (`id`: a library brush) and / or lays a facet patch over it (objects
+     * merge, lists and values replace, as the library's `update_brush` does). Editor state, not an
+     * undo step. `unset` removes whole facets first. Returns the active brush as the engine paints
+     * it, its facets, and what was clamped or dropped.
+     */
+    setBrushFacets(patch?: BrushPatch, id?: string, unset?: readonly UnsettableBrushFacet[]): {
+        brush: PaintBrush;
+        spec: Brush;
+        problems: string[];
+    };
+    /**
+     * Makes `spec` (a whole facet brush, as the brush editor edits it) the active brush, keeping the
+     * active brush's id. Editor state, not an undo step. Returns it as the engine paints it, its
+     * facets, and what was clamped or dropped.
+     */
+    setBrushSpec(spec: Brush): {
+        brush: PaintBrush;
+        spec: Brush;
+        problems: string[];
+    };
+    /**
+     * The engine settings a facet patch changes on a brush (`from`: a library brush id or a brush as
+     * painted; default the active brush), as `paintStroke`'s and `updateStroke`'s `brush` take them.
+     */
+    brushChanges(patch: BrushPatch, from?: string | PaintBrush): Omit<PaintBrushInput, 'id'>;
+    private readBrushPatch;
+    private useBrush;
+    /**
+     * Saves the active brush (or `brush`, engine settings on top of it) into the brush library under
+     * `id` / `name`, replacing a user brush with that id. Built-in ids are refused. Resolves with the
+     * saved brush.
+     */
     saveBrush(options: {
         id: string;
         name?: string;
         brush?: PaintBrushInput;
-    }): PaintBrush;
-    removeBrush(id: string): void;
-    /** The user's saved brushes. */
+    }): Promise<PaintBrush>;
+    /** Removes a user brush from the brush library (built-in brushes can't be removed). */
+    removeBrush(id: string): Promise<void>;
+    /** The user's saved brushes, as the engine paints them. */
     getUserBrushes(): PaintBrush[];
-    /** A brush library file of the given brushes (default: the user's brushes). */
-    exportBrushes(ids?: readonly string[]): BrushLibraryFile;
+    /** A brush library file (version 2) of the given brushes (default: the user's brushes). */
+    exportBrushes(ids?: readonly string[]): Promise<BrushLibraryFile>;
     /**
-     * Adds the brushes of a library file to the user library. A brush whose id is taken is skipped
-     * unless `replace` (built-in ids are always skipped). Returns the ids added and the problems.
+     * Adds the brushes of a library file (version 1 or 2) to the brush library. A brush whose id is
+     * taken is skipped unless `replace` (built-in ids are always skipped). Resolves with the ids
+     * added or replaced, the ids skipped and the problems.
      */
     importBrushes(file: unknown, options?: {
         replace?: boolean;
-    }): {
+    }): Promise<{
         added: string[];
         skipped: string[];
         problems: string[];
-    };
+    }>;
     /** A thumbnail of a brush: a test stroke on the current paper. */
     brushThumbnail(id: string, options?: {
         width?: number;