@pixerate/editor 0.266.2 → 0.267.0

package/skills/pixerate-vector/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixerate-vector
-description: How to draw and edit vector artwork in the Pixerate vector editor through its vector.* commands - adding shapes and SVG paths, text (point, area, on a path, styles, Create Outlines), symbols and instances, CAD constraints, artboards and frames with resizing constraints, connectors, fills, strokes, stacked fills and strokes with blend modes, drop shadows, glows and blurs, clipping and opacity masks, gradients (linear, radial, conic, mesh, freeform), stroke alignment, arrowheads, variable-width and tapered strokes, live corner radii, boolean operations and Pathfinder (unite, subtract, divide, trim), Shape Builder, paint bucket, path effects (trim, repeater, zig zag, offset), envelope warps and free distort, blends and morphing, anchor editing (join, smooth, simplify, knife, eraser), align, distribute, group, and SVG import and export. Use when creating an icon, logo, illustration, glyph, badge or any Bezier path artwork, or editing an SVG in a Pixerate vector editor.
+description: How to draw and edit vector artwork in the Pixerate vector editor through its vector.* commands - adding shapes and SVG paths, text (point, area, on a path, styles, Create Outlines), symbols and instances, CAD constraints, artboards and frames with resizing constraints, connectors, stacked fills and strokes with blend modes, brushstrokes with brush character and paper grain, drop shadows, glows and blurs, clipping and opacity masks, gradients (linear, radial, conic, mesh, freeform), stroke alignment, arrowheads, variable-width and tapered strokes, live corner radii, boolean operations and Pathfinder (unite, subtract, divide, trim), Shape Builder, paint bucket, path effects (trim, repeater, zig zag, offset), envelope warps and free distort, blends and morphing, anchor editing (join, smooth, simplify, knife, eraser), align, distribute, group, and SVG import and export. Use when creating an icon, logo, illustration, glyph, badge or Bezier path artwork, or editing an SVG in a Pixerate vector editor.
 ---
 
 # Pixerate vector editor
