@pixerate/editor 0.252.0 → 0.254.0

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;