@pixerate/editor 0.240.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.240.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

@@ -235,21 +235,19 @@ 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: 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 its centre. Wet and
-   impasto brushes take it per pixel too, shifted by any paint they pick up: in watercolour and
-   gouache the pattern then flows, blooms and granulates with the water; impasto keeps its relief.
+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` 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.
+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:
 
@@ -259,6 +257,7 @@ When to use which:
 | 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
 
@@ -402,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
 
@@ -495,13 +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 in wet paint moves with the water**: the pattern bleeds and blooms like any
-  pigment, so fine detail softens. For a crisp pattern in an exact shape, paint the shape, dry it,
-  and `fill_layer_with_effect` with `lockTransparency: true`. Erasers, blenders and smudges ignore
-  effect paint; 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.