@@ -20,7 +20,9 @@ carry a live effect stack. Every command is a `vector.*` command run with `run_c
   `{ type, stops: [{ offset, color, opacity?, midpoint? }], ... }`.
 - **Appearance**: a path can stack several fills and several strokes (bottom to top; all fills
   draw under all strokes), each with its own paint, `opacity`, `blendMode` and `visible`, and
-  each stroke with its own width, alignment, dashes, caps, joins, arrowheads and profile. Layers
+  each stroke with its own width, alignment, dashes, caps, joins, arrowheads and profile, or a
+  **brushstroke** (`vector.addBrushstroke`, `vector.setBrushstroke`, `vector.listBrushes`) painted
+  along the outline with a dry or wet brush, a Mixer Brush, smudge or blender, gradient paint, seeded jitter and paper grain. Layers
   are addressed by `index` in their stack, 0 at the bottom. `fill` / `stroke` and the stroke
   settings of `vector.setStyle` are shorthands for the **top** layer; `null` clears the stack.
   Any node can also have a `blendMode` and `filters` (drop / inner shadow, outer / inner glow,
@@ -101,7 +103,7 @@ the pitfalls, and uses the commands below.
   than splitting text into separate nodes, so it still edits as one paragraph. Create Outlines
   only for final artwork or logos that must not depend on fonts; keep a copy as text if it may
   change.
-- **Paths, strokes, booleans, gradients, stacks, masks, shadows, connectors, constraints and
+- **Paths, strokes, brushstrokes, booleans, gradients, stacks, masks, shadows, connectors, constraints and
   vertical text:** read [references/best-practices.md](references/best-practices.md) first.
 - **Non-destructive first.** Live booleans (`vector.boolean` with `live: true`), path effects
   and envelopes keep the operands editable. A destructive boolean or Pathfinder replaces its
@@ -373,12 +375,20 @@ contents whole while you work, without losing the mask.
 
 | Command | Use it to |
 | --- | --- |
-| `vector.listBrushes` | List the brushes a brushstroke can use: the dry presets (pencils, pastels, charcoal, crayon, chalk, markers, inks, ballpoint, gel pen, fineliner), 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`, default the brush's default colour (ballpoint blue, chalk), else the path's stroke; `keepColour` keeps the path's colour): 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 (another brush without `color` takes its default colour, unless `keepColour`; giving the same `brushId` again takes that saved brush as the library has it now), 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`. |
+| `vector.listBrushes` | List the brushes a brushstroke can use: the dry presets (pencils, pastels, charcoal, crayon, chalk, markers, inks, ballpoint, gel pen, fineliner, gradient and multi-colour brushes), wet paint (watercolour, gouache, wet oils), the Mixer Brush, smudge and blender, then saved brushes from the brush library the vector profile admits, with their sizes and `builtin`, plus the editor's `colorScheme` and `colorLocked`. Brushes it refuses (thick paint, particles, stickers, erasers, the wet 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`, default the brush's default colour (ballpoint blue, chalk), else the path's stroke; `keepColour`, or a lock from `vector.setColorLocked`, keeps the path's colour): 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. `paint` is gradient paint sampled dab by dab along the path (`{ type: 'gradient', stops, map: { by: 'distance', length, repeat } }`, lengths in document units; also pressure, direction, across-tip, random; not velocity or time). Returns the stroke stacks. |
+| `vector.setBrushstroke` | Change brushstroke layer `index` of path `id`: brush (another brush without `color` takes its default colour, unless `keepColour` or the colour is locked; giving the same `brushId` again takes that saved brush as the library has it now), size, pressure, colour, opacity, `seed` (a new seed is a new take on the same stroke; null: plain dabs), `paper` (replaced whole; null: no grain; {}: the default sanded paper) and `paint` (gradient paint, replaced whole; null: the colour again). Remove it with `vector.removeStroke`. |
+| `vector.setColorLocked` | Lock (`locked: true`) or unlock brushstroke colours ("Keep my colour"): while locked, `vector.addBrushstroke` and `vector.setBrushstroke` with another brush keep the path's or layer's colour instead of the brush's default; an explicit `color` still applies. Strokes already made are unchanged. Respect a lock the person set. Editor state, not an undo step. Returns `{ colorScheme, colorLocked }`. |
+| `vector.setColorScheme` | Set `scheme` `light` or `dark`: the side of light / dark default colours (chalk) that brushstrokes made from now on take. Existing strokes keep their colour. Usually the host's job. Returns `{ colorScheme, colorLocked }`. |
 
 Give brushstrokes a `seed` unless you want flat, even dabs: without one a charcoal or pastel line looks like a felt pen. Use different seeds on neighbouring strokes so they do not repeat each other, and `paper: null` for clean ink or marker lines that should not catch grain. The grain is laid in each path's own space, so it moves with the path.
 
