@pixerate/editor 0.239.0 → 0.241.0

package/dist/vector/index.js

@@ -26,7 +26,7 @@ import {
   traceField,
   traceVectorImage,
   vectorTraceContours
-} from "../chunk-UUBO6RB5.js";
+} from "../chunk-UDBDYZET.js";
 import {
   applyHomography,
   homographyFromPoints,
@@ -53,7 +53,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-XK4SST43.js";
+} from "../chunk-ZDPLZDTT.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -526,8 +526,8 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-7YGBSFC6.js";
-import "../chunk-PJYG6FCF.js";
+} from "../chunk-ILM6GYAX.js";
+import "../chunk-XBZK47LV.js";
 import {
   createProvenance
 } from "../chunk-M6DNZNVY.js";

package/package.json

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

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

@@ -40,6 +40,8 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
 - **Strokes are data.** Every stroke is recorded (brush, colour, raw points, seed, symmetry
   copies) and gets a `strokeId`. `replay_strokes` paints recorded strokes again, exactly or
   varied. That is the main way an agent should make many similar marks.
+- **Stroke layers keep strokes editable** (`add_layer {type: "strokes"}`): tune a stroke's brush,
+  colour, seed or points after painting it instead of repainting. See "Stroke layers" below.
 - **Guides** are editor state saved with the document: a symmetry guide makes every stroke paint
   its mirror or kaleidoscope copies (one stroke), a perspective guide snaps strokes to lines
   towards one to three vanishing points, a tracing image sits under the paint (never exported)
@@ -196,11 +198,13 @@ Paint that changes colour as the stroke goes: give a gradient where a colour wou
   bristle draws its own line: press harder to splay the tuft, tilt to flatten it; soft bristles
   bend into curves at turns; a low `bristle.load` runs dry into broken streaks.
 - **Sticker spray** (category `sticker`): stamps (`star`, `leaf`, `confetti`, `flower`, `heart`,
-  `splat`, `sparkle`, `ring`, `dot`) sprayed along the stroke onto an **empty layer**, where each
-  stays an object: `add_stickers` (place them exactly), `sticker_at` (pick one by point), `list_stickers`, `update_sticker` (move, turn, resize, recolour, restamp),
-  `arrange_stickers`, `remove_stickers`. A sticker layer takes no other paint. Stickers are drawn
-  whole, so a spray is refused while a mask stencil is on: hide it (`update_stencil` `enabled`
-  false) first, then remove the stickers you don't want.
+  `splat`, `sparkle`, `ring`, `dot`) sprayed onto an **empty layer**, each staying an object:
+  `add_stickers` (exact places), `sticker_at`, `list_stickers`, `update_sticker`, `arrange_stickers`,
+  `remove_stickers`. A sticker layer takes no other paint; sprays are refused under an enabled
+  mask stencil (hide it with `update_stencil` `enabled` false, then remove unwanted stickers).
+- **Stroke layers**: pixels drawn from the layer's strokes; they take `dab`, `particle`, `bristle`
+  and Mixer Brush strokes that pick up no paint. `list_strokes {live: true}` → `update_stroke` /
+  `edit_stroke_points` / `reorder_stroke` / `remove_strokes`; `rasterize_stroke_layer` once settled.
 - **Stencils**: `add_stencil` lays a `ruler` or `arc` (strokes that start within `snap` px follow
   it exactly: straight lines, circles, rainbows) or a `line` / `shape` mask (paint lands only on
   one side or inside a rect, ellipse or polygon; `invert` for outside). Stencils stay until
@@ -231,27 +235,29 @@ for the controls and presets.
 
 ## Effect paint
 
-`set_effect_paint` makes a generator, overlay or title effect the paint. It is rendered once at
-the canvas size, and every stroke then takes each pixel's colour from that picture, fixed to the
-canvas: painting reveals a hidden image where the brush goes. Its transparency paints nothing, so
-an overlay paints only where it has pixels.
+`set_effect_paint` makes a generator, overlay or title effect the paint: rendered once, every
+stroke takes each pixel's colour from it, fixed to the canvas (painting reveals a hidden image).
+Its transparency paints nothing.
 
 1. `search_effects` (`use` generator, overlay or title) and `describe_effect` for the controls.
