@pixerate/editor 0.124.1 → 0.126.0

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: pixerate-animation-editor
-description: How to author and edit vector animations (motion graphics, logo reveals, animated icons, explainer scenes, UI micro-interactions) in the Pixerate animation editor through its agent tools - artwork SVG with ids, shots of commands (enter, exit, draw, move, rotate, scale, fade, morph, Smart Animate match, follow a path, pulse, shake, wiggle), easing and springs, stagger, camera, beat and voiceover cues, drivers, reusable clips, checking, rendering frames and contact sheets, and exporting to Flair or Lottie. Use when animation tools such as get_animation, insert_shots or edit_animation are available, or when asked to animate, time, ease, stagger or export vector motion.
+description: How to author and edit vector animations (motion graphics, logo reveals, animated icons, explainer scenes, UI micro-interactions) in the Pixerate animation editor through its agent tools - artwork SVG with ids, shots of commands (enter, exit, draw, move, rotate, scale, fade, morph, Smart Animate match, follow a path, pulse, shake, wiggle), easing and springs, stagger, camera, beat and voiceover cues, drivers, reusable clips, checking, rendering frames and contact sheets, and exporting to Flair or Lottie. Use when animation tools such as get_animation, insert_shots or edit_animation are available, or when asked to animate, time, ease, stagger or export vector motion, and provider motion and vector effects (for example Flair) applied to nodes.
 ---
 
 # Pixerate animation editor
@@ -125,8 +125,31 @@ The full command vocabulary (every type, option and default) is in
 | `undo_animation` | Undo your last edit (one tool call or one `edit_animation` batch). |
 | `redo_animation` | Redo the edit you just undid. |
 
+### Effects
+
+These tools come from `createAnimationEffectsToolProvider` and work when the host has registered an
+effects provider (for example Flair). Without one, `search_effects` and `describe_effect` return
+`available: false`, `list_applied_effects` still lists what the scene holds, and the write tools
+refuse.
+
+| Tool | Use it to |
+| --- | --- |
+| `search_effects` | Find effects: `kind` motion (primitives to apply to nodes) or vector (effects with their own picture), `query`, `category`. |
+| `describe_effect` | Read an effect's `controls` (names, ranges, units), `defaults` and `presets`, and whether it `appliesHere` (a motion effect). |
+| `list_applied_effects` | See the provider effects in the scene: their `instance` ids, the nodes they animate, their shots and values. |
+| `apply_effect` | Animate a node (`target`, a group animates as one) with a motion effect: the changes become ordinary commands, tagged with the effect, in a new shot after the last. Returns the instance id. |
+| `update_effect` | Make an applied effect again with new `values`, in the same place (`effect` is its instance id). |
+| `remove_effect` | Remove an applied effect: its commands, shots it alone filled and a vector effect's group. |
+| `add_vector_effect` | Add a vector effect's own picture as an artwork group (fitted into `box`) with its motion as new shots. Returns the instance and group ids. |
+
 ## Pitfalls
 
+- **Effect commands are ordinary commands.** You can retime or edit them with `edit_animation` like
+  any command, but `update_effect` replaces all of an effect's commands. Change values through the
+  effect, and timing through the commands.
+- **Some provider motion cannot be carried over.** Counting, writing text and similar changes are
+  skipped. The result's `notes` say what was left out.
+
 - **Unknown ids are refused** with a "did you mean" suggestion. Take ids from `get_animation` or
   the elements `set_animation_artwork_svg` returns; never guess them.
 - **`enter-visible`**: an element that enters while already showing blinks out first. Give an

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

@@ -1,6 +1,6 @@
 ---
 name: pixerate-paint-editor
-description: How to paint in the Pixerate paint editor (natural media) through its agent tools - canvas and paper (generated grain, depth, families from cold pressed watercolour to canvas), layers with painterly blend modes (watercolor, tint, highlight, shadow), dry media (pencil, pastel, charcoal, airbrush, marker, ink) with pen dynamics, wet media (watercolour, gouache and oil that flow, bloom, granulate and dry), thick impasto paint lit by a movable light, blending tools (blender, smudge, Mixer Brush), brush behaviours (pick-up and mix ratios, dirty and multi-coloured brushes), the brush library, replayable strokes, symmetry and perspective guides, tracing and reference images, harmonies, swatches, a mixing pad and pigment mixing, and PNG, JPEG, WebP, PSD and JSON output. Use when asked to paint, sketch, paint in watercolour, shade, blend, smudge, glaze, mix colours, paint symmetric or in perspective, trace an image, or when paint_stroke, set_paper, replay_strokes or mix_colors are available.
+description: How to paint in the Pixerate paint editor (natural media) through its agent tools - canvas and paper (generated grain, depth, families from cold pressed watercolour to canvas), layers with painterly blend modes (watercolor, tint, highlight, shadow), dry media (pencil, pastel, charcoal, ink) with pen dynamics, wet media (watercolour, gouache and oil that flow, bloom, granulate and dry), thick impasto paint lit by a movable light, blending tools (blender, smudge, Mixer Brush), brush behaviours (pick-up, dirty and multi-coloured brushes), the brush library, replayable strokes, symmetry and perspective guides, tracing and reference images, harmonies, swatches, a mixing pad, and PNG, JPEG, WebP, PSD and JSON output. Use when asked to paint, sketch, paint in watercolour, shade, blend, smudge, glaze, mix colours, paint symmetric or in perspective, trace an image, or when paint_stroke, set_paper, replay_strokes or mix_colors are available. Also effect paper, effect layers and light on paint from an effects provider.
 ---
 
 # Paint editor
