@pixerate/editor 0.228.2 → 0.230.0

package/dist/video-editor/index.js

@@ -1,6 +1,6 @@
 import {
   createEffectAuthoringSession
-} from "../chunk-PB6JV62G.js";
+} from "../chunk-SBPGIZQN.js";
 import {
   VIDEO_ADJUSTMENT_SCOPES,
   VIDEO_BLEND_MODES,
@@ -148,16 +148,16 @@ import {
   videoTransitionEase,
   videoValueAt,
   videoWipeRect
-} from "../chunk-LPTFDCJO.js";
+} from "../chunk-ONNNNGNS.js";
 import "../chunk-EHLOCVWB.js";
 import {
   namedWithSuggestion
-} from "../chunk-W4KFNAWC.js";
+} from "../chunk-TYCJGFCF.js";
 import {
   EffectsSlot,
   createEffectToolProvider,
   isEffectError
-} from "../chunk-UGYUGZE2.js";
+} from "../chunk-TCZ2J7PR.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   defineEditorDocument

package/package.json

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

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

@@ -155,13 +155,16 @@ 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`. `kind` camera lists camera moves (with `camera`: role transition or hold, `durationMs`, `cut`); they move a scene's camera and cannot be applied with these tools. |
+| `search_effects` | Find effects: `kind` motion (primitives to apply to nodes) or vector (effects with their own picture), `query`, `category`. `kind` camera lists camera moves (with `camera`: role transition or hold, `durationMs`, `cut`); give them to a shot with `set_shot_camera_move`, not `apply_effect`. |
 | `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. |
+| `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). |
 
 ### Save and open
 
@@ -175,8 +178,32 @@ The host may add the shared document tools (see `pixerate-agent-tools`). An anim
 | `list_saved_animation_documents` | List saved animations (`key`, `name`, `savedAt`), newest first. |
 | `open_saved_animation_document` | Replace the animation with a saved one by `key`. One undo step. Ask before opening over changes the user has not saved. |
 
+### Camera moves
+
+With a provider that has camera moves (Flair: `camera-glide`, `camera-whip-pan`,
+`camera-punch-zoom`, `camera-cut` to get in; `camera-ken-burns`, `camera-crash-zoom` while
+holding), a shot's camera can play one as it arrives and one while it holds:
+
+1. Frame the shot as usual (`update_shot` with `camera: { frame: "<id>" }` or a rectangle). A
+   move without a framing keeps the one the camera has.
+2. `list_camera_moves` with the `role`, pick by `description`, then `set_shot_camera_move`. Use
+   a preset (`describe_effect` lists them) before hand-tuning `values`.
+3. A transition's `ms` sets how long it takes (default the move's own, written out on the
+   shot); a hold move plays across the shot's `hold`, so lengthen the hold for a slower drift.
+   The next shot's move starts from where a hold move ends.
+4. `render_animation_frame` mid-move to look, and `check_animation`: `camera-move-first-shot`
+   (the first shot cuts, so its transition does not play), `camera-move-unknown`,
+   `camera-move-values`, `camera-move-not-played` (no provider with camera moves: the camera
+   eases between framings instead).
+
+Exports to Flair tag each camera change with `<move>@<shot>`; with the provider set the camera
+is sampled from the move, and a cut stays a jump.
+
 ## Pitfalls
 
+- **One move per role per shot.** Whip pans and cuts jump half way: put them between framings
+  that differ, and do not follow a cut with a long glide into the same framing.
+
 - With agent playback on, the cursor clicks the shot a call names in the timeline and visits the stage elements its commands target. Results are unchanged.
 - **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

package/skills/pixerate-animation-motion-graphics/SKILL.md

@@ -66,6 +66,8 @@ This skill is the method. `pixerate-animation-editor` has the full tool referenc
 | Draw a line or outline | `draw`, or `enter` `style: "draw"` |
 | Attention on one element | `pulse`, `shake`, `wiggle` (sparingly) |
 | A set length | `fit_animation` with `seconds`, `keep` for fixed shots |
+| The camera travels to the next part | `update_shot` camera `frame`, then `set_shot_camera_move` role `transition` (a glide; a whip pan for energy) |
+| A slow push while a shot holds | `set_shot_camera_move` role `hold` (a Ken Burns drift), with a longer `hold` |
 
 ## Recipes
 
@@ -95,6 +97,7 @@ This skill is the method. `pixerate-animation-editor` has the full tool referenc
 - `add_commands`, `update_command`, `delete_commands`, `move_command`: refine commands
 - `edit_animation`: several edits as one undo step
 - `fit_animation`, `set_animation_settings`, `get_timing_grid`: length, settings and cues
+- `list_camera_moves`, `set_shot_camera_move`: provider camera moves into and during a shot
 - `check_animation`, `get_motion_path`, `render_animation_frame`: check and look
 - `export_lottie`, `export_flair_motion`: deliver
 - `undo_animation`: take back a step

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

@@ -311,6 +311,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `set_global_light` | Set the document light (`angle`, `altitude` in degrees) that every shadow and bevel with `useGlobalLight` follows. Returns the light. |
 | `paint_stroke` | Paint (`tool` brush), blend with the Mixer Brush (`tool` mixer) or erase (`tool` eraser) along `points` in document px (optional `pressure` 0..1) on a pixel layer or its mask (`channel`; the mixer paints pixels only); `color` #rrggbb (on a mask: black hides, white reveals; for the mixer, the reservoir colour) or `paint` (brush only: a gradient for this stroke); `brush` `{size, hardness, spacing, angle, roundness, opacity, flow, smoothing, pressureSize, pressureOpacity, blend}`; `mixer` `{wet, load, mix, loadEachStroke, cleanEachStroke, mixing: rgb \| pigment}` (tool mixer only). The selection limits the paint. One undo step per call. Returns the layer, channel, changed `bounds`, dab count and, for the mixer, `mixerLoad` `{reservoir, amount, pickup}`. |
 | `set_paint` | Set what the brush paints: one colour (it becomes the foreground) or gradient paint (`stops` sorted by offset, `space` pigment / oklab / srgb, `map`, `softness`). Errors say what is wrong. Returns `paint`, `foreground`, `background`, `brush`. |
+| `sample_color` | The Eyedropper: read the composite colour at a document point (`size` averages a square; default 1 px) and, unless `setForeground` is false, make it the paint foreground. Use it to match a colour already in the image before painting or retouching. Fails outside the canvas or on transparent pixels. Returns `color` and `foreground`. |
 | `get_paint` | Read-only. What the brush paints (`paint`), the foreground and background colours and the brush settings. |
 | `get_mixer_brush` | Read-only. The Mixer Brush settings and what it carries (`reservoir` #rrggbb or null, `amount` left 0..1, `pickup` #rrggbb or null). Call it before a mixer stroke with `loadEachStroke: false`. |
 | `load_mixer_brush` | Fill the Mixer Brush reservoir with `color` (default the foreground), amount 1; keeps the pickup. View state, not an undo step. Use before strokes with `loadEachStroke: false`. Returns the load. |

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

@@ -83,6 +83,12 @@ the pitfalls, and uses the tools below.
     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`.
