@pixerate/editor 0.240.0 → 0.242.0

package/dist/video-editor/index.d.cts

@@ -18,6 +18,7 @@ export * from './evaluate.cjs';
 export * from './audio.cjs';
 export * from './mix.cjs';
 export * from './mask.cjs';
+export * from './effect-path.cjs';
 export * from './plan.cjs';
 export * from './grade.cjs';
 export * from './lut.cjs';

package/dist/video-editor/index.d.ts

@@ -18,6 +18,7 @@ export * from './evaluate.js';
 export * from './audio.js';
 export * from './mix.js';
 export * from './mask.js';
+export * from './effect-path.js';
 export * from './plan.js';
 export * from './grade.js';
 export * from './lut.js';

package/dist/video-editor/index.js

@@ -1,6 +1,6 @@
 import {
   createEffectAuthoringSession
-} from "../chunk-TEFQISBY.js";
+} from "../chunk-X3ZINLIP.js";
 import {
   VIDEO_ADJUSTMENT_SCOPES,
   VIDEO_BLEND_MODES,
@@ -149,7 +149,7 @@ import {
   videoTransitionEase,
   videoValueAt,
   videoWipeRect
-} from "../chunk-WDDUPWVG.js";
+} from "../chunk-L3JFOTBQ.js";
 import {
   namedWithSuggestion
 } from "../chunk-EUKY4KFX.js";
@@ -159,7 +159,7 @@ import {
   effectSequenceTiming,
   effectTemplateTools,
   fillEffectTemplate
-} from "../chunk-G3RUKJ5C.js";
+} from "../chunk-RXZL4NG5.js";
 import "../chunk-EHLOCVWB.js";
 import {
   CAMERA_MOVE_MAX_MS,
@@ -168,9 +168,10 @@ import {
   cameraMoveParts,
   createEffectToolProvider,
   isEffectError,
+  pathControlsOf,
   resolveCameraMoveSpec,
   sampleEffectCameraMove
-} from "../chunk-SIK3LT6M.js";
+} from "../chunk-OFH6Q67U.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   defineEditorDocument
@@ -2205,6 +2206,73 @@ var VideoAudioPeaksCache = class {
   }
 };
 
+// src/video-editor/effect-path.ts
+function videoClipPicture(project, clip) {
+  const asset = clip.type === "media" ? project.assets.find((a) => a.id === clip.asset) : void 0;
+  const size = asset ? { width: asset.width ?? project.width, height: asset.height ?? project.height } : { width: project.width, height: project.height };
+  const fit = clip.fit ?? (clip.type === "media" || clip.type === "sequence" ? "contain" : "fill");
+  const rect = placeVideoRect(project, size, clip.type === "text" ? "fill" : fit, clip.transform, 0);
+  return { size, rect, rotation: videoTransformAt(clip.transform, 0).rotation };
+}
+function turn(x, y, cx, cy, deg) {
+  if (!deg) return [x, y];
+  const a = deg * Math.PI / 180;
+  const dx = x - cx;
+  const dy = y - cy;
+  return [cx + dx * Math.cos(a) - dy * Math.sin(a), cy + dx * Math.sin(a) + dy * Math.cos(a)];
+}
+function framePointsToPicture(points, picture) {
+  const { rect, size, rotation } = picture;
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  const out = [];
+  for (let i = 0; i + 1 < points.length; i += 2) {
+    const [x, y] = turn(points[i], points[i + 1], cx, cy, -rotation);
+    out.push(Math.round((x - rect.x) / rect.width * size.width * 100) / 100, Math.round((y - rect.y) / rect.height * size.height * 100) / 100);
+  }
+  return out;
+}
+function videoClipMaskOutline(project, clip) {
+  if (!clip.mask) return null;
+  const picture = videoClipPicture(project, clip);
+  const { rect, rotation } = picture;
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  const polygon = videoMaskPolygon(clip.mask, rect).map(([x, y]) => turn(x, y, cx, cy, rotation));
+  if (polygon.length < 2) return null;
+  return [...polygon, polygon[0]].flatMap(([x, y]) => [Math.round(x * 100) / 100, Math.round(y * 100) / 100]);
+}
+var VideoPathGesture = class {
+  constructor(frame, spacing = 3) {
+    this.frame = frame;
+    this.spacing = spacing;
+  }
+  frame;
+  spacing;
+  points = [];
+  drawing = false;
+  at(e, box) {
+    return [Math.round((e.clientX - box.left) / box.width * this.frame.width * 100) / 100, Math.round((e.clientY - box.top) / box.height * this.frame.height * 100) / 100];
+  }
+  down(e, box) {
+    this.drawing = true;
+    this.points = this.at(e, box);
+  }
+  move(e, box) {
+    if (!this.drawing) return false;
+    const [x, y] = this.at(e, box);
+    const n = this.points.length;
+    if (Math.hypot(x - this.points[n - 2], y - this.points[n - 1]) < this.spacing) return false;
+    this.points.push(x, y);
+    return true;
+  }
+  /** Ends the stroke; returns its points, or `null` for a tap (fewer than two points). */
+  up() {
+    this.drawing = false;
+    return this.points.length >= 4 ? [...this.points] : null;
+  }
+};
+
 // src/video-editor/plan.ts
 function clipIndex(project) {
   const out = /* @__PURE__ */ new Map();
@@ -3660,6 +3728,7 @@ var VideoEditorController = class _VideoEditorController {
       previewScale: this.previewScale,
       effectsProvider: this.effects.provider,
       plans: this.plans,
+      pathDrawing: this.pathDrawing,
       revision: this.revision
     };
   }
