@pixerate/editor 0.254.1 → 0.256.0

package/dist/vector/brushstroke.d.cts

@@ -1,13 +1,29 @@
 import { type PaintBrush } from '../paint-editor/brushes.cjs';
+import type { Brush } from '../brushes/types.cjs';
 import type { VectorBrushstroke, VectorBrushstrokePaper, VectorPathNode, VectorStrokeLayer } from './types.cjs';
 /** Image pixels per document unit brushstrokes are rendered at. */
 export declare const VECTOR_BRUSHSTROKE_SCALE = 2;
-/** The brushes a brushstroke can use: the library's dry dab-engine brushes. */
-export declare function vectorBrushstrokeBrushes(): PaintBrush[];
-/** A brush from the library by id, or null. */
+/**
+ * The brushes a brushstroke can use, as the engine paints them: the presets `VECTOR_PROFILE`
+ * admits (dry dab-engine brushes), then the saved brushes given (facet brushes, e.g. a brush
+ * library's) it admits.
+ */
+export declare function vectorBrushstrokeBrushes(user?: readonly Brush[]): PaintBrush[];
+/** A preset by id, or null. */
 export declare function vectorBrushstrokeBrush(id: string): PaintBrush | null;
-/** Reads brushstroke settings from untrusted data; null when the brush is unknown. */
-export declare function sanitizeVectorBrushstroke(value: unknown): VectorBrushstroke | null;
+/** The engine brush a brushstroke paints with: its embedded saved brush, else the preset; null when neither renders. */
+export declare function vectorBrushstrokeBrushOf(brush: Pick<VectorBrushstroke, 'brushId' | 'spec'>): PaintBrush | null;
+/**
+ * Why a brush id can't paint a brushstroke (with the ids that can), or null when it can.
+ * `user` are the saved brushes on offer.
+ */
+export declare function vectorBrushstrokeBrushError(id: string, user?: readonly Brush[]): string | null;
+/**
+ * Reads brushstroke settings from untrusted data; null when the brush is unknown. A saved brush is
+ * taken from `value.spec` (a stored layer) or from `user` (the brush library's saved brushes) and
+ * kept in `spec`.
+ */
+export declare function sanitizeVectorBrushstroke(value: unknown, user?: readonly Brush[]): VectorBrushstroke | null;
 /** The largest brushstroke seed. */
 export declare const VECTOR_BRUSHSTROKE_MAX_SEED = 2147483647;
 /** Reads paper settings from untrusted data; null when there are none (the default paper). */

package/dist/vector/brushstroke.d.ts

@@ -1,13 +1,29 @@
 import { type PaintBrush } from '../paint-editor/brushes.js';
+import type { Brush } from '../brushes/types.js';
 import type { VectorBrushstroke, VectorBrushstrokePaper, VectorPathNode, VectorStrokeLayer } from './types.js';
 /** Image pixels per document unit brushstrokes are rendered at. */
 export declare const VECTOR_BRUSHSTROKE_SCALE = 2;
-/** The brushes a brushstroke can use: the library's dry dab-engine brushes. */
-export declare function vectorBrushstrokeBrushes(): PaintBrush[];
-/** A brush from the library by id, or null. */
+/**
+ * The brushes a brushstroke can use, as the engine paints them: the presets `VECTOR_PROFILE`
+ * admits (dry dab-engine brushes), then the saved brushes given (facet brushes, e.g. a brush
+ * library's) it admits.
+ */
+export declare function vectorBrushstrokeBrushes(user?: readonly Brush[]): PaintBrush[];
+/** A preset by id, or null. */
 export declare function vectorBrushstrokeBrush(id: string): PaintBrush | null;
-/** Reads brushstroke settings from untrusted data; null when the brush is unknown. */
-export declare function sanitizeVectorBrushstroke(value: unknown): VectorBrushstroke | null;
+/** The engine brush a brushstroke paints with: its embedded saved brush, else the preset; null when neither renders. */
+export declare function vectorBrushstrokeBrushOf(brush: Pick<VectorBrushstroke, 'brushId' | 'spec'>): PaintBrush | null;
+/**
+ * Why a brush id can't paint a brushstroke (with the ids that can), or null when it can.
+ * `user` are the saved brushes on offer.
+ */
+export declare function vectorBrushstrokeBrushError(id: string, user?: readonly Brush[]): string | null;
+/**
+ * Reads brushstroke settings from untrusted data; null when the brush is unknown. A saved brush is
+ * taken from `value.spec` (a stored layer) or from `user` (the brush library's saved brushes) and
+ * kept in `spec`.
+ */
+export declare function sanitizeVectorBrushstroke(value: unknown, user?: readonly Brush[]): VectorBrushstroke | null;
 /** The largest brushstroke seed. */
 export declare const VECTOR_BRUSHSTROKE_MAX_SEED = 2147483647;
 /** Reads paper settings from untrusted data; null when there are none (the default paper). */

package/dist/vector/controller.d.cts

