@pixerate/editor 0.254.1 → 0.256.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.1",
+  "version": "0.256.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-paint-editor/SKILL.md

@@ -101,58 +101,32 @@ the pitfalls, and uses the tools below.
 
 ## Best practices
 
-- **Big to small, dark to light (or light to dark), one decision per layer.** Name layers by
-  purpose ("Underpainting", "Shadows", "Line"). Lower a layer's `opacity` instead of repainting.
-- **Pressure is your value control** on grainy media: points with `pressure` 0.2..0.4 give
-  texture-catching, broken marks; 0.8..1 fills the grain. Vary pressure along a stroke (swell in
-  the middle, lighten at the ends) for natural marks.
-- **Give points a time `t`** (milliseconds, about 8..16 ms apart for natural speed) when using an
-  ink or brush pen: velocity dynamics thin fast strokes. Without `t` there is no velocity effect.
-- **Tilt** (`altitude` near 0.3..0.6 radians with an `azimuth`) turns a pencil into broad side
-  shading; upright points draw a fine line.
-- **Space points** about a third of the brush size apart or closer; the brush fills in dabs
-  between them. Long smooth curves need more points than straight lines.
-- **Use `rotation: "stroke"`** for flat tips (pastel, charcoal, chisel marker) so the mark turns
-  with the path; `fixed` for calligraphic nibs.
+- **Big to small, dark to light (or light to dark), one decision per layer.** Name layers by purpose ("Underpainting", "Shadows", "Line"). Lower a layer's `opacity` instead of repainting.
+- **Pressure is your value control** on grainy media: points with `pressure` 0.2..0.4 give texture-catching, broken marks; 0.8..1 fills the grain. Vary pressure along a stroke (swell in the middle, lighten at the ends) for natural marks.
+- **Give points a time `t`** (milliseconds, about 8..16 ms apart for natural speed) when using an ink or brush pen: velocity dynamics thin fast strokes. Without `t` there is no velocity effect.
+- **Tilt** (`altitude` near 0.3..0.6 radians with an `azimuth`) turns a pencil into broad side shading; upright points draw a fine line.
+- **Space points** about a third of the brush size apart or closer; the brush fills in dabs between them. Long smooth curves need more points than straight lines.
+- **Use `rotation: "stroke"`** for flat tips (pastel, charcoal, chisel marker) so the mark turns with the path; `fixed` for calligraphic nibs.
 - **Blending tools**:
-  - `blender`: `strength` 0.3..0.6 for soft transitions, `distance` 0.2..0.5 (fraction of the
-    tip) for how far colours travel. Keep `mixing: "pigment"` for painterly blends; `rgb`
-    blends like a soft blur. Work along an edge in short strokes rather than over everything.
-  - `smudge`: `length` near 0.9 drags paint far (long streaks), 0.5 short pushes; `strength`
-    0.5..0.8. `mixing: "pigment"` (the `wet-smudge` preset) smears colours into each other like
-    wet paint.
+  - `blender`: `strength` 0.3..0.6 for soft transitions, `distance` 0.2..0.5 (fraction of the tip) for how far colours travel. Keep `mixing: "pigment"` for painterly blends; `rgb` blends like a soft blur. Work along an edge in short strokes rather than over everything.
+  - `smudge`: `length` near 0.9 drags paint far (long streaks), 0.5 short pushes; `strength` 0.5..0.8. `mixing: "pigment"` (the `wet-smudge` preset) smears colours into each other like wet paint.
   - Mixer Brush: blend with flow 0.3..0.6; at full flow it paints only its own colour.