-2. `set_effect_paint` with `effect`, `values` and `time` (ms, default 0). Wait for it: strokes that
-   would use it are refused while it renders.
-3. Paint with a dry brush: dab, particle and bristle brushes take the colour per pixel (the most
-   faithful), the Mixer Brush and dab brushes with `behavior.pickup` take it per dab at the dab's
-   centre and mix it with what they pick up. Brush opacity, flow, grain and pressure still apply.
-4. `set_color` or `set_paint` goes back to colour; `remove_effect` (target and effect `paint`)
-   does too, and `update_effect` (target and effect `paint`, `values`) renders new values.
+2. `set_effect_paint` with `effect`, `values`, `time` (ms, default 0). Wait for it to return.
+3. Paint: dab, particle and bristle brushes take the colour per pixel; the Mixer Brush and pick-up
+   dab brushes take it per dab at its centre. Wet and impasto brushes take it per pixel, shifted by
+   paint they pick up (in watercolour and gouache it flows with the water; impasto keeps its relief).
+   Sprayed stickers each take the colour at their centre (they stay recolourable).
+4. `set_color`, `set_paint` or `remove_effect` (target and effect `paint`) go back to colour;
+   `update_effect` (target and effect `paint`, `values`) renders new values.
+5. Along each stroke (`map`) or playing on stroke layers (`live`): [references/effect-paint.md](references/effect-paint.md).
 
 When to use which:
 
 | Want | Use |
 | --- | --- |
 | The effect inside brushed marks, hand-painted edges | `set_effect_paint` and a dry brush |
-| The effect inside an exact shape, or in wet / thick paint | Paint the shape, dry it, then `fill_layer_with_effect` with `lockTransparency: true` |
+| The effect in a wash that flows, or in thick paint | `set_effect_paint` and a watercolour, gouache, oil or impasto brush |
+| The effect inside an exact shape, unchanged by water | Paint the shape, dry it, then `fill_layer_with_effect` with `lockTransparency: true` |
 | The effect over the whole sheet | `set_paper_effect` or `add_effect_layer` |
+| A pattern that follows the stroke, or paint that moves | `map: { by: "stroke" }`, `live: true` on a stroke layer |
 
 ## Canvas-hosted layer
 
@@ -281,7 +287,7 @@ view), so work with the tools you are given.
 | Tool | Use |
 | --- | --- |
 | `list_layers` | Read the layers top first: id, name, type (`pixel` / `group`), visible, opacity, blend, clipped, locks, `active`, painted `bounds` (null when empty), parent and depth. |
-| `add_layer` | Add an empty pixel layer (or `type: "group"`) above the active layer, above `aboveId`, or at the top of group `parentId`; it becomes active. Returns the layer. Put each pass of a painting on its own layer. |
+| `add_layer` | Add an empty pixel layer (or `type: "group"`, or `type: "strokes"` for a stroke layer whose strokes stay editable) above the active layer, above `aboveId`, or at the top of group `parentId`; it becomes active. Returns the layer. Put each pass of a painting on its own layer. |
 | `update_layer` | Change `name`, `visible`, `opacity` (0..1), `blend`, `clipped` (clip to the layer below) or `locks` (`pixels`, `transparency`: paint only where there is paint, `position`, `all`). Returns the layer. |
 | `list_blend_modes` | Read every blend mode: id, label, group (`standard`, `pigment`, `painterly`), what the pigment and painterly modes do, and the `psd` mode export writes instead. Read before choosing a painterly mode. Changes nothing. |
 | `set_active_layer` | Make a layer the default target of strokes, fills and clears. Editor state. |