@@ -4176,6 +4245,81 @@ var VideoEditorController = class _VideoEditorController {
       return { edit: { op: "set_transition", clip, transition: { ...t, effect: { ...t.effect, values: merged } } }, label: `Change transition ${d.name}`, clip };
     }, options.merge);
   }
+  /**
+   * Gives an effect that draws along a path (see `pathControlsOf`) its path: on an effect clip
+   * (`instance` "generator") or a clip effect (its id). The path is frame points (`points`
+   * `[x0, y0, …]`, mapped into the pixels of the picture the effect renders: the project frame for
+   * an effect clip, the clip's own picture for a clip effect), SVG path data (`d`, which the effect
+   * fits as its control says; `""` clears it), the outline of a clip's mask (`mask`), or words the
+   * provider writes as a single-stroke path (`text`). `control` picks the path control when there
+   * are several. Checked before anything changes; one undo step. Returns the edit, the control and
+   * the value it took.
+   */
+  async setEffectPath(clip, instance, path, options = {}) {
+    const fail2 = (error) => ({ ok: false, error });
+    try {
+      const current = this.clipOrThrow(clip);
+      const effect = instance === "generator" ? current.type === "effect" ? current.effect : null : current.effects?.find((e) => e.id === instance)?.effect;
+      if (!effect) {
+        const ids = ["generator"].filter(() => current.type === "effect").concat((current.effects ?? []).map((e) => e.id));
+        return fail2(`Clip "${clip}" has no effect "${instance}"; its effects are ${ids.map((i) => `"${i}"`).join(", ") || "none"} ("generator" is an effect clip's own picture).`);
+      }
+      const d = await this.describeEffect(effect);
+      const controls = pathControlsOf(d);
+      if (!controls.length) return fail2(`"${d.id}" does not draw along a path. Find one that does with search_effects accepts ["path"].`);
+      const control = options.control ?? (controls.length === 1 ? controls[0] : void 0);
+      if (!control) return fail2(`"${d.id}" has several path controls (${controls.join(", ")}); pass control.`);
+      if (!controls.includes(control)) return fail2(`"${control}" is not a path control of "${d.id}"; its path controls are ${controls.join(", ")}.`);
+      const picture = videoClipPicture(this.project, current);
+      let value;
+      if ("points" in path) {
+        const pts = path.points;
+        if (!Array.isArray(pts) || pts.length < 4 || pts.length % 2 || !pts.every(Number.isFinite)) return fail2("points must be at least two points as [x0, y0, x1, y1, \u2026] in frame pixels.");
+        value = framePointsToPicture(pts, picture);
+      } else if ("d" in path) {
+        if (typeof path.d !== "string") return fail2('d must be SVG path data (a string), or "" to clear the path.');
+        value = path.d;
+      } else if ("mask" in path) {
+        const from = findVideoClip(this.project, path.mask.clip)?.clip;
+        if (!from) return fail2(`There is no clip "${path.mask.clip}" to take a mask from.`);
+        const outline = videoClipMaskOutline(this.project, from);
+        if (!outline) return fail2(`Clip "${path.mask.clip}" has no mask; add one with set_video_clip_mask, or pass points or d.`);
+        value = framePointsToPicture(outline, picture);
+      } else if ("text" in path) {
+        const provider = this.effects.require();
+        if (!provider.pathFromText) return fail2(`The effects provider "${provider.id}" cannot write words as a path; pass points or d.`);
+        if (typeof path.text !== "string" || !path.text.trim()) return fail2("text is empty; pass the words to write.");
+        value = await provider.pathFromText(path.text, { ...path.font ? { font: path.font } : {}, ...path.align ? { align: path.align } : {} });
+      } else return fail2("Pass the path as one of points, d, mask or text.");
+      const r = instance === "generator" ? await this.updateEffectValues(clip, "generator", { [control]: value }) : await this.updateClipEffect(clip, instance, { values: { [control]: value } });
+      return r.ok ? { ...r, control, value } : r;
+    } catch (e) {
+      return fail2(e instanceof Error ? e.message : String(e));
+    }
+  }
+  pathDrawing = null;
+  /**
+   * Starts drawing a path on the preview for an effect that draws along one (the preview then
+   * takes the pointer; `finishPathDrawing` with the frame points applies it). Editor state.
+   */
+  startPathDrawing(target) {
+    this.pathDrawing = { ...target };
+    this.notify();
+  }
+  /** Stops drawing a path without changing anything. */
+  cancelPathDrawing() {
+    if (!this.pathDrawing) return;
+    this.pathDrawing = null;
+    this.notify();
+  }
+  /** Applies the drawn path (frame points) to the effect being drawn for, and stops drawing. One undo step. */
+  async finishPathDrawing(points) {
+    const target = this.pathDrawing;
+    this.pathDrawing = null;
+    this.notify();
+    if (!target) return { ok: false, error: "No path is being drawn; start one from the effect's Draw path button." };
+    return this.setEffectPath(target.clip, target.instance, { points }, { control: target.control });
+  }
   /** Keys for one numeric control of a clip effect (clip-relative ms), or `null` to stop animating it (keeping its value at the clip's start). */
   setClipEffectKeyframes(clip, instance, control, keys) {
     const current = findVideoClip(this.project, clip)?.clip;
@@ -6117,6 +6261,47 @@ function createVideoEffectsToolProvider(controller, options = {}) {
           return { clip: args.clip, transition: clipOf(args.clip).transition, effects: videoClipAppliedEffects(clipOf(args.clip)) };
         }
       },