@@ -236,6 +236,28 @@ Paint that changes colour as the stroke goes: give a gradient where a colour wou
   one side or inside a rect, ellipse or polygon; `invert` for outside). Stencils stay until
   removed (`remove_stencils`); masks are recorded with each stroke so replays keep them.
 
+## Provider effects
+
+When the host registers an effects provider (`setEffectsProvider`), shaders and generators from
+it work with the painting. Search first: `search_effects` with `use` `generator` (paper, layers,
+fills), `overlay` / `title` (layers, fills) or `filter` (light on paint), then `describe_effect`
+for the controls and presets.
+
+- **Effect paper**: `set_paper_effect` draws a generator over the sheet, under every layer.
+  `multiply` (the default) keeps the paper's colour and grain showing through, which is what
+  makes it look like printed or dyed paper; `normal` covers it. It saves and exports with the
+  painting, and brush grain still follows the real paper.
+- **Effect layers** (`add_effect_layer`): a pixel layer drawn by a generator, overlay or title
+  effect. Use them for backgrounds you want to change later, and for overlays (grain, light
+  leaks, captions) above the paint with a blend mode (`screen` / `linear-dodge` for light,
+  `multiply` for textures). `update_effect` draws the layer again and replaces its pixels, paint
+  on it included, so paint on a layer above it.
+- **Effect fills** (`fill_layer_with_effect`): the effect composited onto a layer's pixels with
+  no link kept; `lockTransparency` colours only what is painted (an effect inside a shape).
+- **Light on dried paint** (`apply_effect`): a filter (light, glow, grade) run on a layer's paint
+  and baked in, at `opacity` strength. Transparent areas stay transparent, and thick paint keeps
+  its relief and stays lit by the editor's light. Dry wet paint first (`dry_paint`).
+
 ## Tool reference
 
 ### Canvas and paper
@@ -346,6 +368,20 @@ Paint that changes colour as the stroke goes: give a gradient where a colour wou
 | `arrange_stickers` | Move stickers (`ids`) to the `front` or `back` of their layer. One undo step. |
 | `remove_stickers` | Delete stickers by `ids`, or all on the layer. One undo step. |
 
+### Provider effects
+
+| Tool | Use |
+| --- | --- |
+| `search_effects` | Find provider effects by `query`, `kind`, `category` and `use` (`generator` for paper and layers, `overlay` / `title` for layers and fills, `filter` for light on paint). `available: false` when no provider is registered. Call before the tools below. |
+| `describe_effect` | Read an effect's controls (types, ranges, defaults), presets and inputs. Call before passing `values`. |
+| `list_applied_effects` | Read the effect paper (target `paper`) and every effect layer with its effect and values; with `target`, one of them. Baked light and fills are pixels and are not listed. Works without a provider. |
+| `apply_effect` | Light on dried paint: run a `filter` effect on a layer's paint and bake it in (`values`, `opacity` = strength 0..1). Refused on empty, wet, locked or hidden layers, with the fix. One undo step; undo takes it back. Returns the effect used and `baked: true`. |
+| `update_effect` | Change the effect paper (`target` and `effect` "paper": `values`, `opacity`) or draw an effect layer again (`effect` "effect": `values`; `null` resets a control). Returns the effect. |
+| `remove_effect` | Remove the effect paper, or turn an effect layer into a plain layer keeping its pixels (`keptPixels`). |
+| `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. |
+
 ### Guides
 
 | Tool | Use |
@@ -418,5 +454,8 @@ Paint that changes colour as the stroke goes: give a gradient where a colour wou
 - **Replays repeat what was recorded**: strokes, fills, clears, flattened relief and wet events.
   Imported pixels, merges and layer moves are not data, so `export_time_lapse` and
   `export_high_res` start those layers empty; paint with strokes when the replay matters.
+- **Effects are pixels in replays.** Effect paper, effect layers, effect fills and baked light
+  need the provider when they are made; replays and time-lapses do not repeat them. Add them
+  after the painting, or keep the effect layer and redraw it.
 - **Recorded strokes are kept in saved documents**; `save_document` with `strokes: false` when
   only the pixels matter (smaller JSON).

package/skills/pixerate-vector/SKILL.md

@@ -383,6 +383,21 @@ contents whole while you work, without losing the mask.
 | `vector.setSnapOptions` | Set those options, e.g. `polarIncrement: 15` for 15° polar tracking, or a grid, before handing the canvas to the user. Moves nothing. Returns the options. |
 | `vector.setTool` | Switch the interactive tool (select, direct, pen, pencil, rect, ellipse, polygon, star, line, scissors, knife, eraser, width, shapeBuilder, paintBucket, blend, gradient, envelope, type, typePath, frame, connector). Only for handing the canvas to the user in a given mode; commands do not need a tool. |
 
+### Provider effects
+
+From `createVectorEffectsToolProvider`, when the host has registered an effects provider (for
+example Flair). Only vector effects apply here: they bring their own picture. Motion is applied in
+the animation editor.
+
+| Tool | Use it to |
+| --- | --- |
+| `search_effects` | Find effects with `kind` vector (lower thirds, stickers, loaders, badges). |
+| `describe_effect` | Read an effect's controls, defaults and presets before adding it. |
+| `list_applied_effects` | List the groups that show provider effects, with their values. |
+| `apply_effect` | Add an effect's picture at rest as a selected group of editable shapes (`target` "document" or a parent group id), fitted into the middle of the document. Returns the group id. |
+| `update_effect` | Draw an effect group again with new `values` (`effect` "picture"); its place and transform are kept, but edits to its shapes are replaced. |
+| `remove_effect` | Keep the group's shapes as a plain group, detached from the effect. |
+
 ## Pitfalls
 
 - Mesh and freeform fills draw as fine tiles, not SVG gradients: they cannot be edited with