@@ -335,7 +341,14 @@ view), so work with the tools you are given.
 | Tool | Use |
 | --- | --- |
 | `paint_stroke` | Paint one stroke through `points` (document px; `pressure` 0..1, `t` ms, `tiltX` / `tiltY` or `altitude` / `azimuth`, `twist`) with `brushId` (default the active brush), optional per-stroke `brush` changes, `color` or `paint` (a gradient for this stroke), `layerId`, `seed`, `snapToPerspective`. The symmetry guide adds its copies; a sampling tracing image supplies the colour when `color` is missing. Returns `layerId`, `bounds`, `dabs`, `strokeId` and, for brushes that pick up paint, `mixerLoad` (what the brush carries now). Refused on locked, hidden or group layers, with the fix in the message. |
-| `list_strokes` | Read the recorded strokes, oldest first (default the last 100): id, layer, brush, colour, point count, seed, bounds. With `ids`, their points too. |
+| `list_strokes` | Read the recorded strokes, oldest first (default the last 100): id, layer, brush, colour, point count, seed, bounds, `live`. With `ids`, their points too; with `layerId`, one layer's. With `live: true`, the editable strokes of stroke layers as they are now, bottom first: the ids for the stroke layer tools. |
+| `stroke_at` | Read the top-most stroke of a stroke layer that painted the pixel at `x`, `y`, or null. Use it to pick one stroke among overlapping ones. |
+| `update_stroke` | Change a stroke on a stroke layer: `brushId` (keeps its size), `brush` settings, `color`, `paint` (null drops a gradient), `seed`. Redraws exactly. One undo step. Returns the stroke and the changed `bounds`. |
+| `edit_stroke_points` | Replace a stroke's `points`, or `transform` it (`dx`, `dy`, `scale`, `rotate`, `flipX`, about its centre or `origin`). One undo step. Returns the stroke with its points and the changed `bounds`. |
+| `reorder_stroke` | Move a stroke to `index` in its stroke layer (0 = bottom). One undo step. Returns the order. |
+| `remove_strokes` | Delete strokes from stroke layers (their eraser). One undo step. Returns the ids and `bounds`. |
+| `convert_to_stroke_layer` | Make an empty pixel layer a stroke layer. Returns the layer. |
+| `rasterize_stroke_layer` | Turn a stroke layer into a plain pixel layer with the same pixels (strokes no longer editable). Do it before erasing, smudging or filling on it. |
 | `replay_strokes` | Paint recorded `strokeIds` again: exactly, or varied by `dx` / `dy` (px), `rotate` (degrees clockwise), `scale` (brush size follows), `flipX`, `origin`, `pressureScale`, `color`, `brushId`, `layerId`, `repeat` (each copy applies the variation again). One undo step. Returns the new stroke ids, bounds and layers. |
 | `undo_paint` | Undo the last step (a wet stroke's undo puts the wet paint back as it was before it). Returns what was undone and what is next. |
 | `redo_paint` | Redo the step just undone. |
@@ -388,7 +401,8 @@ view), so work with the tools you are given.
 | `set_paper_effect` | Draw a generator over the paper (`values`, `opacity`, `blend` default `multiply`, `time`); `effect: null` removes it. One undo step. Returns the effect paper. |
 | `add_effect_layer` | Add a layer drawn by a generator, overlay or title effect (`values`, `name`, `aboveId`, `opacity`, `blend`, `time`); it becomes active. Returns the layer and its effect. |
 | `fill_layer_with_effect` | Composite a generator, overlay or title effect onto a layer (`layerId`, `values`, `opacity`, `lockTransparency`, `time`). One undo step. Returns the layer id and the effect. |
-| `set_effect_paint` | Paint with a generator, overlay or title effect (`effect`, `values`, `time` ms default 0): rendered once at the canvas size, strokes take each pixel's colour from it. Call after `describe_effect`, then `paint_stroke` with a dry brush. Editor state, not an undo step. Returns `effectPaint` (`effect`, `provider`, `values`, `time`). |
+| `set_effect_paint` | Paint with a generator, overlay or title effect (`effect`, `values`, `time` ms default 0): rendered once at the canvas size, strokes take each pixel's colour from it; `map` `{ by: "stroke", length, repeat }` lays it along each stroke; `live` keeps it playing on stroke layers. Call after `describe_effect`, then `paint_stroke`. Editor state, not an undo step. Returns `effectPaint`. |
+| `set_effect_playback` | Play or pause live effect paint in the view (`playing`) and cap its frame rate (`fps` 1..60). Editor state. Returns `playing`, `fps`, `time` and `animation` (what plays, or null). Export a moment with `export_image` / `export_psd` `time`. |
 
 ### Guides
 