+      {
+        name: "set_video_effect_path",
+        title: "Run an effect along a path",
+        description: `Gives an effect that draws along a path (search_effects with accepts ["path"]; describe_effect lists its pathControls) the path to draw along: on an effect clip (instance "generator", added with add_video_effect_clip) or a clip effect (its id, from apply_effect). Pass exactly one of: points (frame pixels from the top left, as on the preview; mapped into the pixels of the picture the effect renders, so a clip effect lines up with its moved or scaled clip), d (SVG path data the effect fits into its picture; "" clears the path), mask (use the outline of a clip's mask, in frame pixels), or text (words the provider writes as a single-stroke path, when it can). Refuses an effect without a path control, naming how to find one. One undo step. Returns the clip, instance, the control set and the value it took (points in picture pixels, or path data).`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            clip: { type: "string", minLength: 1, description: "The clip id from get_video_project." },
+            instance: { type: "string", minLength: 1, description: `"generator" for an effect clip's own picture, or a clip effect id from list_applied_effects.` },
+            control: { type: "string", minLength: 1, description: "Which path control (default: the effect's only one; describe_effect pathControls lists them)." },
+            points: { type: "array", minItems: 4, maxItems: 4096, items: { type: "number", description: "x or y, frame pixels." }, description: "The path as frame points [x0, y0, x1, y1, \u2026] in pixels from the frame's top left." },
+            d: { type: "string", description: `SVG path data, fitted into the effect's picture as its control says; "" clears the path.` },
+            mask: { type: "object", properties: { clip: { type: "string", minLength: 1, description: "The clip whose mask outline to use." } }, required: ["clip"], additionalProperties: false, description: "Use the outline of this clip's mask (set_video_clip_mask), in frame pixels." },
+            text: {
+              type: "object",
+              properties: {
+                text: { type: "string", minLength: 1, description: "The words to write." },
+                font: { type: "string", minLength: 1, description: "A single-stroke font the provider offers (default its first)." },
+                align: { type: "string", enum: ["start", "middle", "end"], description: "Where the line sits (default start)." }
+              },
+              required: ["text"],
+              additionalProperties: false,
+              description: "Words the provider writes as a single-stroke path (a signature, handwriting)."
+            }
+          },
+          required: ["clip", "instance"],
+          oneOf: [{ required: ["points"] }, { required: ["d"] }, { required: ["mask"] }, { required: ["text"] }],
+          additionalProperties: false
+        },
+        annotations: { title: "Run an effect along a path", ...ctx.annotations.write },
+        handler: async (args) => {
+          ctx.requireProvider();
+          const given = ["points", "d", "mask", "text"].filter((k2) => args[k2] !== void 0);
+          if (given.length !== 1) throw new Error(`Pass exactly one of points, d, mask or text${given.length ? ` (got ${given.join(", ")})` : ""}.`);
+          const k = given[0];
+          const path = k === "text" ? { ...args.text } : { [k]: args[k] };
+          const r = await controller.setEffectPath(args.clip, args.instance, path, { control: args.control });
+          if (!r.ok) throw new Error(r.error);
+          return { clip: args.clip, instance: args.instance, control: r.control, value: r.value };
+        }
+      },
       {
         name: "set_video_effect_keyframes",
         title: "Keyframe an effect control",
@@ -6675,6 +6860,7 @@ export {
   VideoEffectsEngine,
   VideoFrameCache,
   VideoLutCache,
+  VideoPathGesture,
   VideoPreviewEngine,
   VideoPreviewPixels,
   allVideoClipIds,
@@ -6718,6 +6904,7 @@ export {
   formatVideoSeconds,
   formatVideoTimecode,
   formatVideoTimecodeFrames,
+  framePointsToPicture,
   isVideoDropFrameRate,
   isVideoKeyframes,
   measureVideoLoudness,
@@ -6809,7 +6996,9 @@ export {
   videoClipHeading,
   videoClipKeyframes,
   videoClipLabel,
+  videoClipMaskOutline,
   videoClipOverhang,
+  videoClipPicture,
   videoClipShowsWaveform,
   videoClipSoundGain,
   videoClipSourceRange,

package/package.json

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

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

@@ -161,7 +161,7 @@ refuse.
 | `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. |
+| `add_vector_effect` | Add a vector effect's own picture as an artwork group (fitted into `box`) with its motion as new shots. For an effect that draws along a path (`search_effects` `accepts: ["path"]`: a signature, a route), `path: { node }` runs it along a path node and lands it on the node, `path: { text }` writes words. Use it when the effect should trace the path itself; use `follow` or a draw-on to move or reveal your own art. Returns the instance and group ids. |
 | `list_camera_moves` | List the provider's camera moves for a `role` (`transition`: how the camera gets into a shot; `hold`: how it moves while the shot holds), with `durationMs` and `cut`. Returns `available: false` without camera moves. Call before `set_shot_camera_move`; `describe_effect` gives a move's controls and presets. |
 | `set_shot_camera_move` | Give a shot a camera move (`shot`, `role`, `move`, optional `ms` for a transition, `preset`, `values`): it is saved on the shot's camera as `in` or `during`. Returns the shot's camera and the `window` (ms) the move plays in. A wrong-role id is refused naming the moves that fit. |
 | `clear_shot_camera_move` | Remove a shot's move for a `role`, keeping its framing. Returns the shot's camera (null when nothing is left). |

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.

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

@@ -82,7 +82,9 @@ the pitfalls, and uses the tools below.
     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`.
+    `list_applied_effects`. **An effect along a path** (a beam along a border, a trail, words
+    written on): `search_effects` with `accepts: ["path"]`, add it as a clip or clip effect, then
+    `set_video_effect_path` with frame `points`, path data `d`, a clip's `mask` outline or `text`.
 12. **Camera moves** (a provider with camera moves, such as Flair): a clip is the shot.
     `list_video_camera_moves` with a `role`, then `set_clip_camera_move`: `transition` moves
     from `from` to `framing` from the clip's start (a glide, whip pan, punch zoom); `hold`
@@ -298,7 +300,7 @@ 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. Camera moves (`kind` camera) are listed but go on clips with `set_clip_camera_move`, not `apply_effect`. Call `describe_effect` next. |
+| `search_effects` | Find effects: words in `query`, filtered by `kind`, `category`, `use` (filter, overlay for clips; transition; generator, title) or `accepts: ["path"]` (effects that draw along a path you give). Returns ids, names, uses, whether they are transparent or loop, and their length. Camera moves (`kind` camera) are listed but go on clips with `set_clip_camera_move`, not `apply_effect`. 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. |
@@ -306,6 +308,7 @@ and every write tool is refused with the reason.
 | `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 transition effect from the effects provider into a `clip` from the one ending where it starts (`duration` centred on the cut, `values`). Needs handles like a crossfade. For a cross dissolve, dip, wipe, push, slide or iris use the built-in `set_video_transition` instead. |
+| `set_video_effect_path` | Give an effect that draws along a path (`describe_effect` `pathControls`) its path, on an effect clip (`instance` "generator") or a clip effect: frame `points` `[x0, y0, …]` (mapped into the picture the effect renders, so a clip effect follows its moved or scaled clip), path data `d` (`""` clears), a clip's `mask` outline, or `text` the provider writes. One undo step. Returns the control and the value it took. |
 | `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. |
 | `list_video_camera_moves` | List the provider's camera moves for a `role` (`transition` into a clip, `hold` across it) with `durationMs` and `cut`. Returns `available: false` without camera moves. Call before `set_clip_camera_move`. |
 | `set_clip_camera_move` | Play a camera move on a clip's picture (`clip`, `role`, `move`, `ms` for a transition, `preset`, `values`, `from` and `framing` as `{ zoom, x, y }`): baked into its transform keys, one per frame, two at a cut. Returns the camera, key counts, `cuts`, `windows` and `notes` (tilt, turn and blur cannot be baked). Refuses a clip keyed by hand. |
@@ -328,6 +331,10 @@ The host may add the shared document tools (see `pixerate-agent-tools`). A video
 
 ## Pitfalls
 
+- **Path points are frame pixels**, as on the preview: `set_video_effect_path` maps them into the
+  picture the effect renders. Do not pass a clip effect points in its source's pixels yourself, and
+  give it the path again after moving or scaling the clip a lot (it maps the clip's first frame).
+
 - **Camera moves are baked keys.** After trimming or splitting a clip, `check_video_project`
   reports `camera-stale`: set the move again to re-bake it. Editing the clip's x, y, scale or
   rotation keys by hand leaves the moves no longer describing them; clear the moves first.