@pixerate/editor 0.254.0 → 0.255.0

package/dist/canvas/brushstroke.d.ts

@@ -8,8 +8,10 @@
 import { brushstrokeScaleBucket } from '../paint/brushstroke-scale.js';
 import { type PathShape, type ShapeDescription, type ShapeSize } from './shapeGeometry.js';
 import type { Point } from './types.js';
-import type { CanvasBrush, CanvasBrushPaint, CanvasBrushPreset, CanvasBrushstroke } from './brushTypes.js';
-export type { CanvasBrush, CanvasBrushPaint, CanvasBrushPaintMapping, CanvasBrushPaintStop, CanvasBrushPaper, CanvasBrushPreset, CanvasBrushSettings, CanvasBrushstroke } from './brushTypes.js';
+import type { CanvasBrush, CanvasBrushPaint, CanvasBrushPreset, CanvasBrushSpec, CanvasBrushstroke } from './brushTypes.js';
+import type { BrushLibrary } from '../brushes/library.js';
+import type { BrushPreviewRenderer } from '../brushes/tools.js';
+export type { CanvasBrush, CanvasBrushPaint, CanvasBrushPaintMapping, CanvasBrushPaintStop, CanvasBrushPaper, CanvasBrushPreset, CanvasBrushSettings, CanvasBrushSpec, CanvasBrushstroke } from './brushTypes.js';
 export { brushstrokeScaleBucket };
 /** A brushed stroke's image, placed in the path's coordinates (the shape's view box). */
 export interface CanvasBrushstrokeImage {
@@ -40,9 +42,12 @@ export declare function pathDataToPolyline(d: string, step?: number): Point[];
 export declare function profileAlongPolyline(points: readonly Point[], values: readonly number[], count?: number): number[];
 /** The renderer chunk (`./brushstrokeRender.ts`). */
 export interface CanvasBrushstrokeRenderer {
-    listCanvasBrushes(): CanvasBrushPreset[];
-    /** Throws for an unknown or non-dry brush; the result is the paint engine's brush. */
-    resolveCanvasBrush(brush: CanvasBrush, width: number): unknown;
+    /** The presets, then the saved brushes given (facet brushes) the canvas profile admits. */
+    listCanvasBrushes(user?: readonly unknown[]): CanvasBrushPreset[];
+    /** Throws for an unknown brush or one the canvas profile refuses; the result is the paint engine's brush. */
+    resolveCanvasBrush(brush: CanvasBrush, width: number | undefined, spec?: unknown): unknown;
+    /** A saved brush checked against the canvas profile (throws with the reason and fix). */
+    readCanvasBrushSpec(spec: unknown): unknown;
     /** Throws for paint that is not a colour or gradient paint a canvas stroke can use; the result is the paint engine's `PaintSource`. */
     resolveCanvasPaint(paint: unknown): unknown;
     renderShapeBrushstrokeNow(shape: BrushedPathShape, scale: number, place?: {
@@ -52,7 +57,7 @@ export interface CanvasBrushstrokeRenderer {
         };
         unit?: number;
     }): CanvasBrushstrokeImage | null;
-    brushSwatchNow(brush: CanvasBrush, options: CanvasBrushSwatchOptions): string;
+    brushSwatchNow(brush: CanvasBrush, options: CanvasBrushSwatchOptions, spec?: CanvasBrushSpec): string;
     brushedShapeSvgNow(shape: BrushedPathShape, size: ShapeSize, scale: number, place?: {
         origin?: {
             x: number;
@@ -66,13 +71,24 @@ export interface CanvasBrushstrokeRenderer {
  * colour parser). Called for you by the functions below; call it early to warm up.
  */
 export declare function loadCanvasBrushstrokeRenderer(): Promise<CanvasBrushstrokeRenderer>;
-/** The dry paint presets a freehand stroke can use (wet, mixer, blender, smudge and eraser presets are left out). */
-export declare function listCanvasBrushes(): Promise<CanvasBrushPreset[]>;
 /**
- * Checks a brush: an unknown preset id, a wet (or other non-dry) preset, or settings that are not
- * an object throw an error saying which presets can be used.
+ * The brushes a freehand stroke can use: the presets `CANVAS_PROFILE` admits (dry dab brushes; wet,
+ * mixer, blender, smudge, eraser and light presets are left out), then the saved brushes of
+ * `library` it admits.
  */
-export declare function validateCanvasBrush(brush: CanvasBrush): Promise<void>;
+export declare function listCanvasBrushes(library?: Pick<BrushLibrary, 'list'>): Promise<CanvasBrushPreset[]>;
+/**
+ * The saved brush a stroke should embed for `brush`: the library's brush when `brush` names a saved
+ * one (checked against the canvas profile), else undefined (a preset or tip settings). Throws
+ * saying why a saved brush can't brush a stroke.
+ */
+export declare function resolveCanvasBrushSpec(brush: CanvasBrush, library?: Pick<BrushLibrary, 'get' | 'isBuiltin'>): Promise<CanvasBrushSpec | undefined>;
+/**
+ * Checks a brush: an unknown id, a brush the canvas profile refuses (wet, a tool, light…), or
+ * settings that are not an object throw an error saying why and which brushes can be used.
+ * `spec` is the saved brush `brush` names (`resolveCanvasBrushSpec`).
+ */
+export declare function validateCanvasBrush(brush: CanvasBrush, spec?: CanvasBrushSpec): Promise<void>;
 /**
  * Checks a brushed stroke's `paint` (a colour or gradient paint): bad stops, an unknown mapping,
  * or a mapping that needs timed samples (`velocity`, `time`) throw an error saying what to use.
@@ -119,4 +135,10 @@ export interface CanvasBrushSwatchOptions {
  * and grain), its size capped to fit, as a PNG data URL ('' when nothing renders). Throws for an
  * unknown or non-dry brush.
  */
-export declare function renderCanvasBrushSwatch(brush: CanvasBrush, options?: CanvasBrushSwatchOptions): Promise<string>;
+export declare function renderCanvasBrushSwatch(brush: CanvasBrush, options?: CanvasBrushSwatchOptions, spec?: CanvasBrushSpec): Promise<string>;
+/**
+ * `preview_brush` for brushed strokes (canvas and vector): the brush library tools' renderer
+ * (`createBrushLibraryToolProvider(library, { profile: CANVAS_PROFILE, renderPreview: renderCanvasBrushPreview })`),
+ * a swatch of the brush as a canvas stroke paints it. Loads the renderer on first use.
+ */
+export declare const renderCanvasBrushPreview: BrushPreviewRenderer;

package/dist/canvas/brushstrokeRender.d.cts

@@ -1,18 +1,24 @@
 /**
  * The lazily loaded half of brushed freehand strokes (`./brushstroke.ts` imports it on first use):
- * the paint engine's dry brushstroke renderer, the paint presets and a CSS colour parser. Keep
- * every import of the paint engine in this file, so the canvas entry never reaches it statically.
+ * the paint engine's dry brushstroke renderer, the brush presets and host profile, and a CSS
+ * colour parser. Keep every import of the paint engine and the presets in this file, so the canvas
+ * entry never reaches them statically.
  */
 import { type BrushstrokeBrush } from '../paint/brushstroke.cjs';
 import { type PaintSource } from '../paint/gradient-paint.cjs';
+import type { Brush } from '../brushes/types.cjs';
 import { type ShapeSize } from './shapeGeometry.cjs';
-import { type BrushedPathShape, type CanvasBrushSwatchOptions, type CanvasBrush, type CanvasBrushPaint, type CanvasBrushPreset, type CanvasBrushstrokeImage } from './brushstroke.cjs';
-export declare function listCanvasBrushes(): CanvasBrushPreset[];
+import { type BrushedPathShape, type CanvasBrushSwatchOptions, type CanvasBrush, type CanvasBrushPaint, type CanvasBrushPreset, type CanvasBrushSpec, type CanvasBrushstrokeImage } from './brushstroke.cjs';
+/** A saved brush, normalised and checked against the canvas profile; throws saying why it can't brush a stroke. */
+export declare function readCanvasBrushSpec(spec: CanvasBrushSpec | unknown): Brush;
+/** The presets, then the saved brushes (`user`, facet brushes) the canvas can paint. */
+export declare function listCanvasBrushes(user?: readonly unknown[]): CanvasBrushPreset[];
 /**
- * The paint engine brush for a canvas brush at diameter `width` (undefined: the preset's own size,
- * or the settings' `size`, else 3); throws with the usable ids.
+ * The paint engine brush for a canvas brush at diameter `width` (undefined: the brush's own size,
+ * or the settings' `size`, else 3). `spec` is the saved brush a stroke embeds when `brush` names
+ * one. Throws with the reason and the usable ids.
  */
-export declare function resolveCanvasBrush(brush: CanvasBrush, width: number | undefined): BrushstrokeBrush;
+export declare function resolveCanvasBrush(brush: CanvasBrush, width: number | undefined, spec?: CanvasBrushSpec | unknown): BrushstrokeBrush;
 /**
  * The paint engine's `PaintSource` for a brushed stroke's `paint`; throws with what is wrong.
  * Mappings that need timed samples (`velocity`, `time`) are refused: canvas strokes carry no timing.
@@ -32,4 +38,4 @@ export declare function brushedShapeSvgNow(shape: BrushedPathShape, size: ShapeS
     };
     unit?: number;
 }): string;
-export declare function brushSwatchNow(brush: CanvasBrush, options: CanvasBrushSwatchOptions): string;
+export declare function brushSwatchNow(brush: CanvasBrush, options: CanvasBrushSwatchOptions, spec?: CanvasBrushSpec): string;

package/dist/canvas/brushstrokeRender.d.ts

@@ -1,18 +1,24 @@
 /**
  * The lazily loaded half of brushed freehand strokes (`./brushstroke.ts` imports it on first use):
- * the paint engine's dry brushstroke renderer, the paint presets and a CSS colour parser. Keep
- * every import of the paint engine in this file, so the canvas entry never reaches it statically.
+ * the paint engine's dry brushstroke renderer, the brush presets and host profile, and a CSS
+ * colour parser. Keep every import of the paint engine and the presets in this file, so the canvas
+ * entry never reaches them statically.
  */
 import { type BrushstrokeBrush } from '../paint/brushstroke.js';
 import { type PaintSource } from '../paint/gradient-paint.js';
+import type { Brush } from '../brushes/types.js';
 import { type ShapeSize } from './shapeGeometry.js';
-import { type BrushedPathShape, type CanvasBrushSwatchOptions, type CanvasBrush, type CanvasBrushPaint, type CanvasBrushPreset, type CanvasBrushstrokeImage } from './brushstroke.js';
-export declare function listCanvasBrushes(): CanvasBrushPreset[];
+import { type BrushedPathShape, type CanvasBrushSwatchOptions, type CanvasBrush, type CanvasBrushPaint, type CanvasBrushPreset, type CanvasBrushSpec, type CanvasBrushstrokeImage } from './brushstroke.js';
+/** A saved brush, normalised and checked against the canvas profile; throws saying why it can't brush a stroke. */
+export declare function readCanvasBrushSpec(spec: CanvasBrushSpec | unknown): Brush;
+/** The presets, then the saved brushes (`user`, facet brushes) the canvas can paint. */
+export declare function listCanvasBrushes(user?: readonly unknown[]): CanvasBrushPreset[];
 /**
- * The paint engine brush for a canvas brush at diameter `width` (undefined: the preset's own size,
- * or the settings' `size`, else 3); throws with the usable ids.
+ * The paint engine brush for a canvas brush at diameter `width` (undefined: the brush's own size,
+ * or the settings' `size`, else 3). `spec` is the saved brush a stroke embeds when `brush` names
+ * one. Throws with the reason and the usable ids.
  */
-export declare function resolveCanvasBrush(brush: CanvasBrush, width: number | undefined): BrushstrokeBrush;
+export declare function resolveCanvasBrush(brush: CanvasBrush, width: number | undefined, spec?: CanvasBrushSpec | unknown): BrushstrokeBrush;
 /**
  * The paint engine's `PaintSource` for a brushed stroke's `paint`; throws with what is wrong.
  * Mappings that need timed samples (`velocity`, `time`) are refused: canvas strokes carry no timing.
@@ -32,4 +38,4 @@ export declare function brushedShapeSvgNow(shape: BrushedPathShape, size: ShapeS
     };
     unit?: number;
 }): string;
-export declare function brushSwatchNow(brush: CanvasBrush, options: CanvasBrushSwatchOptions): string;
+export declare function brushSwatchNow(brush: CanvasBrush, options: CanvasBrushSwatchOptions, spec?: CanvasBrushSpec): string;

package/dist/canvas/changeFeed.d.cts

@@ -39,6 +39,12 @@ export interface CanvasChange<TNode extends CanvasNode = CanvasNode, TEdge exten
     };
     /** A node is being dragged or resized: more changes of the same gesture will follow. */
     inGesture: boolean;
+    /**
+     * The drag or resize that earlier changes reported (`inGesture`) has ended. Set on the first
+     * change after it, which the feed reports even when nothing else changed: a drop often only
+     * clears the runtime `dragging` flag, and followers need to know the gesture is over.
+     */
+    gestureEnded?: true;
     /** Milliseconds since the epoch. */
     at: number;
 }

package/dist/canvas/changeFeed.d.ts

@@ -39,6 +39,12 @@ export interface CanvasChange<TNode extends CanvasNode = CanvasNode, TEdge exten
     };
     /** A node is being dragged or resized: more changes of the same gesture will follow. */
     inGesture: boolean;
+    /**
+     * The drag or resize that earlier changes reported (`inGesture`) has ended. Set on the first
+     * change after it, which the feed reports even when nothing else changed: a drop often only
+     * clears the runtime `dragging` flag, and followers need to know the gesture is over.
+     */
+    gestureEnded?: true;
     /** Milliseconds since the epoch. */
     at: number;
 }

package/dist/canvas/drawController.d.cts

@@ -5,7 +5,8 @@
 import type { ArrangeHistoryTarget } from './arrangeController.cjs';
 import type { CanvasNode, Point } from './types.cjs';
 import { type FreehandDrawOptions, type FreehandPenSample, type FreehandStroke, type FreehandStrokeStyle, type FreehandTool } from './freehand.cjs';
-import { listCanvasBrushes } from './brushstroke.cjs';
+import { type CanvasBrush } from './brushstroke.cjs';
+import type { BrushLibrary } from '../brushes/library.cjs';
 /** A stroke drawn by code or an agent (`drawStroke`). */
 export interface DrawStrokeInput {
     /** Points in canvas (flow) coordinates, at least one. */
@@ -36,6 +37,11 @@ export interface DrawStrokeResult<TNode extends CanvasNode = CanvasNode> {
     brush?: unknown;
 }
 export interface CanvasDrawControllerOptions<TNode extends CanvasNode = CanvasNode> {
+    /**
+     * The brush library whose saved brushes strokes may use besides the presets (the canvas
+     * profile decides which). Share one with the paint editor so a brush saved there draws here.
+     */
+    brushLibrary?: Pick<BrushLibrary, 'list' | 'get' | 'isBuiltin'>;
     getNodes: () => TNode[];
     setNodes: (nodes: TNode[]) => void;
     history?: ArrangeHistoryTarget;
@@ -68,8 +74,10 @@ export declare function createCanvasDrawController<TNode extends CanvasNode = Ca
         width: number;
         height: number;
     } | undefined;
-    /** The dry paint presets a stroke can be brushed with (loads the paint engine). */
-    listBrushes: typeof listCanvasBrushes;
+    /** The presets and saved brushes (of `brushLibrary`) a stroke can be brushed with (loads the paint engine). */
+    listBrushes: () => Promise<import("./brushTypes.cjs").CanvasBrushPreset[]>;
+    /** The saved brush to embed for a brush id (undefined for presets and tip settings); for a brush picker. */
+    brushSpec: (brush: CanvasBrush) => Promise<import("./brushTypes.cjs").CanvasBrushSpec | undefined>;
 };
 export type CanvasDrawController = ReturnType<typeof createCanvasDrawController>;
 /** Modifier options when computing bounds while dragging/drawing. */

package/dist/canvas/drawController.d.ts

@@ -5,7 +5,8 @@
 import type { ArrangeHistoryTarget } from './arrangeController.js';
 import type { CanvasNode, Point } from './types.js';
 import { type FreehandDrawOptions, type FreehandPenSample, type FreehandStroke, type FreehandStrokeStyle, type FreehandTool } from './freehand.js';
-import { listCanvasBrushes } from './brushstroke.js';
+import { type CanvasBrush } from './brushstroke.js';
+import type { BrushLibrary } from '../brushes/library.js';
 /** A stroke drawn by code or an agent (`drawStroke`). */
 export interface DrawStrokeInput {
     /** Points in canvas (flow) coordinates, at least one. */
@@ -36,6 +37,11 @@ export interface DrawStrokeResult<TNode extends CanvasNode = CanvasNode> {
     brush?: unknown;
 }
 export interface CanvasDrawControllerOptions<TNode extends CanvasNode = CanvasNode> {
+    /**
+     * The brush library whose saved brushes strokes may use besides the presets (the canvas
+     * profile decides which). Share one with the paint editor so a brush saved there draws here.
+     */
+    brushLibrary?: Pick<BrushLibrary, 'list' | 'get' | 'isBuiltin'>;
     getNodes: () => TNode[];
     setNodes: (nodes: TNode[]) => void;
     history?: ArrangeHistoryTarget;
@@ -68,8 +74,10 @@ export declare function createCanvasDrawController<TNode extends CanvasNode = Ca
         width: number;
         height: number;
     } | undefined;
-    /** The dry paint presets a stroke can be brushed with (loads the paint engine). */
-    listBrushes: typeof listCanvasBrushes;
+    /** The presets and saved brushes (of `brushLibrary`) a stroke can be brushed with (loads the paint engine). */
+    listBrushes: () => Promise<import("./brushTypes.js").CanvasBrushPreset[]>;
+    /** The saved brush to embed for a brush id (undefined for presets and tip settings); for a brush picker. */
+    brushSpec: (brush: CanvasBrush) => Promise<import("./brushTypes.js").CanvasBrushSpec | undefined>;
 };
 export type CanvasDrawController = ReturnType<typeof createCanvasDrawController>;
 /** Modifier options when computing bounds while dragging/drawing. */

package/dist/canvas/freehand.d.cts

@@ -6,7 +6,7 @@ import type { CanvasNode, Point, Rect } from './types.cjs';
 import { type FitPathDataOptions } from './curveFit.cjs';
 export type FreehandTool = 'select' | 'pen' | 'highlighter' | 'eraser';
 import type { CanvasGradientDef } from './gradient.cjs';
-import type { CanvasBrush, CanvasBrushPaint, CanvasBrushstroke } from './brushTypes.cjs';
+import type { CanvasBrush, CanvasBrushPaint, CanvasBrushSpec, CanvasBrushstroke } from './brushTypes.cjs';
 export interface FreehandStrokeStyle {
     /** Stroke color (any CSS color string) or gradient definition. */
     color: string | CanvasGradientDef;
@@ -36,6 +36,11 @@ export interface FreehandStrokeStyle {
      * along the path; `color` still gives the alpha and fills `paint` stops. Only with `brush`.
      */
     paint?: CanvasBrushPaint;
+    /**
+     * The saved brush `brush` names, when it is one from a brush library rather than a preset:
+     * strokes embed it so they render without the library. A brush picker sets it with `brush`.
+     */
+    brushSpec?: CanvasBrushSpec;
 }
 /** Pen data for one freehand point (Pointer Events: pressure 0..1, tilt in degrees). */
 export interface FreehandPenSample {

package/dist/canvas/freehand.d.ts

@@ -6,7 +6,7 @@ import type { CanvasNode, Point, Rect } from './types.js';
 import { type FitPathDataOptions } from './curveFit.js';
 export type FreehandTool = 'select' | 'pen' | 'highlighter' | 'eraser';
 import type { CanvasGradientDef } from './gradient.js';
-import type { CanvasBrush, CanvasBrushPaint, CanvasBrushstroke } from './brushTypes.js';
+import type { CanvasBrush, CanvasBrushPaint, CanvasBrushSpec, CanvasBrushstroke } from './brushTypes.js';
 export interface FreehandStrokeStyle {
     /** Stroke color (any CSS color string) or gradient definition. */
     color: string | CanvasGradientDef;
@@ -36,6 +36,11 @@ export interface FreehandStrokeStyle {
      * along the path; `color` still gives the alpha and fills `paint` stops. Only with `brush`.
      */
     paint?: CanvasBrushPaint;
+    /**
+     * The saved brush `brush` names, when it is one from a brush library rather than a preset:
+     * strokes embed it so they render without the library. A brush picker sets it with `brush`.
+     */
+    brushSpec?: CanvasBrushSpec;
 }
 /** Pen data for one freehand point (Pointer Events: pressure 0..1, tilt in degrees). */
 export interface FreehandPenSample {