@pixerate/editor 0.254.0 → 0.255.0

package/dist/vector/index.js

@@ -26,7 +26,7 @@ import {
   traceField,
   traceVectorImage,
   vectorTraceContours
-} from "../chunk-2ZJ4DT3M.js";
+} from "../chunk-VUKUTT2W.js";
 import {
   applyHomography,
   homographyFromPoints,
@@ -53,7 +53,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-7P6VF3FG.js";
+} from "../chunk-HYWRU5VX.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -376,6 +376,8 @@ import {
   vectorBoundsInside,
   vectorBoxMatrix,
   vectorBrushstrokeBrush,
+  vectorBrushstrokeBrushError,
+  vectorBrushstrokeBrushOf,
   vectorBrushstrokeBrushes,
   vectorBrushstrokeCharacterError,
   vectorBrushstrokeImages,
@@ -526,8 +528,10 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-GYMMNCFT.js";
-import "../chunk-MTKY6K3Q.js";
+} from "../chunk-AF23QK5F.js";
+import {
+  snapshotBrushLibrary
+} from "../chunk-JVRLGV3C.js";
 import "../chunk-APX63ILU.js";
 import {
   createProvenance
@@ -3689,7 +3693,7 @@ function getVectorAppearancePanel(state) {
     ...kind === "stroke" ? { strokeWidth: l.strokeWidth ?? 1, strokeAlign: l.strokeAlign ?? "center" } : {},
     ...isVectorBrushstrokeLayer(l) ? (() => {
       const b = l.brush;
-      const preset = vectorBrushstrokeBrush(b.brushId);
+      const preset = vectorBrushstrokeBrushOf(b);
       return { brushstroke: { brushId: b.brushId, name: preset.name, size: b.size ?? preset.tip.size, ...b.seed !== void 0 ? { seed: b.seed } : {}, grain: b.seed !== void 0 && b.paper !== null } };
     })() : (l.kind ?? "paint") !== "paint" ? { unknownKind: String(l.kind) } : {},
     editing: edit.target === kind && (edit.layer === null ? index === count - 1 : edit.layer === index)
@@ -6818,6 +6822,7 @@ var VectorEditorController = class _VectorEditorController {
   revision = 0;
   state;
   constructor(options = {}) {
+    this.brushes = options.brushLibrary ? snapshotBrushLibrary(options.brushLibrary, () => this.notify()) : null;
     this.history = options.history ?? new HistoryManager();
     this.doc = options.document ? loadedDocument(options.document) : { width: 800, height: 600, nodes: [] };
     this.doc = this.refreshed(this.doc);
@@ -6853,6 +6858,16 @@ var VectorEditorController = 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). */
+  brushes;
+  /** The brushes a brushstroke can use: the presets, then the brush library's saved brushes the vector profile admits. */
+  listBrushstrokeBrushes() {
+    return vectorBrushstrokeBrushes(this.brushes?.user ?? []);
+  }
+  /** Resolves once the brush library has been read (its saved brushes can be used from then on). */
+  whenBrushesLoaded() {
+    return this.brushes?.ready ?? Promise.resolve();
+  }
   destroy() {
     if (this.dwellTimer) clearTimeout(this.dwellTimer);
     this.dwellTimer = null;
@@ -8163,15 +8178,17 @@ var VectorEditorController = class _VectorEditorController {
   }
   /**
    * 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`,
    * `null` for none); without one it renders plain. One undo step.
    */
   addBrushstroke(brush, options = {}) {
-    const clean = sanitizeVectorBrushstroke(brush);
-    if (!clean) return { ok: false, message: `Unknown brush "${brush?.brushId}": use one of ${vectorBrushstrokeBrushes().map((b) => b.id).join(", ")}.` };
+    const user = this.brushes?.user ?? [];
+    const brushError = typeof brush?.brushId === "string" ? vectorBrushstrokeBrushError(brush.brushId, user) : "brushId must be a brush id (vector.listBrushes lists them).";
+    const clean = brushError ? null : sanitizeVectorBrushstroke(brush, user);
+    if (!clean) return { ok: false, message: brushError ?? `Brush "${brush.brushId}" can't paint a brushstroke (vector.listBrushes lists the ones that can).` };
     if (brush.size !== void 0 && !(brush.size > 0 && brush.size <= 500)) return { ok: false, message: "size must be above 0 and at most 500 (document units)." };
     const characterError = vectorBrushstrokeCharacterError(brush);
     if (characterError) return { ok: false, message: characterError };
@@ -8193,7 +8210,9 @@ var VectorEditorController = class _VectorEditorController {
    * brushstroke. With `merge`, consecutive edits fold into one undo step.
    */
   setBrushstroke(index, patch, options = {}) {
-    if (patch.brushId !== void 0 && !vectorBrushstrokeBrush(patch.brushId)) return { ok: false, message: `Unknown brush "${patch.brushId}": use one of ${vectorBrushstrokeBrushes().map((b) => b.id).join(", ")}.` };
+    const user = this.brushes?.user ?? [];
+    const brushError = patch.brushId !== void 0 ? vectorBrushstrokeBrushError(patch.brushId, user) : null;
+    if (brushError) return { ok: false, message: brushError };
     if (patch.size !== void 0 && patch.size !== null && !(patch.size > 0 && patch.size <= 500)) return { ok: false, message: "size must be above 0 and at most 500 (document units)." };
     if (patch.color !== void 0 && !parseVectorColor(patch.color)) return { ok: false, message: `"${patch.color}" is not a colour.` };
     if (patch.opacity !== void 0 && !(patch.opacity >= 0 && patch.opacity <= 1)) return { ok: false, message: "opacity must be from 0 to 1." };
@@ -8207,7 +8226,7 @@ var VectorEditorController = class _VectorEditorController {
       (stack, path) => {
         const layer = stack[index];
         if (!layer || layer.kind !== "brushstroke" || !layer.brush) return `Path "${path.id}" has no brushstroke at stroke ${index} (vector.getAppearance lists its strokes; 0 is the bottom).`;
-        const brush = { ...layer.brush, ...patch.brushId ? { brushId: patch.brushId } : {} };
+        const brush = patch.brushId && patch.brushId !== layer.brush.brushId ? { ...layer.brush, brushId: patch.brushId, spec: void 0 } : { ...layer.brush };
         if (patch.size === null) delete brush.size;
         else if (patch.size !== void 0) brush.size = patch.size;
         if (patch.pressure === null) delete brush.pressure;
@@ -8215,7 +8234,7 @@ var VectorEditorController = class _VectorEditorController {
         if (patch.seed === null) delete brush.seed;
         else if (patch.seed !== void 0) brush.seed = patch.seed;
         if (patch.paper !== void 0) brush.paper = patch.paper;
-        const next = { ...layer, brush: sanitizeVectorBrushstroke(brush) ?? layer.brush, ...patch.color ? { paint: patch.color } : {}, ...patch.opacity !== void 0 ? { opacity: patch.opacity } : {} };
+        const next = { ...layer, brush: sanitizeVectorBrushstroke(brush, user) ?? layer.brush, ...patch.color ? { paint: patch.color } : {}, ...patch.opacity !== void 0 ? { opacity: patch.opacity } : {} };
         return stack.map((l, i) => i === index ? next : l);
       },
       merge
@@ -15894,9 +15913,9 @@ function createVectorCommands(controller, options = {}) {
       label: "Brushstroke Brushes",
       readOnly: true,
       keywords: ["brush", "brushstroke", "pencil", "pastel", "charcoal", "ink", "marker", "natural media"],
-      description: "Lists the brushes a brushstroke can use (the paint editor's dry brushes): { brushes: [{ id, name, category, size }] } (size: the brush's own diameter in document units).",
+      description: "Lists the brushes a brushstroke can use (the dry presets, then saved brushes from the brush library the vector profile admits): { brushes: [{ id, name, category, size, builtin }] } (size: the brush's own diameter in document units).",
       params: { type: "object", properties: {}, additionalProperties: false },
-      run: () => ({ brushes: vectorBrushstrokeBrushes().map((b) => ({ id: b.id, name: b.name, category: b.category, size: b.tip.size })) })
+      run: () => ({ brushes: controller.listBrushstrokeBrushes().map((b) => ({ id: b.id, name: b.name, category: b.category, size: b.tip.size, builtin: vectorBrushstrokeBrush(b.id) !== null })) })
     },
     {
       ...base,
@@ -18848,6 +18867,8 @@ export {
   vectorBoxCorners,
   vectorBoxMatrix,
   vectorBrushstrokeBrush,
+  vectorBrushstrokeBrushError,
+  vectorBrushstrokeBrushOf,
   vectorBrushstrokeBrushes,
   vectorBrushstrokeCharacterError,
   vectorBrushstrokeImages,

package/dist/vector/types.d.cts

@@ -2,6 +2,7 @@ import type { GenerationProvenance } from '../generation/provenance.cjs';
 import type { CanvasGradientDef } from '../canvas/gradient.cjs';
 import type { WarpMesh, WarpStyle } from '../geom/types.cjs';
 import type { GrainPattern } from '../paint/grain.cjs';
+import type { Brush } from '../brushes/types.cjs';
 /** An affine matrix `[a, b, c, d, e, f]`: `x' = a·x + c·y + e`, `y' = b·x + d·y + f` (SVG order). */
 export type VectorMatrix = readonly [number, number, number, number, number, number];
 /** A point in document coordinates. */
@@ -268,7 +269,13 @@ export interface VectorBrushstrokePaper {
  * renders plain dabs, as before, and `paper` is ignored.
  */
 export interface VectorBrushstroke {
+    /** A preset id, or a saved brush's id from the brush library. */
     brushId: string;
+    /**
+     * The saved brush `brushId` names (a facet brush of `@pixerate/editor/brushes`), embedded when it
+     * is not a preset, so the document renders without the library.
+     */
+    spec?: Brush;
     size?: number;
     pressure?: number[];
     /** Jitter seed, an integer 0–2147483647. Turns the brush's character on. */

package/dist/vector/types.d.ts

@@ -2,6 +2,7 @@ import type { GenerationProvenance } from '../generation/provenance.js';
 import type { CanvasGradientDef } from '../canvas/gradient.js';
 import type { WarpMesh, WarpStyle } from '../geom/types.js';
 import type { GrainPattern } from '../paint/grain.js';
+import type { Brush } from '../brushes/types.js';
 /** An affine matrix `[a, b, c, d, e, f]`: `x' = a·x + c·y + e`, `y' = b·x + d·y + f` (SVG order). */
 export type VectorMatrix = readonly [number, number, number, number, number, number];
 /** A point in document coordinates. */
@@ -268,7 +269,13 @@ export interface VectorBrushstrokePaper {
  * renders plain dabs, as before, and `paper` is ignored.
  */
 export interface VectorBrushstroke {
+    /** A preset id, or a saved brush's id from the brush library. */
     brushId: string;
+    /**
+     * The saved brush `brushId` names (a facet brush of `@pixerate/editor/brushes`), embedded when it
+     * is not a preset, so the document renders without the library.
+     */
+    spec?: Brush;
     size?: number;
     pressure?: number[];
     /** Jitter seed, an integer 0–2147483647. Turns the brush's character on. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.254.0",
+  "version": "0.255.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-brushes/SKILL.md

@@ -38,9 +38,15 @@ paints without (warnings), each with a fix; lists and writes use the current hos
 | Host | Renders |
 | --- | --- |
 | Paint editor (`paint`) | Everything. |
-| Image editor (`image`) | Dry dabs on round, flat and chisel tips, the Mixer Brush and the eraser; no wet or thick surface, particles, objects, light or motion. |
-| Canvas (`canvas`) | Dry dab brushes along a path (no tools, wet, thick, particles, objects or light); velocity is ignored. |
-| Vector strokes (`vector`) | As canvas, but light brushes paint as plain colour. |
+| Image editor (`image`) | Dry dabs on round, flat and chisel tips, the Mixer Brush and the eraser; no wet or thick surface, particles, objects, light or motion. Pick one with `set_brush_preset`. |
+| Canvas (`canvas`) | Dry dab brushes along a path (no tools, wet, thick, particles, objects or light); velocity is ignored. Draw with one as `canvas.drawFreehand` `brush`. |
+| Vector strokes (`vector`) | As canvas, but light brushes paint as plain colour. Draw with one as `vector.addBrushstroke` `brushId`. |
+
+Every host lists the presets its profile admits and the library's saved brushes it admits, and
+each registers these tools with its own profile, so `list_brush_presets` shows that host's brushes.
+A saved brush used in canvas or vector strokes is copied into the stroke, so the document renders
+where the library is not; changing the brush in the library later doesn't change strokes already
+drawn.
 
 ## Working method
 

package/skills/pixerate-canvas/SKILL.md

@@ -250,8 +250,8 @@ character: seeded jitter and the paper grain they catch) and, when a width was c
 
 | Command | Use it to |
 | --- | --- |
-| `canvas.drawFreehand` | Draw a pen or highlighter stroke through `points` (`[x, y]` pairs in canvas units, in drawing order; one undo step). `tool` picks the defaults (`pen`: blue, width 3; `highlighter`: yellow, width 24, opacity 0.35); `color`, `width`, `opacity` override them (with a `brush`, `width` is the brush diameter and defaults to the preset's own size). Pass `brush` (a preset id from `canvas.listBrushes`, or tip settings) to paint it with a dry brush, plus `pressure` / `tiltX` / `tiltY` profiles spread along its length (`[0.2, 1, 0.3]` swells in the middle). Add `paint` (only with `brush`) for gradient paint that changes colour along the stroke: `{ "type": "gradient", "stops": [...], "map": { "by": "distance", "length": 200 } }` (length in canvas units), or `by` `pressure`, `tilt`, `direction`, `across-tip`, `random`. Returns the node `id`, its `bounds` and the stored `brush` (with `paint` normalised: defaults filled in, colours lowercased). |
-| `canvas.listBrushes` | Read-only: the dry paint presets `canvas.drawFreehand` and the gestures accept as `brush` (`id`, `name`, `category`, the preset's own `size`, which a stroke uses unless you pass `width`). Call it before the first brushed stroke instead of guessing ids. |
+| `canvas.drawFreehand` | Draw a pen or highlighter stroke through `points` (`[x, y]` pairs in canvas units, in drawing order; one undo step). `tool` picks the defaults (`pen`: blue, width 3; `highlighter`: yellow, width 24, opacity 0.35); `color`, `width`, `opacity` override them (with a `brush`, `width` is the brush diameter and defaults to the preset's own size). Pass `brush` (a preset or saved brush id from `canvas.listBrushes`, or tip settings) to paint it with a dry brush, plus `pressure` / `tiltX` / `tiltY` profiles spread along its length (`[0.2, 1, 0.3]` swells in the middle). Add `paint` (only with `brush`) for gradient paint that changes colour along the stroke: `{ "type": "gradient", "stops": [...], "map": { "by": "distance", "length": 200 } }` (length in canvas units), or `by` `pressure`, `tilt`, `direction`, `across-tip`, `random`. Returns the node `id`, its `bounds` and the stored `brush` (with `paint` normalised: defaults filled in, colours lowercased). |
+| `canvas.listBrushes` | Read-only: the brushes `canvas.drawFreehand` and the gestures accept as `brush`: the dry presets, then saved brushes from the brush library the canvas can paint (`id`, `name`, `category`, the brush's own `size`, which a stroke uses unless you pass `width`, and `builtin`). Call it before the first brushed stroke instead of guessing ids. |
 
 Gestures draw one hand-drawn stroke node each (one undo step) through the same path as
 `canvas.drawFreehand`, and the agent's cursor traces them. Targets are boxes
@@ -348,9 +348,14 @@ effects provider (for example Flair); without one the read tools say so and the
 - **A shape node holds one effect.** `apply_effect` replaces the effect that is there. Effects draw on shape nodes only (nodes with `data.shape`).
 - **Effects belong to the provider they came from.** Each saved effect keeps its provider id. After the provider changes (another effects library), check `list_applied_effects` for `available: false` and re-apply those effects with ids from the new provider's `search_effects`; the old effect ids mean nothing to it.
 
-- **Brushes are dry only.** Wet presets (watercolour, gouache, wet oils), mixer, blender, smudge and
-  eraser presets are refused: wet paint needs an area to flow in, and the others need paint under
-  them. `pressure` and tilt without a `brush` are refused too.
+- **Brushes are dry only.** The canvas profile (`CANVAS_PROFILE`, see `pixerate-brushes`) refuses
+  wet and thick brushes (watercolour, gouache, wet oils, impasto), particle and sticker brushes,
+  tools (mixer, blender, smudge, eraser) and light brushes, saying why and which ids to use:
+  wet paint needs an area to flow in, tools need paint under them, light needs the paint editor's
+  light channel. Saved brushes from the brush library work when they are dry (`check_brush` with
+  `host: "canvas"` says, and gives a `degraded` brush to save instead); a stroke keeps a copy of
+  the saved brush, so it renders without the library. `pressure` and tilt without a `brush` are
+  refused too.
 - **Gradient paint needs a brush, and no timing.** `paint` without `brush` is refused; use
   `color` for a plain stroke. Canvas strokes record no timing, so `velocity` and `time` mappings
   are refused: use `distance` for colour that changes along the stroke. The stroke `color` still

package/skills/pixerate-image-editor/SKILL.md

@@ -313,7 +313,8 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `set_paint` | Set what the brush paints: one colour (it becomes the foreground) or gradient paint (`stops` sorted by offset, `space` pigment / oklab / srgb, `map`, `softness`). Errors say what is wrong. Returns `paint`, `foreground`, `background`, `brush`. |
 | `sample_color` | The Eyedropper: read the composite colour at a document point (`size` averages a square; default 1 px) and, unless `setForeground` is false, make it the paint foreground. Use it to match a colour already in the image before painting or retouching. Fails outside the canvas or on transparent pixels. Returns `color` and `foreground`. |
 | `sample_gradient` | Read the composite along a line (`start` → `end`, document pixels) and fit the fewest gradient stops to it (`tolerance` OKLab ΔE, `maxStops`, `sampleSize` averaging, `snapStep`). Changes nothing. Returns a linear `gradient` (angle of the line, oklab), its `css` and `pointsRead`. Use it to match a sky, a backdrop or a light falloff before painting a gradient or styling one. |
-| `get_paint` | Read-only. What the brush paints (`paint`), the foreground and background colours and the brush settings. |
+| `get_paint` | Read-only. What the brush paints (`paint`), the foreground and background colours, the brush settings, and `brushPreset` (the preset they came from, null once changed by hand). |
+| `set_brush_preset` | Paint with a brush from the brush library: `id` from `list_brush_presets` (the image host lists only what it can paint). Sets the paint tool it needs (`brush`, `mixer` for a Mixer Brush, `eraser`), its brush and mixer settings and a brush's own gradient. Refuses wet, thick, particle, sticker and light brushes with the reason. Returns `tool`, `brush`, `mixer`, `paint`, `warnings` (e.g. paper grain, which the image editor paints without). Then `paint_stroke` with that tool. |
 | `get_mixer_brush` | Read-only. The Mixer Brush settings and what it carries (`reservoir` #rrggbb or null, `amount` left 0..1, `pickup` #rrggbb or null). Call it before a mixer stroke with `loadEachStroke: false`. |
 | `load_mixer_brush` | Fill the Mixer Brush reservoir with `color` (default the foreground), amount 1; keeps the pickup. View state, not an undo step. Use before strokes with `loadEachStroke: false`. Returns the load. |
 | `clean_mixer_brush` | Empty the Mixer Brush pickup well (`emptyReservoir: true` also drops the loaded paint, so it only smears). View state, not an undo step. Returns the load. |

package/skills/pixerate-vector/SKILL.md

@@ -373,7 +373,7 @@ contents whole while you work, without losing the mask.
 
 | Command | Use it to |
 | --- | --- |
-| `vector.listBrushes` | List the natural-media brushes (pencils, pastels, charcoal, markers, inks) with their sizes. |
+| `vector.listBrushes` | List the brushes a brushstroke can use: the dry presets (pencils, pastels, charcoal, markers, inks), then saved brushes from the brush library the vector profile admits, with their sizes and `builtin`. Brushes it refuses (wet, thick, particles, stickers, tools) are refused by `vector.addBrushstroke` with the reason. A saved brush is kept in the layer, so the document renders without the library. |
 | `vector.addBrushstroke` | Paint paths with a brush along their outline (`brushId`, `size`, `pressure` profile such as [0.2, 1, 0.2] for a taper, `color`): sketchy, hand-drawn or inked lines that stay editable. Pass a `seed` (any integer) so the brush gets its character, the seeded jitter and paper grain that make pencil, pastel and charcoal look real; `paper` picks the grain (`{ pattern, seed, scale, depth }`) or `null` turns it off. Returns the stroke stacks. |
 | `vector.setBrushstroke` | Change brushstroke layer `index` of path `id`: brush, size, pressure, colour, opacity, `seed` (a new seed is a new take on the same stroke; null: plain dabs) and `paper` (replaced whole; null: no grain; {}: the default sanded paper). Remove it with `vector.removeStroke`. |