+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`
+    plays across the rest of the clip at `framing` (a Ken Burns drift on a still). The moves are
+    baked into the clip's x, y, scale and rotation keys at the project's fps, two keys at a cut,
+    so the preview and exports play them without the provider. Check with `get_video_frame`.
 
 ## Best practices
 
@@ -284,7 +290,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 not applied to clips (`appliesHere` false). Call `describe_effect` next. |
+| `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. |
 | `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. |
@@ -293,6 +299,9 @@ and every write tool is refused with the reason.
 | `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_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. |
+| `clear_clip_camera_move` | Remove a clip's move for a `role` and re-bake the other; with none left the transform goes back to what it was. |
 
 ### Save and open
 
@@ -308,6 +317,12 @@ The host may add the shared document tools (see `pixerate-agent-tools`). A video
 
 ## Pitfalls
 
+- **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.
+- **A cut is two keys at one time** (the value just before, then the value after). Keys may
+  share a time only in pairs; a speed ramp never takes one.
+
 - **An adjustment clip changes only tracks below it** (scope `underneath`). Put it on a new top
   track (`add_video_track` with `at: 0`), or use scope `all`. Adjustment clips have no sound and
   are left out of EDLs; ffmpeg exports draw a plain grade or full-strength LUT at full opacity

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

@@ -65,7 +65,7 @@ music track and cutting to them, see `pixerate-bgm-alignment`.
 | Time passing | Crossfade or dip between shots |
 | A section change | Dip to black or a held shot, then a new rhythm |
 | Continuity of motion | Cut on action (`roll_video_edit` onto the movement) |
-| Photos in a slideshow | Image assets, a slow push-in (`set_video_keyframes` scale 1 to 1.08) |
+| Photos in a slideshow | Image assets, a slow push-in: with a provider that has camera moves, `set_clip_camera_move` role `hold` (a Ken Burns drift) on each photo; otherwise `set_video_keyframes` scale 1 to 1.08 |
 
 ## Recipes
 
@@ -96,4 +96,5 @@ start: 0, duration: <sequence>, fadeOut: 2000 }`; `update_video_clip` on the las
 - `roll_video_edit`, `slip_video_clip`, `trim_video_clip`, `close_video_gaps`: refine the rhythm
 - `set_video_transition`: crossfades and dips
 - `update_video_clip`, `set_video_keyframes`: fades, volume and push-ins
+- `list_video_camera_moves`, `set_clip_camera_move`: provider camera moves (a drift across a photo)
 - `undo_video`: take back a step