-- **Pick-up and mix ratios**: `pickup` 0.3..0.7 with `mix` 0.4..0.7 gives a brush that drags
-  the colours it crosses into its own; `dirty: true` keeps them for the next stroke (wipe with
+- **Pick-up and mix ratios**: `pickup` 0.3..0.7 with `mix` 0.4..0.7 gives a brush that drags the colours it crosses into its own; `dirty: true` keeps them for the next stroke (wipe with
   `clean_mixer_brush`). Keep `pickup` 0 for clean, predictable colour.
-- **Multi-colour**: give 2..8 `colors` (or none for the paint and secondary colours). `tip` mode
-  with a flat tip and `rotation: "stroke"` paints ribbons; `softness` 0.3..0.7 keeps the stripes
-  readable. `dab` mode with `order: "sequence"` and `length` 5..20 walks through a palette;
+- **Multi-colour**: give 2..8 `colors` (or none for the paint and secondary colours). `tip` mode with a flat tip and `rotation: "stroke"` paints ribbons; `softness` 0.3..0.7 keeps the stripes readable. `dab` mode with `order: "sequence"` and `length` 5..20 walks through a palette;
   `random` for foliage and confetti.
-- **Pigment for paint, multiply for markers**: tip `blend: "pigment"` mixes subtractively on the
-  canvas; `multiply` darkens where marker strokes overlap. Pigment layers are written as Normal
-  to PSD (the export warns).
+- **Pigment for paint, multiply for markers**: tip `blend: "pigment"` mixes subtractively on the canvas; `multiply` darkens where marker strokes overlap. Pigment layers are written as Normal to PSD (the export warns).
 - **Painterly layer modes do the glazing for you** (`update_layer` `blend`, or a brush tip):
-  - `watercolor`: the layer is a transparent wash. Washes multiply wavelength by wavelength, so
-    each glaze darkens and blue over yellow makes green. White is clear: paint glazes on a
-    layer over the underpainting, at opacity 0.4..0.8.
-  - `tint`: recolours what is below (its hue and chroma) and keeps its lightness, gently near
-    white and black. Use it to warm or cool a whole passage.
-  - `highlight`: adds coloured light that rolls off towards white instead of clipping. Use it
-    for glints and glow; black does nothing.
-  - `shadow`: shades as if light were blocked, coloured by the layer (paint shadows in a cool
-    blue-violet), never crushing to black. White does nothing.
-
-  PSD has none of them: `export_psd` writes the nearest standard mode (watercolor and shadow
-  as Multiply, tint as Color, highlight as Screen) and warns; the merged image stays exact.
-- **Grow the canvas instead of starting big** with `extend_canvas` (pixels per side; nothing
-  painted moves relative to anything else). Adding `left` or `top` shifts every coordinate you
-  hold by (+left, +top): re-read `list_layers` or use the returned `rect`. Dry wet paint first.
+  - `watercolor`: the layer is a transparent wash. Washes multiply wavelength by wavelength, so each glaze darkens and blue over yellow makes green. White is clear: paint glazes on a layer over the underpainting, at opacity 0.4..0.8.
+  - `tint`: recolours what is below (its hue and chroma) and keeps its lightness, gently near white and black. Use it to warm or cool a whole passage.
+  - `highlight`: adds coloured light that rolls off towards white instead of clipping. Use it for glints and glow; black does nothing.
+  - `shadow`: shades as if light were blocked, coloured by the layer (paint shadows in a cool blue-violet), never crushing to black. White does nothing.
+
+  PSD has none of them: `export_psd` writes the nearest standard mode (watercolor and shadow as Multiply, tint as Color, highlight as Screen) and warns; the merged image stays exact.
+- **Grow the canvas instead of starting big** with `extend_canvas` (pixels per side; nothing painted moves relative to anything else). Adding `left` or `top` shifts every coordinate you hold by (+left, +top): re-read `list_layers` or use the returned `rect`. Dry wet paint first.
   `set_canvas` only crops or grows at the bottom-right.
-- **Save brushes you build** in the brush library: `create_brush` with `basedOn` and the facets
-  you changed (or `get_brush` then `create_brush` with its `brush`), and share them with
-  `export_brushes` / `import_brushes`. A saved brush shows in every editor that shares the
-  library; `set_brush` its id to paint with it.
+- **Save brushes you build** in the brush library: `create_brush` with `basedOn` and the facets you changed (or `get_brush` then `create_brush` with its `brush`), and share them with
+  `export_brushes` / `import_brushes`. A saved brush shows in every editor that shares the library; `set_brush` its id to paint with it.
 
 Which facet sets which engine setting: [references/brush-facets.md](references/brush-facets.md).
 
@@ -272,6 +246,17 @@ is a canvas coordinate: read [references/canvas-hosted.md](references/canvas-hos
 | `get_paper` | Read every setting of the current paper (pattern, seed, scale, tiling, depth, shading, dry and wet tuning, and `metallic`, `backlight`, `backlightColor` when set). |
 | `set_paper` | Change the paper: `preset`, then any of `color`, `depth` (0..1), `scale` (0.25..8), `seed` (another sheet), `pattern`, `tiling`, `shading`, `dry` / `wet` tuning (`contrast` 0..3, `invert`), `metallic`, `backlight` (0..1, light from behind: glazes glow, opaque paint blocks; preset `stained-glass`) and `backlightColor`. Affects new strokes' grain and how the paper shows; strokes already painted keep their pixels. Returns the paper. |
 
+### Suggesting paint
+
+Contributing while the user paints: suggest, don't paint. Read [references/painting-alongside.md](references/painting-alongside.md).
+
+| Tool | Use |
+| --- | --- |
+| `propose_paint` | Suggest paint as a ghost the user accepts or dismisses: `title`, `rationale`, `ops` (`stroke` with points and a dry brush, `wash` over its layer, `echo` of stroke ids moved / turned / scaled / repeated) and where its new layer goes (`place` top, bottom or above `layerId`). Returns the proposal id, the ghost's `bounds` and the strokes it echoes. Use it for contributions the user didn't ask for. |
+| `list_paint_proposals` | Read the pending paint proposals: id, title, rationale, who proposed it, op kinds, placement, bounds, the strokes it echoes and any since removed (`missing`), and whether accepting is allowed. Call before accepting or rejecting. |
+| `accept_paint_proposal` | Paint a pending proposal on a new layer as one undo step recorded as the proposer's (`proposalId`). Only when the user said yes. Returns the layer id, stroke ids and undo step name. Refuses when a stroke it echoes is gone. |
+| `reject_paint_proposal` | Dismiss a pending proposal (`proposalId`); nothing changes. Use it to withdraw a suggestion that no longer fits. Returns the id and title. |
+
 ### Layers
 
 | Tool | Use |

package/skills/pixerate-paint-editor/references/painting-alongside.md

@@ -0,0 +1,19 @@
+# Painting alongside the user
+
+When the user is painting and you contribute on your own initiative, **suggest, don't paint**:
+`propose_paint` shows your idea as a ghost over the canvas, and the user accepts or dismisses it.
+Accepted, it lands on a new layer of its own as one undo step recorded as yours, and the user's
+active layer stays theirs. Paint directly only when asked to.
+
+- **Play to what agents do well**: a `wash` (a warm ground with `place: "bottom"`, a glaze over a
+  passage), an `echo` of the user's own strokes (grass along the horizon, rain, hatching, a
+  repeated motif: `list_strokes` for the ids, then `dx` / `dy` / `rotate` / `scale` / `repeat`),
+  or a few deliberate `stroke`s. Not a stroke-by-stroke rendering of a subject.
+- **Small and complementary.** One idea per proposal, with a `title` that says what it adds and a
+  `rationale` that says why it fits what the user just painted.
+- **Dry brushes only** (dab, particle, bristle or mixer without pickup). Suggestions are previewed
+  and painted on their own layer, which wet paint, thick paint and pickup can't do.
+- **Withdraw what no longer fits** with `reject_paint_proposal`; an echo whose strokes the user
+  removed can't be accepted (`missing` in `list_paint_proposals`).
+
+The tools are `propose_paint`, `list_paint_proposals`, `accept_paint_proposal` and `reject_paint_proposal` (see SKILL.md, Suggesting paint).

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`. |