@@ -1,3 +1,5 @@
+import { type BrushLibrary } from '../brushes/library.cjs';
+import type { PaintBrush } from '../paint-editor/brushes.cjs';
 import { type VectorStylizeOptions, type VectorStylizeStyle } from './stylize.cjs';
 import { type VectorDistortBrushMode } from './distortBrush.cjs';
 import { HistoryManager } from '../history/HistoryManager.cjs';
@@ -97,6 +99,11 @@ export declare const DEFAULT_VECTOR_PATH_EDIT: Readonly<VectorPathEditOptions>;
 export declare const VECTOR_PENCIL_STRING_PX = 100;
 export interface VectorEditorOptions {
     document?: VectorDocument;
+    /**
+     * The brush library whose saved brushes brushstrokes may use besides the presets (the vector
+     * profile decides which). Share one with the paint editor so a brush saved there paints here.
+     */
+    brushLibrary?: Pick<BrushLibrary, 'list' | 'subscribe'>;
     /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
     history?: HistoryManager;
     /** Starting tool (default `select`). */
@@ -790,6 +797,12 @@ export declare class VectorEditorController {
      * Stops listening to the history and drops all listeners. A later `subscribe` reconnects, so a
      * controller torn down by React StrictMode's double effect keeps working when it is reused.
      */
+    /** The saved brushes of the brush library as last read (empty without one). */
+    private brushes;
+    /** The brushes a brushstroke can use: the presets, then the brush library's saved brushes the vector profile admits. */
+    listBrushstrokeBrushes(): PaintBrush[];
+    /** Resolves once the brush library has been read (its saved brushes can be used from then on). */
+    whenBrushesLoaded(): Promise<void>;
     destroy(): void;
     /** The current snapshot (stable until the next change). */
     getState: () => VectorEditorState;
@@ -1102,7 +1115,7 @@ export declare class VectorEditorController {
     }): VectorActionResult;
     /**
      * Adds a brushstroke to the selected (or given) paths: a stroke layer that paints the path with
-     * brush `brushId` from the paint editor's library (`vectorBrushstrokeBrushes`), `size` document
+     * brush `brushId` (a preset, or a saved brush of the brush library: `listBrushstrokeBrushes`), `size` document
      * units across (default the brush's own), an optional `pressure` profile along the length, in
      * `color` (default the top stroke's paint, else black) at `opacity`. At the top of the stroke
      * stack or at `index`. A `seed` gives it the brush's character (jitter and the grain of `paper`,

package/dist/vector/controller.d.ts

@@ -1,3 +1,5 @@
+import { type BrushLibrary } from '../brushes/library.js';
+import type { PaintBrush } from '../paint-editor/brushes.js';
 import { type VectorStylizeOptions, type VectorStylizeStyle } from './stylize.js';
 import { type VectorDistortBrushMode } from './distortBrush.js';
 import { HistoryManager } from '../history/HistoryManager.js';
@@ -97,6 +99,11 @@ export declare const DEFAULT_VECTOR_PATH_EDIT: Readonly<VectorPathEditOptions>;
 export declare const VECTOR_PENCIL_STRING_PX = 100;
 export interface VectorEditorOptions {
     document?: VectorDocument;
+    /**
+     * The brush library whose saved brushes brushstrokes may use besides the presets (the vector
+     * profile decides which). Share one with the paint editor so a brush saved there paints here.
+     */
+    brushLibrary?: Pick<BrushLibrary, 'list' | 'subscribe'>;
     /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
     history?: HistoryManager;
     /** Starting tool (default `select`). */
@@ -790,6 +797,12 @@ export declare class VectorEditorController {
      * Stops listening to the history and drops all listeners. A later `subscribe` reconnects, so a
      * controller torn down by React StrictMode's double effect keeps working when it is reused.
      */
+    /** The saved brushes of the brush library as last read (empty without one). */
+    private brushes;
+    /** The brushes a brushstroke can use: the presets, then the brush library's saved brushes the vector profile admits. */
+    listBrushstrokeBrushes(): PaintBrush[];
+    /** Resolves once the brush library has been read (its saved brushes can be used from then on). */
+    whenBrushesLoaded(): Promise<void>;
     destroy(): void;
     /** The current snapshot (stable until the next change). */
     getState: () => VectorEditorState;
@@ -1102,7 +1115,7 @@ export declare class VectorEditorController {
     }): VectorActionResult;
     /**
      * Adds a brushstroke to the selected (or given) paths: a stroke layer that paints the path with
-     * brush `brushId` from the paint editor's library (`vectorBrushstrokeBrushes`), `size` document
+     * brush `brushId` (a preset, or a saved brush of the brush library: `listBrushstrokeBrushes`), `size` document
      * units across (default the brush's own), an optional `pressure` profile along the length, in
      * `color` (default the top stroke's paint, else black) at `opacity`. At the top of the stroke
      * stack or at `index`. A `seed` gives it the brush's character (jitter and the grain of `paper`,