@pixerate/editor 0.241.0 → 0.243.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.241.0",
+  "version": "0.243.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

@@ -159,8 +159,9 @@ read [references/wet-media.md](references/wet-media.md) for the engine and the w
 
 ## Oils and thick paint
 
-Wet oil barely flows and blends where the brush meets it; impasto brushes add relief lit by
-`set_lighting`. Load `pixerate-paint-oil-impasto`, and read [references/oils.md](references/oils.md).
+Wet oil blends where the brush meets it; impasto adds relief lit by `set_lighting`: load
+`pixerate-paint-oil-impasto` and read [references/oils.md](references/oils.md). **Light paint**
+(neon, glowing glass: `light.amount`, the Light category): [references/light-paint.md](references/light-paint.md).
 
 ## Gradient paint
 
@@ -261,12 +262,8 @@ When to use which:
 
 ## Canvas-hosted layer
 
-A host can mount the painting as a layer of a larger canvas (`createPaintEditorToolProvider` with
-`origin`). Then every position you pass or read back is a canvas coordinate, not a document
-pixel: stroke points, picks, bounds, guides, stencils, stickers and wet areas alike.
-`get_canvas_info` `bounds` says where the painting lies on that canvas; paint inside it. The
-host may leave out tools it owns (`new_canvas`, `set_canvas`, `extend_canvas`, exports, the
-view), so work with the tools you are given.
+When `get_canvas_info` has `bounds`, the painting is a layer of a larger canvas and every position
+is a canvas coordinate: read [references/canvas-hosted.md](references/canvas-hosted.md).
 
 ## Tool reference
 
@@ -375,7 +372,10 @@ view), so work with the tools you are given.
 | --- | --- |
 | `set_lighting` | Move the light for thick paint and metallic paper: `azimuth` (degrees clockwise from the top), `elevation` (5..90), `relief` (0..1). Nothing is repainted; not an undo step. Returns the lighting. Use a low elevation to show brushwork. |
 | `get_relief` | Read a layer's relief (`bounds`, `maxHeight` 0..255, null when flat) and the lighting. Changes nothing. |
-| `flatten_relief` | Remove a layer's relief and material, keeping its colour. One undo step. Returns whether anything was flattened. |
+| `flatten_relief` | Remove a layer's relief and material (rim and clarity too), keeping its colour and light. One undo step. Returns whether anything was flattened. |
+| `get_light` | Read a layer's light paint: `hasLight`, `bounds`, `peak` 0..255 and its `spill`. Changes nothing. |
+| `set_light_spill` | How far a layer's light spills (`radius` px, 0 off) and how strongly (`strength` 0..2). Not an undo step; nothing is repainted. |
+| `clear_light` | Take a layer's light away, keeping its colour. One undo step. |
 
 ### Stickers
 

package/skills/pixerate-paint-editor/references/canvas-hosted.md

@@ -0,0 +1,8 @@
+# Canvas-hosted layer
+
+A host can mount the painting as a layer of a larger canvas (`createPaintEditorToolProvider` with
+`origin`). Then every position you pass or read back is a canvas coordinate, not a document
+pixel: stroke points, picks, bounds, guides, stencils, stickers and wet areas alike.
+`get_canvas_info` `bounds` says where the painting lies on that canvas; paint inside it. The
+host may leave out tools it owns (`new_canvas`, `set_canvas`, `extend_canvas`, exports, the
+view), so work with the tools you are given.

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

@@ -0,0 +1,31 @@
+# Light paint
+
+Light paint is paint that gives off light: neon, light painting, glow-in-the-dark, glowing glassy
+tubes. Any dab, particle, bristle, Mixer Brush or impasto brush lays it with `light.amount` above 0
+(`set_brush`); the Light category presets are ready-made (`glow-gel`, `neon-marker`,
+`light-airbrush`, `spark-trail`).
+
+- **What it does.** Each layer keeps a light channel next to its colour. The light's colour is the
+  paint's colour at that pixel, so recolouring paint recolours its light. It glows (the paint
+  itself is brighter, whatever `set_lighting` says) and spills onto everything around and below it
+  in each stroke's own colour.
+- **It behaves like paint.** Plain paint over glowing paint dims it; erasers remove it; smudges,
+  blenders, the knife, the Mixer Brush and pick-up brushes carry it with the colour they move. A
+  smeared neon line glows along the smear. `clear_light` takes it away and keeps the colour.
+- **Spill** (`set_light_spill`, per layer): `radius` px (default 24; 0 turns it off) and
+  `strength` 0..2 (default 1). It is not an undo step and repaints nothing; it shows the
+  painting as committed, so a stroke's spill appears when the stroke ends. It spills onto
+  everything below, paper included, so it reads best on dark paper (`set_paper` colour).
+- **Glassy beads** (impasto): `impasto.rim` makes a bead's light stronger at its edges, where its
+  surface turns away (backlit glass); `impasto.clarity` lets the middle of a bead show the layers
+  below while its edges stay solid. `glow-gel` uses both: paint loops with a distance-mapped
+  gradient (`set_paint`) for glowing glass tubes.
+- **Crossings.** Beads on one layer fuse where they cross (their heights combine by maximum), so
+  clarity only shows other layers: paint one loop per layer for glassy crossings.
+- **Spill vs a glow layer style.** Spill takes each stroke's colour and strength. For a one-colour
+  halo around everything on a layer, use a blend or an effect layer instead.
+- **Not yet:** wet brushes (glowing watercolour is planned, #494), sticker sprays and stroke layers
+  refuse light above 0, with the alternatives.
+- **PSD.** `export_psd` writes each layer's pixels with their glow, and its spill as a
+  "‹layer› light" Linear Dodge (Add) layer directly above it. Re-importing gives plain pixel
+  layers, not editable light.

package/skills/pixerate-paint-oil-impasto/SKILL.md

@@ -66,6 +66,7 @@ This skill is the method. `pixerate-paint-editor` has the full tool reference an
 | Scraped, smeared texture | `palette-knife` |
 | Blobs of paint straight from the tube | `paint-tube` |
 | A glossy bead or line | `gloop-pen` |
+| A glowing, glassy bead (a neon or glass tube) | `glow-gel` (light paint with rim and clarity, on dark paper; one loop per layer where they cross) |
 | Dry, broken strokes over texture | `dry-brush`, or a lower `impasto.load` |
 | A metallic highlight | `metallic-paint` |
 | Paint that stays exactly as laid | `set_instant_dry` on |

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.