@@ -481,12 +495,9 @@ The host may add the shared document tools (see `pixerate-agent-tools`). A paint
   strokes record it, and replays render it again first, so they need the same provider (an
   error names the effect and provider when it is missing; `color` on `replay_strokes` repaints
   in one colour instead).
-- **Effect paint refuses wet, impasto and sticker brushes** (they carry one colour as pigment,
-  thick paint or stamps). Paint the shape, dry it, and `fill_layer_with_effect` with
-  `lockTransparency: true`. Erasers, blenders and smudges ignore it, and a brush with its own
-  gradient, a stroke `color` or `paint`, or `set_color` / `set_paint` paints colour instead.
-- **Effect paint is fixed to the canvas, not the stroke**: a replayed or moved stroke shows the
-  part of the effect under its new place. Wait for `set_effect_paint` to return before painting;
-  strokes are refused while it renders.
+- **Effect paint is fixed to the canvas by default** (`map: { by: "stroke" }` follows the stroke),
+  and in wet paint it flows with the water; for a crisp pattern in an exact shape, paint and dry
+  the shape, then `fill_layer_with_effect` (`lockTransparency: true`). Erasers, blenders and
+  smudges ignore it. Wait for `set_effect_paint` to return; strokes are refused while it renders.
 - **Recorded strokes are kept in saved documents** (`save_paint_document`, `get_paint_document`),
   so a painting can be replayed and repainted at a higher resolution.

package/skills/pixerate-paint-editor/references/effect-paint.md

@@ -0,0 +1,25 @@
+# Effect paint along the stroke, and live effect paint
+
+- **Along the stroke** (`set_effect_paint` `map: { by: "stroke", length, repeat }`): the effect is
+  rendered as a strip `length` px long (16..4096, default 300) and 256 px across. Each pixel takes
+  the colour at its distance along the stroke and its place across the tip, so the pattern follows
+  the stroke's turns instead of staying fixed to the canvas. `repeat` starts the strip again
+  (default), `mirror` runs it back, `clamp` holds the last colour. Use it for ribbons, ropes,
+  flames and textures that should flow with the mark; use the default canvas mapping to reveal one
+  hidden picture across many strokes. Every colour-laying brush takes it (watercolour, gouache, oil
+  and impasto too; sprayed stickers at their centre); particle and bristle marks take the place of
+  their pen dab.
+  Scaled replays (`export_high_res`) scale `length` with the canvas.
+- **Live** (`live: true`): on a stroke layer (`add_layer {type: "strokes"}`) each stroke keeps
+  playing the effect, so the paint moves. Paint the strokes, then `set_effect_playback`
+  (`playing`, `fps` 1..60, default 30) plays or pauses them in the view. The document keeps the
+  frame at the effect's own `time`; `export_image` and `export_psd` take `time` (ms) to export
+  another moment. Live strokes stay editable like any stroke on a stroke layer
+  (`update_stroke` with `paint` changes the effect).
+- **Where it applies**: live only plays on stroke layers; on a pixel layer the stroke bakes the
+  frame at `time`. A painting plays at most 8 distinct live effects (each needs a renderer per
+  frame); paint more strokes with one of them, or bake new ones (`live: false`).
+- **Cost**: each frame redraws the live strokes (and any stroke overlapping them), and renders
+  each live effect once. On a large canvas with many live strokes, lower `fps`.
+- **Without the provider** (a document opened elsewhere): the saved pixels show the frame as
+  painted, and nothing plays until the provider is registered.