@nodetool-ai/agents 0.8.4-a24.3 → 0.8.4

package/dist/_skills/timeline-edit-ops/SKILL.md

@@ -0,0 +1,736 @@
+---
+name: timeline-edit-ops
+description: Reference for editing a NodeTool timeline that already exists with edit_timeline ops — animate_clip roles and presets, the easing grammar, per-word/character stagger, set_clip_params limits, document-only fields (styleTracks, textAnimator, animationLinks, layout, camera2d, motionBlur, repeater), groups, transitions, masks and mattes, clip effects, time remap, compositions, beat-cutting ops, and validate_timeline's/preview_timeline_frame's full mechanics. Use for a few changes to a cut that already exists — retiming a clip, swapping a preset, nudging a stagger. For a new cut, or a scene with many clips, build it with the @nodetool-ai/sandbox-timeline pack instead; see motion-graphics.
+---
+
+# Timeline edit ops → the `edit_timeline` reference
+
+This is the op-by-op contract for changing a timeline document that already
+exists. `motion-graphics` owns the build loop and picks the surface: a new
+cut goes through the `@nodetool-ai/sandbox-timeline` pack, which handles
+tracks, groups, layout and most of what follows here for you. Reach for this
+skill once that document exists and needs a few changes.
+
+Ops are the right tool when the timeline has no authoring code (`code.get`
+answers `code: null`), or for a deliberate hand tweak on one that does. On a
+code-backed timeline, an op inside a scene the code tracks marks that scene
+"edited": the next `code.set`/`code.edit`/`code.rebake` (`api-timelines`)
+keeps your edit and reports it in `conflicts` rather than overwriting it,
+unless `force` says otherwise.
+
+## Read before you edit
+
+Call `get_timeline` first. You need the sequence's `fps`, `width`, `height`,
+the track list with each track's `index` and `type`, and every clip's
+`startMs`, `durationMs`, `mediaType` and existing `animations`. Edit nothing
+until you have clip ids from the document — never a guessed one.
+
+Snapshot with `create_timeline_version` before your first edit. Motion work is
+iterative and a wrong `mode: "replace"` wipes animations somebody wrote.
+
+`edit_timeline` takes a timeline ID and an `ops` array, run in order, up to
+60 per call. Inspect each op's `ok` and the batch's `failed` result before a
+dependent edit. In an in-product agent, use the matching `ui_timeline_*` tool
+for an individual op:
+
+```json
+{"timeline_id":"<id>","ops":[{"op":"animate_clip","target":"Title","animations":[{"role":"in","preset":"fade","durationMs":400}]}]}
+```
+
+The `animate_clip` input accepts catalog presets or `custom` curves and code,
+plus `stagger` and a typewriter `caret`. It does **not** author `styleTracks`,
+`textAnimator`, or `beat`. `set_clip_params` does **not** author `layout`,
+`repeater`, `motionBlur`, `steppedTime`, `temporalEcho`, `animationLinks`, or
+`transform.depthPx`. `set_clip_params` refuses a call that names one of
+those keys, and `animate_clip` drops the fields it does not author. For those fields, read `get_timeline`'s `timeline` object, change
+the needed clip or sequence fields, and call `set_timeline_document` with a
+complete document assembled from it. Preserve tracks, clips, markers, tempo,
+setup, templateId, mediaTracks, transcript, scriptEnabled, and camera2d when
+present. Include `timeline.updatedAt` as `expected_updated_at` so a
+concurrent edit is refused. A whole-document write validates the result and
+snapshots the prior version. Omitted document fields are removed, so never
+send only the changed clip. The JSON objects in the document sections below
+are fields to merge into that complete document, not `edit_timeline` ops.
+The editor may lack controls for them even though they render and survive a
+save.
+
+## Track layering
+
+**Lowest `index` renders on top.** Track 0 covers track 1, which covers track 2
+— Premiere, Resolve and FCP order, and the opposite of a paint stack. The
+compositor turns the index into `z = 1000 - index`; `preview_timeline_frame`
+reports that `z_index` per layer and lists layers top of the stack first.
+
+Five track types, and the type is a role, not a restriction on what draws:
+
+| Type | Holds | Use for |
+|---|---|---|
+| `video` | picture clips, images | the cut itself |
+| `overlay` | text and shape clips | titles, lower-thirds, scrims, callouts |
+| `audio` | sound | music, voiceover, effects — never drawn |
+| `subtitle` | text | burned-in captions |
+| `midi` | played notes | a synthesized part — never drawn |
+
+Rules that follow from the ordering:
+
+- A scrim goes on a **higher** index than the text it sits behind, and a lower
+  index than the picture it darkens — so picture, then scrim, then text, in
+  descending index order.
+- Give each motion element its own overlay track when their timings overlap.
+  Two animated clips on one track that overlap in time trigger an automatic
+  crossfade you did not ask for (see Transitions).
+- Captions are the exception you do not control: word-level captions from a
+  voiceover clip composite above every real track regardless of which track
+  that clip sits on. Do not build a title that expects to cover them.
+- An audio clip never contributes a layer. A frame that looks empty because
+  everything is on audio tracks is a track-type mistake.
+- At most **8 video layers** composite at once, resolved top track first. Text,
+  shape and image clips are not counted, so a stack of titles is unaffected —
+  but nine overlapping video clips means the bottom one silently does not draw.
+  A preview frame is how you find that out.
+
+## Build the elements
+
+The clips you animate are made with the same `edit_timeline` op list.
+
+```json
+[
+  {"op":"add_text_clip","text":"Maya Chen","trackId":"<overlay>","startMs":4000,"durationMs":3000,"fontSizePx":64},
+  {"op":"add_shape_clip","shape":{"kind":"rect","x":0,"y":0.72,"width":1,"height":0.18,"fill":"#000000"},"startMs":4000,"durationMs":3000,"opacity":0.55}
+]
+```
+
+`add_text_clip` needs only `text`; the style fields (`fontSizePx`, `color`,
+`background`, `stroke`) are read from the op itself or from a `style` bag, and
+with no `trackId` it lands on an overlay track. `add_shape_clip` takes its
+geometry in `shape` (or `shapeStyle`, or the op's own keys) with `x`, `y`,
+`width` and `height` as 0..1 fractions of the frame — no geometry at all is a
+full-frame rect, which is the scrim you usually want.
+
+Tracks are the z-order, so how they are made matters:
+
+```json
+[
+  {"op":"add_track","type":"overlay","name":"Titles"},
+  {"op":"move_track","target":"Picture","toIndex":2}
+]
+```
+
+`add_track` takes `type` (`video`, `audio`, `overlay`, `subtitle`, `midi`) and an
+optional `name`, and **appends to the bottom** — the highest index, which draws
+last. A picture track added after the overlays therefore covers them. Add the
+overlays last, or move the picture down afterwards: `move_track` takes a
+`target` and one of `toIndex` (0 is the top), `before` or `after`.
+
+## Animating a clip
+
+`edit_timeline` with `{"op": "animate_clip", "target": <clip id or name>,
+"animations": [...]}`. Each animation is `{role, preset, durationMs?, delayMs?,
+easing?, params?}`. `mode` is `"replace"` (default) or `"add"`.
+
+Four roles. A clip may carry several, one of each kind or more:
+
+- **`in`** — entrance. `delayMs` offsets from the clip's start.
+- **`out`** — exit. `delayMs` offsets backwards from the clip's **end**, so 0
+  means it finishes exactly as the clip ends. This is the one people get wrong.
+- **`emphasis`** — a beat mid-clip. `delayMs` from the clip's start.
+- **`loop`** — runs continuously; `durationMs` is one cycle, not the total.
+  `kenBurns` is the exception: it runs once across the whole clip and holds.
+
+### The presets
+
+`in` / `out` — `fade` (500ms), `slide` (500ms; `direction` left/right/up/down,
+`distance` 0–1 of the frame, default 0.3), `pop` (500ms, easeOut; `overshoot`
+1–1.5, default 1.08), `spin` (500ms; `turns` 0–2, default 0.25), `wipe` (500ms;
+`direction`, `softness` 0–0.5, default 0.05), `blur` (500ms; `amount` 0–40,
+default 12), `colorFade` (600ms, grayscale blooming into color).
+
+`in` on text only — `typewriter` reveals whole characters in reading order.
+Set `durationMs` to the time for the entire text to appear. Without it, the
+characters type 65ms apart and finish within the clip. To set a fixed speed,
+use `durationMs: 1` with `stagger: {unit: "character", offsetMs: 40}`.
+`animate_clip` stores every typewriter in that form. A document you write by
+hand must use it too: a stored plain `durationMs` with no `stagger` shows the
+whole text at once, with no caret.
+
+`emphasis` — `pulse` (600ms; `intensity` 0–0.5, default 0.06), `flash` (400ms;
+`intensity` 0–1, default 0.6), `shake` (600ms; seeded noise on both axes:
+`intensity` 0–0.2 default 0.02, `frequency` Hz default 8, `seed` default 1,
+`fadeInMs`/`fadeOutMs` default 0; the same seed repeats the same motion),
+`bounce` (600ms; `height` 0–0.3, default 0.05), `squash` (500ms, easeOutBack;
+`amount` 0–0.5, default 0.12), `followPath` (also `loop`; `d` an SVG path in
+0..1 space plus `pathX`/`pathY`/`pathWidth`/`pathHeight`, `orient` turns the
+clip along the tangent, `startT`/`endT` pick a stretch of the path; writes
+`positionX`/`positionY`, so it replaces the clip's position).
+
+`loop` — `kenBurns` (`zoom` 0–1 default 0.12, `direction` in/out,
+`driftX`/`driftY` −0.2–0.2; one move over the whole clip, with `durationMs`,
+`delayMs` and `stagger` ignored, so the clip's length sets its speed),
+`float` (3000ms; `amplitude` 0–0.2, `frequency` cycles per period default 1,
+`seed` 0 = pure sine, else drift), `breathe` (3000ms; `intensity` 0–0.3), `rotate` (3000ms; `direction` cw/ccw),
+`hueShift` (3000ms; `direction` forward/reverse), `orbit` (3000ms; `degrees`
+default 360, `direction` cw/ccw) — which sweeps a 3D clip's camera and does
+nothing on any other clip.
+
+Seventeen named easings: `linear`, `easeIn`, `easeOut`, `easeInOut`,
+`easeOutBack`, `easeOutElastic`, `easeOutBounce`, exponential, quintic, and
+circular variants (`easeOutExpo`, `easeInOutQuint`, `easeOutCirc`), and `hold`
+for a segment that keeps its prior keyframe value until the segment ends.
+Unset means the preset's own default, and
+failing that the role's — `in` gets `easeOut`, `out` gets `easeIn`. That
+default is almost always right: an entrance decelerates into place, an exit
+accelerates away. Reach for `easeOutBack` or `easeOutElastic` only when the
+piece is playful; they read as cheap on anything corporate.
+
+`{"op": "list_animation_presets"}` reports the exact param list when this
+summary is not enough — the catalog is the authority. It is an `edit_timeline`
+op like every other call here, not a tool of its own.
+
+### Keyframes and the easing grammar
+
+`easing` takes more than the named ids. `cubic-bezier(x1,y1,x2,y2)` is
+the CSS curve: `cubic-bezier(0.16,1,0.3,1)` is the deceleration most entrances
+want. `spring(stiffness,damping,mass)` solves a real spring, so
+`spring(180,12,1)` settles with one small overshoot and `spring(180,26,1)` does
+not overshoot at all. All three constants must be positive. Anything the parser
+cannot read eases linearly and reports `unknown_easing`.
+
+The presets are where motion starts, not where it stops. A custom animation is
+one extra field and it reaches shapes no preset has: an entrance that overshoots
+twice, a hold in the middle of a move, two channels on different schedules, a
+decay, an arc, a path draw-on. Reach for one as soon as a preset is close but
+not right — bending `durationMs` and `easing` around a preset that was never the
+shape you wanted takes longer and lands flatter. `motion-curves` carries the
+channel table and the worked recipes. Then `{"role": "in", "preset": "custom",
+...}` carrying exactly one of
+
+- `curves` — `[{property, keyframes: [{t, value, easing?}]}]`, with `t` running
+  0..1 across the animation's window. The `list_animation_presets` op reports
+  the animatable properties.
+- `code` — a JavaScript body baked into curves once, host-side, at author time.
+  Nothing evaluates at render.
+
+Add `mask` when a curve drives `wipeProgress`; without it the wipe has no edge
+to run against.
+
+Motion that has to follow a piece of audio is a different call: `bake_audio_animation`
+measures an audio clip and writes the curve onto a target clip through the
+`set_baked_animation` op, either following the loudness (`mode: "envelope"`) or
+pulsing on each onset (`mode: "beats"`). Its keyframes sit in the target clip's
+own media, so trimming or splitting that clip re-slices the motion, and the
+animation carries `bakedFrom` — running it again with different settings
+replaces that curve instead of stacking a second one, and never touches a curve
+you keyframed by hand. `set_markers_from_beats` is the other tool: markers to
+cut against, rather than motion to animate with.
+
+How several animations on one channel combine decides whether the second one
+adds to the first or throws it away:
+
+| Fold | Channels | Result |
+|---|---|---|
+| add | `offsetX`, `offsetY`, `rotation`, `rotationX`, `rotationY`, `blur`, `brightness`, `hue`, `temperature`, `tint`, `cameraAzimuth`, `cameraElevation`, `cameraFov` | Values sum, so a shake and a slide both move the clip |
+| multiply | `scale`, `scaleX`, `scaleY`, `opacity`, `saturation`, `contrast`, `cameraZoom` | Values multiply, so two half-opacity ramps give a quarter |
+| min | `wipeProgress` | The tightest wipe wins |
+| replace | `positionX`, `positionY`, `anchorX`, `anchorY`, `trimStart`, `trimEnd` | One value survives — the last animation in document order. The other is discarded |
+
+The replace row is the trap. Two animations driving `positionX` over the same
+instants means one of them does nothing, and `validate_timeline` reports
+`replace_curves_overlap`. Move a clip with `offsetX` when you want it to
+compose with other motion, and with `positionX` only when you mean an absolute
+placement nothing else touches.
+
+### Durations the contract constrains
+
+`motion-principles` holds the numbers — how long an entrance runs, how long a
+title holds. What this contract adds is what the document refuses:
+
+- `in` + `out` together must fit inside the clip. A window that does not fit
+  after its `delayMs` is clamped or never runs, and `validate_timeline` says so
+  as `animation_exceeds_clip`.
+- A `loop` on a clip shorter than one cycle shows a fragment of the motion.
+  `kenBurns` is not cycled: it always spans the clip, so a short clip makes
+  its zoom and drift fast.
+
+### Choosing motion that matches the cut
+
+Pick the entrance from the edit, not from variety. A title over a locked-off
+shot can `slide`; a title over a whip pan or a moving camera should `fade` or
+`blur`, because sliding text plus moving picture reads as two unrelated
+motions. Match the direction to the picture: text sliding against the camera
+move fights it.
+
+One motion idea per moment. A clip with `pop` in, `shake` emphasis and `spin`
+out is not three times as expressive.
+
+## Animating typography
+
+Text clips take every preset above, and one thing media clips do not:
+per-word stagger. Add `stagger` to an animation on a text clip:
+
+```json
+{"op": "animate_clip", "target": "Title", "animations": [
+  {"role": "in", "preset": "pop", "durationMs": 400,
+   "stagger": {"unit": "word", "offsetMs": 80, "from": "start"}}
+]}
+```
+
+Each unit runs the full animation for `durationMs`, offset `offsetMs` from the
+previous. `from` picks which unit leads: `start` (default), `end`, or `center`.
+A stagger needs at least two units — below that it compiles as an ordinary
+block animation.
+
+`unit` is one of three, and the count is what the span math is built on:
+
+| `unit` | One unit is | Counted as |
+|---|---|---|
+| `word` | a whitespace-separated word | the words in the clip's text |
+| `character` | a grapheme cluster — an emoji, or a letter with its combining marks, counts once | every cluster including the spaces between words, which are timed and draw nothing |
+| `line` | a wrapped line | the lines the text wraps to at the sequence's width and the clip's `fontSizePx`, not the newlines you typed |
+
+The span is `durationMs + offsetMs × (units − 1)`, halved for `from: "center"`
+(the middle unit leads and both edges run last, so the largest delay is half
+the span). Six words at `offsetMs: 200` with a 500ms preset span 1500ms. The
+same line at `unit: "character"` is roughly thirty units, so the same offset
+spans six seconds — character staggers want offsets an order of magnitude
+smaller than word staggers, and a `line` stagger changes count when the frame
+does.
+
+**A span that does not fit the clip is silently compressed, not cut off.** The
+engine shrinks the per-step offset — never the per-word duration — so the last
+word still completes inside the clip. Ask for 200ms of offset on a clip with
+room for 60ms and you get 60ms: every word still animates, the motion is
+simply tighter and more simultaneous than you wrote. `validate_timeline`
+reports `stagger_compressed`.
+This is the most common reason staggered type "doesn't look staggered". Work
+out the span, compare it against `durationMs` minus any `delayMs`, and if it
+does not fit, lengthen the clip or lower the offset yourself rather than
+letting the clamp choose for you.
+
+`loop` staggers are the exception: the offset is a phase shift, so it is
+neither stretched nor clamped.
+
+Which offset reads as texture and which reads as one word at a time is in
+`motion-principles`, with the line-length limit that goes with it.
+
+For several separate clips, `stagger_animations` shifts existing animation
+delays in the order of `clip_ids` without moving the clips. Give at least two
+distinct clip IDs, each already animated, and a non-negative `offset_ms`.
+The in-product tool is `ui_timeline_stagger_animations` with the same fields.
+
+```json
+{"op":"stagger_animations","clip_ids":["logo-id","title-id","tagline-id"],"offset_ms":80}
+```
+
+Stagger applies only to text clips and only to transform and opacity motion.
+`wipe`, `blur` and `colorFade` stay block-level even with a stagger set — the
+mask and effect curves are per-layer, not per-word. A stagger on a media clip
+is ignored, not an error, so a "why isn't it staggering" bug is usually a clip
+that is not `mediaType: "text"`.
+
+Type sizes are authored against the sequence resolution: `fontSizePx` on a
+1920×1080 sequence means the same thing at any preview width.
+
+## Document motion fields
+
+The fields below belong to clips in the complete timeline document. Merge
+them into the clip read by `get_timeline`, retaining its other fields and
+animations, then write the full document with `set_timeline_document`.
+`edit_timeline` and `ui_timeline_animate_clip` do not accept them as animation
+inputs.
+
+`styleTracks` animate visual properties in the same animation window as a
+preset. Each stored animation needs `id`, `role`, `preset`, and `durationMs`.
+Targets include `text.color`, `shape.fill`, `shape.cornerRadius`,
+`clip.borderRadius`, `mask.featherPx`, `effect.<effect-id>.<numeric-field>`,
+supported effect colors such as `effect.bg-field.colorB`,
+gradient stops, and compatible `shape.d` or `mask.d` paths. The clip must
+already have the targeted style, mask, or effect. A per-glyph target such as
+`glyph.color` also needs text `stagger`.
+
+```json
+{"animations":[{"id":"title-color","role":"in","preset":"fade","durationMs":600,"styleTracks":[{"target":"text.color","keyframes":[{"t":0,"value":"#8bd5ff"},{"t":1,"value":"#ffffff","easing":"easeOutExpo"}]}]}]}
+```
+
+`textAnimator` changes text content over its animation window. `ticker`
+supports `from`, `to`, `decimals`, `padTo`, `prefix`, and `suffix`.
+Set `groupSeparator` to `","` for grouped thousands such as `2,847`;
+without it the output stays ungrouped. `scramble` supports `charset` and
+deterministic `seed`. It needs a text clip.
+An animation's `beat` binds its start to a one-based beat index at the live
+sequence tempo; `scope` is `clip` or `sequence`, and `offsetMs` moves it around
+that beat. `delayMs` still applies on top.
+
+```json
+{"id":"count-up","role":"emphasis","preset":"custom","durationMs":900,"beat":{"index":3,"scope":"sequence","offsetMs":-20},"textAnimator":{"kind":"ticker","from":1,"to":7,"padTo":2}}
+```
+
+`animationLinks` copy a source clip's authored `positionX`, `positionY`,
+`scale`, `rotation`, or `opacity` channel, with optional time offset, loop,
+scale, and offset. A `wiggle` link supplies seeded motion without a render-time
+script. Links do not follow the source's own links. Resolve each
+`sourceClipId` against the document's clip IDs before writing it. An opacity
+link replaces the target clip's own opacity while its group and transition
+coverage still multiply the result.
+
+```json
+{"animationLinks":[{"target":"positionX","sourceClipId":"leader-id","source":"positionX","scale":0.35},{"target":"rotation","kind":"wiggle","amplitude":0.025,"frequencyHz":1.4,"seed":8}]}
+```
+
+`layout` turns a group clip into a flex container for its real children
+(their `parentId` names the group): `flexDirection: "row" | "column"`,
+`gap`, `justifyContent`, `alignItems`, `padding`. A child's own sizing is
+`flexItem` (`grow`, `width`, `position: "absolute"` + `inset` to fill the
+container). `repeater.count` includes the original clip and is capped at
+128. `timeStepMs` offsets each copy in time. These are fields on a clip, not
+new clip records to add by hand.
+
+Do not scroll a still plate by tiling it with a `repeater`. Each copy meets the
+next at a seam, and the seam shows when the image differs at its edges. A
+generated rain plate is denser at the top, so it always does. To make rain
+fall, move one plate to a random offset on `hold` keyframes every two frames.
+This reads as falling rain and has no seam.
+
+```json
+{"layout":{"display":"flex","flexDirection":"row","gap":24},"repeater":{"count":3,"positionStep":{"x":180,"y":0},"timeStepMs":67}}
+```
+
+(`logo-id`/`wordmark-id` are separate clips with `parentId` naming this group.)
+
+`camera2d` is a sequence document field. It needs `position`, `depthPx`, and
+positive `focalLengthPx`. Keyframes use absolute `timeMs` and include position
+and depth. Add `depthPx` to a clip's existing `transform` for perspective;
+`focusDepthPx` and `aperturePx` add depth-of-field blur. `camera2d: null`
+clears the camera.
+
+For a tilted wall of cards, use a parent group's `rotation`, `rotationX`, and
+`perspective` for the shared tilt, each card's `depthPx` and scroll animation
+for the separate planes, and `camera2d` for the push and depth blur. Keep a
+shape's normalized geometry inside the frame-sized source raster. Move the
+clip or group with `transform.position` or custom `offsetX`/`offsetY` curves
+to scroll or fly it across the frame; geometry outside that raster is clipped
+before the transform places it.
+
+```json
+{"camera2d":{"position":{"x":0,"y":0},"depthPx":0,"focalLengthPx":1400,"keyframes":[{"timeMs":0,"position":{"x":0,"y":0},"depthPx":0},{"timeMs":1200,"position":{"x":90,"y":-20},"depthPx":120}]}}
+```
+
+`motionBlur` is per clip: `samplesPerFrame` is 1–32 and `shutterAngle` is
+0–360 degrees. One sample disables blur for that clip. A higher count sets a
+minimum; the scene renders at its highest requested count, with evenly
+weighted samples across each layer's own shutter window. `steppedTime.fps`
+quantizes a clip's source and animation clock. `temporalEcho` adds delayed
+copies through `copies`, `intervalMs`, and `opacityDecay`.
+
+```json
+{"motionBlur":{"samplesPerFrame":8,"shutterAngle":180},"steppedTime":{"fps":12},"temporalEcho":{"copies":3,"intervalMs":80,"opacityDecay":0.5}}
+```
+
+## Groups
+
+`{"op":"add_group","name":"Lower third","startMs":4000,"durationMs":4000,"children":["name-id","role-id"]}` makes a clip with no media whose transform, opacity
+and window every clip naming it inherits. `{"op": "set_parent", "target":
+"Name plate", "parentId": "<group id>"}` adopts a clip that already exists;
+`"parentId": null` releases it, and a cycle is refused.
+
+Rig a lower third this way: scrim, name, role, each on its own overlay track,
+all three parented to one group. Then animate the **group**. One `slide` in and
+one `fade` out on the group moves the assembly together and keeps the parts
+locked to each other, where animating them separately is three chances to
+drift.
+
+Children keep their own tracks, so grouping does not change what covers what.
+A plain group's opacity multiplies into each child. A group with an effect,
+non-`normal` blend mode, or transition precomposes its children into one
+surface first. The effect or transition then runs once on the assembled
+picture. Put a `glow` on the group for the whole look, on a child for that
+child alone.
+
+`parent_missing`, `parent_not_group` and `parent_cycle` all mean the child
+renders unparented, losing the group's transform, opacity and window.
+
+## Transitions
+
+A transition is between clips, not on one clip. It is authored on the
+**incoming** clip and resolved for both: the compositor finds the clip beneath
+it on the same track and gives that one the complementary half of the cut.
+The incoming clip may be a group: `set_transition` on the group transitions
+its whole precomposed assembly, with children still parented on their own
+tracks. Its outgoing partner is the previous overlapping sibling on the
+group's track under the same parent.
+
+Two clips on the same track whose times overlap dissolve across the overlap
+with no tool call at all. The corollary: **an accidental overlap is an
+accidental dissolve.** When two clips look soft where you wanted a hard cut,
+check their `startMs` and `durationMs` before looking anywhere else.
+
+`set_transition` picks a cut instead of taking the default:
+`{"op": "set_transition", "target": "Shot 2", "transition": {"type": "wipe",
+"durationMs": 500, "direction": "left", "softness": 0.1}}`. Pass
+`"transition": null` to clear it. The cut plays over the target's head, so
+**overlap the two clips by at least `durationMs`** or there is nothing beneath
+for it to play against — a transition with nothing under it reads as a fade
+from black.
+
+| Type | What moves | Reach for it when |
+|---|---|---|
+| `crossfade` | Incoming fades up | Two shots of the same scene; the safe default |
+| `dipToColor` | Both fade through a solid | A scene change, a chapter break. `color` is yours to pick |
+| `wipe` | Feathered edge reveals the incoming | A graphic or split-screen feel. `softness` 0 is a hard edge |
+| `push` | Both clips travel one frame width | Lateral energy; the two read as one moving picture |
+| `slide` | Only the incoming travels | The new shot arrives over a shot that holds |
+| `zoom` | Outgoing grows, incoming comes in from 0.8 | A push into the next beat |
+| `whip`, `zoomBlur` | Motion blur across a directional or zooming cut | Fast camera energy |
+| `glitch` | Displaced digital cut | A deliberate electronic break |
+| `gradientWipe`, `iris` | Spatial threshold or aperture reveal | Designed graphic transitions |
+| `lightLeak` | Localized color field across the cut | A flare-like bridge |
+
+`direction` on `wipe`, `push`, `slide`, `whip`, and `gradientWipe` names the
+incoming edge. `gradientWipe` also takes `map: "linear" | "radial" |
+"noise"`, `scale`, `seed`, and `softness`. `iris` takes `softness`;
+`lightLeak` takes `color`, `scale`, and `seed`. `easing` takes a named id,
+`cubic-bezier(...)`, or `spring(...)`.
+
+`fadeInMs` and `fadeOutMs` on `set_clip_params` are audio fades. The compositor
+does not read them, so they will not fade a picture — for that, animate the
+clip with a `fade` `in` or `out`.
+
+A transition's opacity multiplies with animation opacity rather than replacing
+it, so a clip that both dissolves in and carries a `fade` in ramps twice and
+reads slower and softer than either alone. Pick one.
+
+`validate_timeline` reports `transition_exceeds_duration` when the cut is
+longer than the clip carrying it, and `unknown_transition` for a type or
+direction this build cannot draw — which falls back to a cross-fade running
+left rather than failing the render.
+
+## Masks and mattes
+
+`{"op": "set_mask", "target": "Title", "mask": {"kind": "rect", "y": 0.2,
+"height": 0.6, "featherPx": 24}}` cuts the layer to a shape in the clip's own
+0..1 space. `kind` is `rect`, `ellipse` or `path` (with an SVG `d`).
+`featherPx` softens the edge, `invert` keeps the outside instead, and
+`"mask": null` clears it. A path that cannot rasterize reports
+`mask_path_invalid` and the layer draws unmasked — the whole picture shows
+through, the opposite of what you asked for.
+
+`{"op": "set_matte", "target": "Fill", "matte": {"source": "Text shape",
+"mode": "alpha"}}` uses another clip as this one's transparency. `alpha` reads
+the source's opacity, `luma` its brightness, and `invert` flips it. **The
+source clip stops drawing itself.** That is the point, and it is also why a
+matte pointed at a clip you still wanted on screen reads as a deletion. Reach
+for it when text has to be filled with moving footage: footage on the fill
+clip, text on the source. `matte_source_missing` is an error, and the layer
+then draws unmatted, showing everything the matte was hiding.
+
+## Clip effects
+
+`set_effects` replaces the whole chain and applies it in the
+order given; an empty list clears it. The tool also accepts `pixelate`,
+`posterize`, `directionalBlur`, `lensDistortion`, `stylize`, `generator`, `lut`,
+and `grain` alongside `color`, `blur`, `glow`, `dropShadow`, `vignette`,
+`sharpen`, `chromaKey`, `curves`, `levels`, and `liftGammaGain`. Its flat input
+uses `{type, ...typeFields}`. It assigns effect IDs and enables each effect;
+it does not accept stored `id` or `enabled` fields. `validate_timeline`
+reports `unknown_effect` for an unrecognized type. The Canvas 2D preview
+applies all known effects through CPU passes when its host supplies scratch
+surfaces. `preview_timeline_frame.effects_not_applied` lists unknown types;
+`degraded` reports missing surfaces and other draw limitations.
+
+```json
+{"op":"set_effects","target":"Shot 2","effects":[{"type":"grain","amount":0.12,"size":1.1},{"type":"stylize","mode":"dither","amount":1,"seed":4}]}
+```
+
+## Time remap
+
+`{"op": "set_time_remap", "target": "Shot 3", "timeRemap": {"keyframes":
+[{"t": 0, "sourceMs": 0}, {"t": 1, "sourceMs": 4000, "easing": "easeInOut"}]}}`
+maps timeline time onto source time. `set_time_remap` replaces the whole map
+each time it is called. `t` runs 0..1 over the clip's window and
+must start at 0, end at 1 and ascend; `sourceMs` says which millisecond of the
+source plays there, so a descending pair is a reverse and a flat pair is a
+freeze. `"timeRemap": null` clears it, and the remap replaces the clip's rate.
+A repeated or backwards `t` is `time_remap_not_monotonic`, an error.
+
+`split_clip` and `trim_clip` refuse a remapped clip. Both would have to
+re-derive the map, and re-deriving it silently is how a speed ramp turns into a
+different move. Clear the remap, cut, re-apply.
+
+## Compositions
+
+A composition is a group saved as a reusable rig with named parameters.
+`list_compositions` reports what is available, `get_composition` shows one
+rig's parameters and their defaults, and
+`{"op":"insert_composition","composition_id":"lower-third","startMs":4000,"params":{"name":"Ada"}}`
+instantiates it into the document with fresh clip ids. Use parameter names
+returned by `get_composition`; `name` here is an example.
+
+Bundled examples include `title-card`, `lower-third`, `caption-bar`,
+`callout`, `cta-end-card`, `logo-sting`, `title-slam`, `word-cards`,
+`window-frame`, and `number-ticker`. Use `list_compositions` for the
+templates available in the current workspace.
+
+Insert first, then override `params`. The rig's timing and motion are already
+balanced against each other, and rebuilding it from bare clips throws that
+away. Edit the instantiated clips only where the brief actually differs.
+
+When a group should be reused, `save_composition
+{timeline_id, group_target, name, params}` extracts it as a composition.
+`params` map names to typed defaults and JSON pointers into child fields.
+`insert_composition` remaps the group and child clip IDs, including internal
+layout and animation links, while preserving references to clips outside the
+composition.
+
+## Cutting to the beat
+
+`detect_audio_events` on the music clip reports onsets and a tempo. Its
+`onsets.times` are in **seconds** and the ops take milliseconds, so multiply by
+1000. Read the tempo's `reliable` flag before building a grid from `bpm`:
+speech and room tone produce a confident-looking number from nothing.
+
+`{"op":"set_markers_from_beats","onsets_ms":[0,500,1000]}` lays the
+grid down so you can see it, one marker per onset. `{"op": "snap_to_beats", "targets": "all",
+"tolerance_ms": 60, "mode": "start", "action": "move"}` pulls clip edges onto
+it. Either takes `onsets_ms`, or a `bpm` with an `offset_ms`; with `bpm`,
+`set_markers_from_beats` also needs `count`, which an `onsets_ms` grid ignores.
+
+The default 60ms tolerance is about two frames at 30fps: close enough that a
+cut reads as on the beat, tight enough that it will not drag an edge to a beat
+it was never near. Widen it only when the grid is loose, because a large
+tolerance moves cuts you meant to leave alone. `snap_to_beats` reports every
+target, including the ones no beat was in reach of, with the reason.
+
+`action: "move"` slides the clip and keeps its length, which shifts everything
+downstream. `action: "trim"` changes the length and leaves the neighbours
+where they are. Move a title that has to land on a hit; trim a picture clip
+whose out point has to meet the next shot.
+
+## Validate the output
+
+Two checks, and they answer different questions.
+
+**`validate_timeline`** answers "is this document sound": unknown animation
+presets and transitions, fades and cuts longer than the clip carrying them,
+clips on tracks the document lacks, overlapping clips, clips shorter than a
+frame, in/out points that cannot render, duplicate ids. Run it after every batch
+of edits.
+
+It also names the motion failures that used to be yours to remember. Each
+finding carries a stable `code`; these are the ones that mean the picture will
+not perform the motion you wrote:
+
+| Code | Severity | What to do about it |
+|---|---|---|
+| `unknown_animation_preset` | error | The stored `preset` is not one this build ships. Use an id from `list_animation_presets` |
+| `shape_path_invalid` | error | A `path` shape's `d` cannot be parsed, so the shape draws nothing. `add_shape_clip` stores the path unchecked, so this is where it surfaces. Fix the `d` |
+| `parent_cycle` | error | A `parentId` chain loops, so the group cannot be resolved at all. Break the loop |
+| `matte_source_missing` | error | The matte names a clip the document lacks, or itself. The layer draws unmatted, showing everything the matte was there to hide |
+| `time_remap_not_monotonic` | error | `t` repeats or goes backwards. `sourceMs` may descend — that is a reverse — but `t` may not |
+| `custom_animation_invalid` | error | A stored `preset: "custom"` animation has unusable baked numeric curves and no style track or text animator to render. Re-bake its curves or add a valid typed track |
+| `animation_style_invalid` | error | A style target has no matching clip style, a path cannot morph, a color cannot parse, or a glyph track lacks text stagger. Fix the target or the clip style |
+| `animation_exceeds_clip` | warning | The window does not fit the clip after its delay, so the motion is clamped or never runs. Shorten `durationMs`, cut the delay, or lengthen the clip |
+| `stagger_compressed` | warning | The units did not fit, so the per-unit offset was shrunk. The line lands faster and flatter than you wrote it. Shorten the per-unit `durationMs` or give the clip more time |
+| `typewriter_not_staggered` | warning | A `typewriter` is stored with a plain `durationMs` and no `stagger`. Nothing draws for that time, then the whole text appears with no caret. Store `durationMs: 1` with a `character` stagger, or apply the preset again through `animate_clip` |
+| `animation_holds_rest_before_window` | warning | A custom `out` curve starts away from the channel's rest value after clip start. An `out` does not apply before its window, so the frames before it show the rest value (a gauge drawn from `trimEnd: 0` shows a full ring). Start the window at clip start. For a `trim`, `position` or `anchor` curve, you can instead set the clip's own value to the first keyframe |
+| `replace_curves_overlap` | warning | Two animations drive one absolute channel (`positionX/Y`, `anchorX/Y`, `trimStart/End`) at once. The last in document order wins and the other is discarded. Separate them in time or fold them into one curve |
+| `text_backing_unproven` | warning | Text draws over picture with no `background`, `stroke` or shape behind it, so nothing decides whether it reads. Preview the frame and look, or give it a plate |
+| `text_illegible` | warning | Type under 2.5% of frame height, or under a 3:1 contrast ratio against its own `background` plate or a full-frame shape behind it. Raise `fontSizePx`, darken the scrim, or add a `stroke` |
+| `unknown_easing` | warning | Outside the grammar, so it eases linearly. Check the spelling: `easeOut`, not `ease-out` |
+| `unknown_transition` | warning | This build cannot draw that `type` or `direction`; it cross-fades left instead. Pick one from the table above |
+| `unknown_effect` | warning | This build cannot apply that effect; the layer draws ungraded |
+| `unknown_shape_kind` | warning | No geometry for that `shapeStyle.kind`, so the shape draws nothing. A scrim that vanished is usually this |
+| `transition_exceeds_duration` | warning | The cut is longer than the clip carrying it. Shorten the transition or lengthen the clip |
+| `parent_missing`, `parent_not_group` | warning | The `parentId` names nothing, or names a clip that is not a group. The child renders unparented, losing the group's transform, opacity and window |
+| `mask_path_invalid` | warning | The `kind` or path `d` cannot rasterize, so the layer draws unmasked and the whole picture shows through |
+| `layer_cap_exceeded` | warning | More video clips overlap at that instant than the compositor draws; the ones on lower tracks are dropped |
+| `font_not_portable` | warning | The family is not one NodeTool ships, so every host resolves it against its own installed fonts and the editor and the render can differ. Pick a bundled family for anything you hand back |
+| `field_stripped` | warning | A field the schema drops, lost on the next save. Usually a newer build wrote it; re-author it in this build's grammar |
+
+The contrast half refuses to guess: a colour it cannot parse, a translucent
+plate or gradient-filled type produces no contrast finding. Type over picture
+with no plate at all is the case it can name without measuring, and it says so
+as `text_backing_unproven`. Either way a silent `text_illegible` is not a pass
+— that is what the frames are for.
+
+**`preview_timeline_frame`** answers "what does it look like". It composites
+the real frame — every track layered in order, transforms and opacity applied,
+animations sampled, transitions part way through, text and shapes drawn — at
+the timecodes you name. It needs no browser, no GPU and no open editor.
+
+```json
+{"timeline_id": "<id>", "times_ms": [1200, 1450, 3000]}
+```
+
+`range {from_ms, to_ms, count}` samples evenly across a span instead of naming
+each timecode — the way to watch a whole entrance rather than guess three
+points inside it. `sheet: true` tiles every frame into one labelled contact
+sheet, so a sweep is one image to read instead of a handful of handles.
+
+It returns an image handle per timecode; call `view_image` on the ones you need
+to see. Beside each frame it lists the layers top of the stack first, with the
+opacity, blend mode and wipe progress each one resolved to — often enough to
+diagnose a problem without looking at a pixel.
+
+**Sample the middle of a motion, not its ends.** The endpoints are the states
+you already know: before an entrance the clip is absent, after it the clip is
+at rest. A 400ms fade-in starting at 1000ms tells you nothing at 1000ms or
+1400ms and everything at 1200ms. For each animation you added, preview at:
+
+- the midpoint of the entrance,
+- a held moment between the in and out,
+- the midpoint of the exit,
+- and, for staggered text, a point after the first word lands but before the
+  last does — the frame where half the line is on screen is the one that
+  reveals a stagger that is too slow.
+
+What the frames catch that a validator cannot: text over a busy or same-colored
+plate, a lower-third under the wrong element because two tracks are the wrong
+way round, a title that has slid outside the frame, a stagger still finishing
+when the clip ends, a scrim covering the face it was supposed to sit beside, an
+element that never appears because its clip is on an audio track.
+
+Each frame carries `degraded` entries for a difference the Canvas 2D host
+could not draw, such as a missing scratch surface, a hard mask edge, or an
+unsupported perspective transform. Read the actual entries before deciding
+which part of the frame needs a GPU render. Known clip effects have CPU passes.
+
+Read the `skipped` field on any layer that drew nothing — it says whether the
+clip is still `draft`, its asset would not read, or the source had no frame at
+that time. A missing picture is usually an unrendered clip, not a motion bug.
+
+`effects_not_applied` names enabled effect types the Canvas 2D compositor does
+not recognize. A known effect such as chroma key, vignette, sharpen, or LUT
+should render in the frame preview; a missing scratch surface instead appears
+in `degraded`.
+
+
+## The render loop
+
+Change one thing, preview the same timecodes, compare. When motion is wrong,
+the order to check is: is the element on screen at all (layer present in the
+report), is it in the right stacking position (`z_index`), is it at the right
+opacity (`opacity`), is it in the right place (look at the frame). Working down
+that list beats re-authoring the animation.
+
+For every defect named by a `view_image` look, a preview layer report, or a
+model critique of the render, fix it and re-check the same timecode, or tell
+the user it remains open and why. Never ship past a named defect silently. If
+`view_image` returns no pixels, tell the user you could not see the frames.
+Do not claim a visual check.
+
+`compare_timeline_frames {a, b, times_ms | range}` measures what actually moved
+between two documents or two versions. Run it after a change the user did not
+ask for (a restructure, a composition insert, a snap pass) so you can say
+which frames it touched instead of hoping it touched none.
+
+Before calling the cut done, render it. `render_timeline` with a
+`preview_scale` below 1 while you are still iterating, then once at full size.
+The preview answers what one timecode looks like; the render answers whether
+the file plays.
+
+A whole-document rewrite goes through `set_timeline_document`, which validates
+before it writes and snapshots what it replaces. Name that snapshot
+(`snapshot_name: "before the title pass"`) so the version list says what you
+were about to do. For anything smaller, `create_timeline_version` first and
+`edit_timeline` after.
+
+Stop when the motion is right, and say what you animated.