+**Colour along the stroke.** For colour that changes along the path, give the brushstroke `paint` (`by: 'distance'` with `length` about the path's length and `repeat: 'clamp'` runs the gradient once from start to end; `across-tip` loads the brush with several colours side by side; `pressure` follows the pressure profile). A gradient as the layer colour also works: its `strokeMode` `along` runs it from each subpath's start to its end, `across` lays it across the tip, and `within` (the default) lays it over the path's box. Gradient and multi-colour presets (`gradient-round`, `rainbow-marker`) paint their own gradient; their `paint` stops take the layer colour.
+
+**Wet paint** (`watercolor-round`, `watercolor-wash`, `gouache`, `oil-round`) bleeds, blooms and granulates in its own small wet area, then dries. That takes a few seconds per stroke, so the canvas shows the paint as laid first and swaps in the settled stroke when it is ready; SVG and PDF exports always wait for it. Prefer a handful of wet strokes to dozens of short ones.
+
+**Mixer Brush, smudge and blender** act on what lies beneath the stroke: the shapes below it in the document and the path's own fills and lower strokes. Put the path above the art it should work on (`vector.arrange`), give it no visible stroke of its own if only the effect should show, and draw it after the shapes are final: the stroke re-renders whenever something beneath it changes. They pick up fills (solid and gradient), plain strokes and other brushstrokes; not text, placed images, filters or masks. The result is drawn over the art, so a smudge can drag colour out onto bare paper but can't wipe the art away. The Mixer Brush paints from its reservoir (the layer colour) even with nothing beneath it; a smudge or blender over nothing draws nothing.
+
 ### Editor settings
 
 | Command | Use it to |

package/skills/pixerate-vector/references/best-practices.md

@@ -19,6 +19,7 @@ Detail for `SKILL.md`'s best practices, by topic.
   `outside` for outlines around artwork; open paths always stroke centred. Use round caps and
   joins for friendly line icons, miter for geometric ones. Keep one stroke width across an icon
   set (for example 1.5 or 2 units on a 24-unit grid).
+- **Brushstrokes and brush character.** Use `vector.addBrushstroke` (after `vector.listBrushes`) when a path should look hand-drawn (pencil, charcoal, pastel, chalk, marker, ink) while staying an editable Bezier path. Pass a `seed` for pencil, pastel, charcoal and chalk (without one the brush paints plain, even dabs with no jitter or grain), and a different seed on neighbouring paths so their strokes do not repeat. Use a `pressure` taper such as `[0.2, 1, 0.2]` for strokes that start and end lightly. For clean ink or marker lines leave out the seed, or pass `paper: null` to keep the jitter without grain. Remove a brushstroke layer with `vector.removeStroke`.
 - **Icon grid.** Use a square artboard (24, 32 or 48 units), keep a padding margin, place
   coordinates on whole or half units so strokes render crisp, and align optical centres.
 - **Gradients.** Two to four stops are usually enough. Use `interpolation: "oklab"` for

package/skills/pixerate-vector/references/commands.md

@@ -180,3 +180,22 @@ inside the intended face.
 | transparency | 0–100 % see-through (50) | – | The lens's own fill, see-through. |
 
 The lens shows what is drawn before it (below it), follows edits there, and keeps its own bounds. Move it with `vector.transform` like any path. Remove it with `vector.removeLens`.
+
+## Brushstrokes (`vector.listBrushes`, `vector.addBrushstroke`, `vector.setBrushstroke`)
+
+A brushstroke is a stroke layer (kind brushstroke) in a path's appearance stack that paints a dry
+brush along the path's outline; the path stays editable and the stroke follows it.
+
+| Parameter | Meaning |
+| --- | --- |
+| `ids` / `id` | `vector.addBrushstroke`: paths or groups (`ids`, default the selection; a group paints every path inside). `vector.setBrushstroke`: one path `id` plus the stroke layer `index` (from `vector.getAppearance`, 0 the bottom). |
+| `brushId` | Required on add. A preset or saved brush id from `vector.listBrushes` (dry brushes only: pencils, pastels, charcoal, crayon, chalk, markers, inks, ballpoint, gel pen, fineliner). Wet, thick, particle, sticker and tool brushes are refused. |
+| `size` | Brush diameter in document units, up to 500 (default the brush's own; `null` on set restores it). |
+| `pressure` | Pressure profile 0–1 spread evenly from start to end (`[0.2, 1, 0.2]` tapers both ends; default full pressure; `null` on set). |
+| `color` | CSS colour. Default: the brush's own default colour (e.g. the ballpoint's blue) unless `keepColour`, else the path's stroke colour, else black. |
+| `keepColour` | Use the path's (or, on set with another `brushId`, the layer's) colour instead of the brush's default colour. |
+| `opacity` | Layer opacity 0–1 (default 1). `index` on add places the layer in the stroke stack (default on top). |
+| `seed` | Integer 0–2147483647 that turns on the brush's character: seeded size, angle, opacity and scatter jitter plus paper grain. The same seed renders the same stroke. Without a seed (or `null` on set) the brush paints plain, even dabs. |
+| `paper` | Applies with a `seed`: `{ pattern?, seed?, scale?, depth? }` for the grain (pattern `sanded` by default, `rough`, `cold-pressed`, `canvas`, `linen`; `scale` 0.25–8; `depth` 0–1, default 0.5). Omitted: the sanded paper; `null`: jitter without grain. On set it is replaced whole and `{}` is the default paper. |
+
+Remove a brushstroke with `vector.removeStroke`, like any stroke layer.