@pixerate/editor 0.123.0 → 0.124.1

package/dist/{warp-BjmAgQwq.d.cts → warp-CH9MM435.d.cts}

@@ -1,4 +1,4 @@
-import { B as BezierPath } from './bezier-C-W9LFyD.cjs';
+import { B as BezierPath } from './bezier-CBzKKDjl.cjs';
 import { W as WarpStyle, a as WarpMesh, V as Vec2, B as Box } from './types-CwMPoRMU.cjs';
 
 /**

package/dist/{warp-Ca5fedzS.d.ts → warp-k_PdtXOG.d.ts}

@@ -1,4 +1,4 @@
-import { B as BezierPath } from './bezier-DQZE5dxA.js';
+import { B as BezierPath } from './bezier-CWv6LQal.js';
 import { W as WarpStyle, a as WarpMesh, V as Vec2, B as Box } from './types-CwMPoRMU.js';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.123.0",
+  "version": "0.124.1",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -144,6 +144,11 @@
       "import": "./dist/chart/index.js",
       "require": "./dist/chart/index.cjs"
     },
+    "./effects": {
+      "types": "./dist/effects/index.d.ts",
+      "import": "./dist/effects/index.js",
+      "require": "./dist/effects/index.cjs"
+    },
     "./diagram": {
       "types": "./dist/diagram/index.d.ts",
       "import": "./dist/diagram/index.js",

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

@@ -295,6 +295,9 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `get_text_layer` | Read a type layer: `text`, character `runs` and `paragraphs` as `start` / `end` ranges (UTF-16 code units, end exclusive) with their styles, the `frame` (point, or box with its size), the text-to-document `transform`, laid-out `lines` (range, baseline, width), `bounds`, `missingFonts`, and `rendering` (`live`, or `stored` pixels from a file until the next edit). Call before editing text you did not write. |
 | `get_shape_layer` | Read a shape layer: `components` bottom to top (`index`, `op`, `live` shape parameters or null, `subpaths` with absolute anchors and handles, `bounds`), `fillRule`, `fill` and `stroke` (paint and settings), `geometryBounds` (the paths) and `bounds` (rendered pixels, stroke included), and `annotationId` while it is still a migrated annotation. Call before editing a shape you did not draw. |
 | `export_smart_object_contents` | Export Contents: the contents as a file (`name`, `mimeType`, `byteLength`, `base64`): the file they came from while unedited, else a PNG (raster) or PSD / PSB (nested document). Changes nothing. |
+| `search_effects` | Find provider effects (when the host registered an effects provider; else `available: false`): `query`, `kind`, `category`, `use` (filter for smart filters; generator, overlay, title for effect layers). See `references/provider-effects.md`. |
+| `describe_effect` | Read an effect's `controls` (strict JSON Schema with ranges and units), `defaults`, `presets` and `inputs` before applying it. |
+| `list_applied_effects` | Read the provider effects per layer: effect smart filters (`role: smart filter`, with blend and opacity) and an effect layer's own effect (`generator`), with `available` false when the provider lacks one. Works without a provider. |
 | `capture_view` | Inspect detail in natural image pixels (the space of `get_selection` and `select_region`, before crop and rotation): `region` `content` (whole image, default), `selection` or `rect`; small regions are enlarged up to 8× with hard pixel edges, so a 64 px rect shows real pixels. `includeOverlays: true` shades unselected pixels and outlines the crop: use it to check a mask's edge before `apply_selection_as_mask`. Returns the `rect` and `scale`. Use `render_preview` for the final framed result. |
 
 ### Write
@@ -400,6 +403,10 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `mix_colors` | Read-only. Mix 1 to 16 `colors` (`{color: #rrggbb, weight, strength?}`) like paint (Kubelka-Munk over reflectance spectra). Returns `mixed` (#rrggbb), `rgbLerp` (the plain RGB average, for comparison) and the normalised `weights`. Call it before `paint_stroke` / `fill_pixels` to pick a paint colour. |
 | `clear_pixels` | Remove the selected pixels (alpha to 0; a transparency-locked layer or a mask gets the background colour). Returns the changed bounds. |
 | `import_psd` | Open a PSD / PSB (`data` base64, a `data:` URL is fine) as the document, replacing the layers, crop and rotation (one undo step). Returns the new `layers` tree with ids, `layerIds`, size and `warnings` naming the affected layers. Call `inspect_psd` first when losses matter. |
+| `apply_effect` | Run a provider filter effect on a layer as a smart filter (`target`, `effect`, `values`, `index`, `enabled`, `opacity`); a pixel, shape or type layer becomes a smart object in the same undo step (`converted`). Returns the filter id. |
+| `update_effect` | Change an effect smart filter (`values` merged, `null` resets; `enabled`, `opacity`, `index`) or redraw an effect layer (`effect: "generator"`, values only). |
+| `remove_effect` | Remove an effect smart filter, or (`generator`) keep an effect layer's pixels as a plain layer. |
+| `add_effect_layer` | Add a layer drawn by a generator, overlay or title effect at the document's size and bit depth (`values`, `time`, `name`, `aboveId` / `belowId`, `opacity`, `blend`). Returns the layer id. |
 | `apply_selection_as_mask` | Mask a layer with the current selection: pass `layerId` to mask an existing layer, or `kind` (plus optional `params`) to create a new masked layer in one step. `density` 0..1 and `feather` px soften the mask non-destructively. Returns `layerId`, kind, mask info and the selection summary. |
 
 ## Pitfalls

package/skills/pixerate-image-editor/references/provider-effects.md

@@ -0,0 +1,35 @@
+# Provider effects in the image editor
+
+The host may register an effects provider (for example Flair). The tools then reach its catalog:
+filter effects become **smart filters**, and generator, overlay and title effects become
+**effect layers**. These are not the layer styles of `set_layer_effect` (drop shadow, stroke, glow).
+
+## Working method
+
+1. `search_effects` with a `use`: `filter` for a look on existing pixels; `generator`, `overlay` or
+   `title` for new content.
+2. `describe_effect` for its controls, ranges and presets.
+3. `apply_effect` on the layer (a smart filter), or `add_effect_layer` (a new layer at the
+   document's size and bit depth).
+4. Tune with `update_effect`. Use a smart filter's `opacity` and the stack's filter mask
+   (`set_smart_filter_mask`, `paint_stroke` channel `filter-mask`) to limit where it shows. Use a
+   layer mask, opacity and blend mode for an effect layer.
+5. `render_preview` once the effect has rendered.
+
+## Best practices
+
+- Prefer smart filters to baking: they stay editable, reorderable and maskable.
+- For light leaks and glows, add an overlay effect layer with blend `screen` or `add`. For
+  textures, use `multiply`.
+- Several effect filters render in order: each waits for the one below it.
+
+## Pitfalls
+
+- **Effects render in the background.** Right after `apply_effect` or `update_effect`, the smart
+  object shows the pixels without the new effect until the provider's result lands. This is a
+  redraw, not an undo step. Render a preview after the effect has rendered.
+- **Smart filters run on 8-bit pixels.** Effect layers render at the document's bit depth.
+- **Without a provider,** effect filters pass pixels through and effect layers keep their last
+  pixels. Both keep their effect ids and values and save unchanged. The write tools refuse.
+- **An effect layer's pixels are redrawn** by `update_effect` (`generator`), which replaces any
+  painting on it. Paint on a layer above, or `remove_effect` `generator` first to keep the pixels.

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

@@ -1,6 +1,6 @@
 ---
 name: pixerate-video-editor
-description: How to edit video projects in the Pixerate non-linear video editor through its agent tools - adding video, audio and image assets, building a rough cut on video and audio tracks, inserting, overwriting, moving, trimming, splitting and ripple-deleting clips, slip, slide and roll edits, lift and extract of a time range, razor cuts across tracks, sync-locked tracks, keyframed opacity, volume and transform, closing gaps, titles and colour clips, fades, volume and speed, crossfade, dip and wipe transitions with handles, J and L cuts, markers, checking the project, rendering frames and contact sheets, and exporting an ffmpeg command or a CMX 3600 EDL. Use when video tools such as get_video_project, add_video_clip or edit_video are available, or when asked to cut, trim, assemble, sequence or export footage on a timeline.
+description: How to edit video projects in the Pixerate non-linear video editor through its agent tools - adding video, audio and image assets, building a rough cut on video and audio tracks, inserting, overwriting, moving, trimming, splitting and ripple-deleting clips, slip, slide and roll edits, lift and extract of a time range, razor cuts across tracks, sync-locked tracks, keyframed opacity, volume and transform, closing gaps, titles and colour clips, fades, volume and speed, crossfade, dip and wipe transitions with handles, J and L cuts, markers, checking the project, provider effects (clip effects, effect clips, effect transitions), rendering frames and contact sheets, and exporting an ffmpeg command or a CMX 3600 EDL. Use when video tools such as get_video_project, add_video_clip or edit_video are available, or when asked to cut, trim, assemble, sequence or export footage on a timeline.
 ---
 
 # Pixerate video editor
@@ -60,6 +60,12 @@ For errors, namespaced tool names and undo conventions, see `pixerate-agent-tool
    `export_video_edl` (one track) for finishing elsewhere. Read the returned notes. For a
    delivery loudness, have the host run `export_video_loudness_measure` first and pass what it
    prints as `loudness.measured`; one pass (`loudness` without `measured`) is fine for a draft.
+10. **Effects** (only when the host registered an effects provider; `search_effects` says
+    `available: false` otherwise): `search_effects` with a `use`, then `describe_effect` for its
+    controls, then `apply_effect` (filters and overlays on a clip), `set_video_effect_transition`
+    or `add_video_effect_clip` (generators and titles). Tune with `update_effect` and
+    `set_video_effect_keyframes`; check with `get_video_frame` (layers list `effects`) and
+    `list_applied_effects`.
 
 ## Best practices
 
@@ -229,8 +235,40 @@ For errors, namespaced tool names and undo conventions, see `pixerate-agent-tool
 | `undo_video` | Undo your last edit (one tool call or one `edit_video` batch). |
 | `redo_video` | Redo the edit you just undid. |
 
+### Effects
+
+These tools come from `createVideoEffectsToolProvider` and work when the host registered an
+effects provider (for example Flair). Without one, `search_effects` and `describe_effect` return
+`available: false` with the reason, `list_applied_effects` still lists what the project holds,
+and every write tool is refused with the reason.
+
+| Tool | Use it to |
+| --- | --- |
+| `search_effects` | Find effects: words in `query`, filtered by `kind`, `category` or `use` (filter, overlay for clips; transition; generator, title). Returns ids, names, uses, whether they are transparent or loop, and their length. Call `describe_effect` next. |
+| `describe_effect` | Read one effect's `controls` (a strict JSON Schema: names, types, ranges, units), `defaults`, `presets` and `inputs`, and whether it `appliesHere` (as a clip effect). Use the names and ranges for values. |
+| `list_applied_effects` | See the effects in the project per clip, in order: clip effects (`fx1`...), an effect clip's own effect (`generator`) and an effect transition (`transition`), with their saved values and `available` (false when the provider lacks it: drawn as a placeholder). |
+| `apply_effect` | Add a filter or overlay effect to a clip's stack (`target` clip id, `effect`, `values`, `index`, `enabled`, `opacity`). Effects run in order on the clip's picture before its grade and placement. Returns the effect's new id and the clip's effects. |
+| `update_effect` | Change an applied effect: `values` merged over its own (null resets a control), `enabled`, `opacity`, `index` (reorder). For `generator` and `transition` only `values`. Returns the effect now. |
+| `remove_effect` | Take an effect off a clip (`transition` removes an effect transition; an effect clip is deleted with `delete_video_clips`). Returns what was removed and what is left. |
+| `add_video_effect_clip` | Put a generator, title or overlay effect on a video `track` as a clip filling the frame (`start`, `duration` default the effect's own length, `values`, `mode`). Transparent effects show the tracks beneath. Returns the clip id. |
+| `set_video_effect_transition` | Use a provider transition effect into a `clip` from the one ending where it starts (`duration` centred on the cut, `values`). Needs handles like a crossfade. |
+| `set_video_effect_keyframes` | Animate one number `control` of a clip effect (or an effect clip's `generator`) with `keys` in clip ms, or `null` to stop animating it. |
+
 ## Pitfalls
 
+- **Effects need rendered frames to export.** ffmpeg cannot draw provider effects, so
+  `export_video_ffmpeg` refuses a project with enabled effects unless the host renders the
+  picture frame by frame (`renderVideoFrameExact`) and passes `frames`. Tell the user, or turn
+  the effects off (`update_effect` with `enabled: false`) for a quick draft export.
+- **Effects render a frame later.** The preview draws a clip without its effect until the
+  provider's picture for that frame arrives; `get_video_frame` and the project are always
+  exact. Effects are cached per frame of the project's frame grid.
+- **Values are checked, keys too.** Out-of-range or unknown controls are refused with the
+  control's description; only number controls can be keyframed, and transition values cannot.
+- **Effects survive without a provider.** A project opened where no provider (or a different
+  one) is registered keeps every effect id and value, shows effect clips as labelled boxes and
+  effect transitions as crossfades, and saves them back unchanged.
+
 - **Edits never add errors.** Any edit that would create an overlap, a source overrun or an
   impossible transition is refused whole (unless you asked for `mode: "overwrite"` or
   `"insert"`); read the message (it names the next free place or the longest trim /