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

package/dist/_skills/motion-background/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: motion-background
+description: Build an ambient backdrop on a NodeTool timeline using shape gradients, procedural generator effects, slow loops, or generated video. Use for title cards, hero beds, end cards, lower-third plates, and quiet loops behind a subject.
+---
+
+# Motion Background → the bed
+
+A background that draws attention has failed. Slow, low contrast, looping with
+no visible join, and cheap enough that the picture in front of it still
+composites.
+
+`timeline-edit-ops` carries the op contract for the calls named here.
+`color-motion` chooses the palette the bed is built from, and `motion-curves`
+writes the loop when no wrapping preset holds the seam.
+
+## Pick the cheapest thing that reads
+
+| Look | Build it from | Cost |
+|---|---|---|
+| Flat or gradient wash | One full-frame `rect` shape with `fillStyle` linear or radial | Shape clips do not count against the video layer cap |
+| Soft mesh or conic wash | One full-frame shape with a `generator` effect, `mode: "meshGradient"` or `"conicGradient"` | One procedural effect, no model call |
+| Shaped colour blobs | Radial-filled `ellipse` clips, low opacity, blurred | More control over each blob's motion |
+| Noise, fractal, particles, light leak, grid | One full-frame shape with the matching `generator` mode | Procedural and seedable |
+| Drifting texture | An image clip with a `kenBurns` animation | Outside the video layer cap |
+| Smoke, ink, or clouds | A generated video bed, looped | One video layer and a model call |
+| Colour cycle | Any of the above plus a `hueShift` loop | An additional grade |
+
+At most **eight video layers** composite at once, resolved from the lowest track
+index. Text, shape and image clips are not counted, so a bed built from shapes
+costs nothing in that budget. Nine overlapping video clips means the bottom one
+silently does not draw, reported as `layer_cap_exceeded`.
+
+## A procedural bed
+
+Add a full-frame shape and apply a generator effect to it. Modes are `noise`,
+`fractal`, `conicGradient`, `meshGradient`, `gradientField`, `particles`,
+`lightLeak`, and `gridPattern`. `colorA` and `colorB` set the two colours;
+`scale`, `amount`, `angle`, `time`, and `seed` shape the field. For movement,
+set `animate: true`, which samples the current timeline time into the effect.
+Keep a fixed `seed` for repeatable frames. This clock keeps moving; it does not
+make the procedural field wrap at the clip boundary. For a seamless loop, use
+a wrapping clip animation or match the endpoints in a rendered loop.
+
+```json
+{"op": "set_effects", "target": "Bed", "effects": [
+  {"type": "generator", "mode": "meshGradient",
+   "colorA": "#10233c", "colorB": "#ec6b45", "scale": 6,
+   "amount": 0.6, "seed": 9, "animate": true}]}
+```
+
+For a dark wash that bands, put a fixed-seed `stylize` `dither` after the
+generator or gradient in the effect list. Dither breaks up 8-bit steps but
+cannot restore precision lost in the source. `color-motion` covers this look.
+
+## A mesh from shapes
+
+For individual moving blobs, stack radial fills over a base. Each ellipse is
+its own clip on an overlay track, at 30–60% opacity, with a `blur` effect wide
+enough that no edge reads:
+
+```json
+{"op": "add_shape_clip", "shape": {"kind": "ellipse",
+ "x": 0.05, "y": 0.1, "width": 0.6, "height": 0.7,
+ "fillStyle": {"type": "radial", "stops": [
+   {"offset": 0, "color": "#5b8cff"}, {"offset": 1, "color": "#5b8cff00"}]}},
+ "durationMs": 12000}
+```
+
+```json
+{"op": "set_effects", "target": "Ellipse", "effects": [{"type": "blur", "radius": 120}]}
+```
+
+Then give each blob a different `loop`: `float` with `amplitude` 0.01–0.015
+(a fraction of frame height each way, so at most 3% of travel),
+`breathe` at `intensity` 0.03–0.08, and cycle lengths that do not divide each
+other — 9000, 13000, 17000ms — so the composite never visibly repeats.
+
+`blendMode` `screen` or `add` on a blob over a dark base builds light rather than
+covering it; `multiply` or `soft-light` deepens instead. That choice matters more
+than the fill colours.
+
+## Loops that actually loop
+
+`float`, `breathe`, `rotate` and `hueShift` are built to wrap: they start and end
+at the same value, so `durationMs` is a period and the seam is invisible. A
+custom loop curve must do the same — the value at `t: 1` has to equal the value
+at `t: 0` or the bed jumps every cycle.
+
+`kenBurns` is the exception: it is a one-shot across the whole clip, holding at
+its end, so it does not repeat and its `durationMs` is ignored. On a long bed a
+drift from `kenBurns` finishes and then sits still. For continuous drift over a
+long clip use `float` with a long period instead.
+
+Periods that read as ambient: 8000–30000ms. Anything under about 5000ms reads as
+a screensaver, and text in front of it becomes hard to hold.
+
+## Keep it behind
+
+- Background sits on the **highest** track index, because the lowest draws on
+  top. A bed that covers the picture is a track-order mistake, not an opacity
+  one.
+- Contrast: pull it down with a `color` effect at `saturation` 0.5–0.7 and
+  `brightness` slightly negative before touching opacity. A desaturated bed
+  reads as depth; a faded one reads as a mistake.
+- Amplitude: nothing in the bed should travel more than about 3% of the frame,
+  or the eye starts tracking it.
+- Give the foreground a scrim if the bed's bright regions cross the type: a black
+  `rect` shape at 40–60% opacity on a track index between the bed and the text.
+  `validate_timeline` reports `text_illegible` for what it can measure, and says
+  nothing about gradients — look at the frame.
+
+## A generated bed
+
+For smoke, ink, or clouds that the procedural modes cannot draw, generate video.
+Use `find_model` with `text_to_video`, then `generate_video`,
+then `add_media_clip` with the returned `asset://` reference. The `find_model`
+result names a `prompting_skill` for the line it picked; load it, because each
+line wants the prompt shaped differently. Whatever the line, prompt for slow,
+even motion with no cuts and no subject; a bed with an event in it is a shot,
+not a bed. On a line that writes native audio (Seedance 2, Veo 3, MiniMax H3,
+Kling 2.6 and later) the bed arrives with a soundtrack: either brief it as room
+tone and keep it, or mute the clip under the track you meant to use —
+`video-audio-continuity` is the rule for which.
+
+A generated clip does not loop. Cover a longer sequence by duplicating it and
+crossfading the joins: overlap the copies by 800–1500ms on one track, which
+dissolves with no call at all, or `set_transition` `crossfade` on the incoming
+copy to pin the length.
+
+## Reduced motion, and knowing when to stop
+
+A bed exists to sit under something. Before adding a second idea to it, check
+whether the first one is doing anything at all — a drift too slow to see is
+budget spent on nothing, and one too fast is the reason nobody read the headline.
+One idea, one amplitude, one period family.
+
+## Check it
+
+- `preview_timeline_frame` with a `range` across a full cycle and `sheet: true`,
+  which is how you see whether a loop breathes evenly or lurches. Sampling three
+  timecodes will not show a seam.
+- The same sweep with the foreground on, to confirm the type still reads at every
+  point in the cycle rather than only where you happened to look.
+- `render_timeline` at a low `preview_scale` while iterating. A bed is judged
+  over seconds, and a still cannot tell you whether it is calm.

package/dist/_skills/motion-curves/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: motion-curves
+description: Write NodeTool timeline animation curves by hand or bake a JavaScript body into curves once. Use for overshoot, bounce, anticipation, arcs, path draw-on, style-property animation, or motion a preset cannot express.
+---
+
+# Motion Curves → animation nobody had a preset for
+
+An `animate_clip` input with `{"preset":"custom"}` carries exactly one of
+`curves` (keyframes you write) or `code` (a JS body baked into curves once,
+host-side). Add `mask` when a curve drives `wipeProgress`. A stored document
+animation can instead carry `styleTracks` or `textAnimator` without numeric
+custom curves.
+
+`timeline-edit-ops` carries the op contract and the preset catalog this file is
+the escape hatch from. `motion-principles` gives the duration and the shape a
+curve should hit before you write its keyframes.
+
+For numeric custom curves, call `edit_timeline` with an `animate_clip` op or
+the in-product `ui_timeline_animate_clip` tool. Both accept the flat `curves`
+or `code` input shown below. For stored `styleTracks`, `textAnimator`, or
+`beat`, read `get_timeline`, edit the full clip animation in its document,
+then call `set_timeline_document` with every existing document field. The
+`animate_clip` input does not author those stored fields.
+
+## When to write one
+
+Write curves as soon as a preset is close but not right. The catalog is eight
+entrance shapes and a handful of beats — where motion starts, not where it
+stops — and a piece whose every title arrives with `pop` reads like a template.
+A curve costs one field and a few numbers, and the recipes below are the shapes
+worth reaching for: an entrance that overshoots twice, a hold in the middle of a
+move, two channels on different schedules, a decay, an arc, a wiggle, a path
+draw-on.
+
+Two shapes need no curve, and writing one anyway only makes the document harder
+to read: a single overshoot and a physical settle are already `easing` strings.
+`cubic-bezier(0.16,1,0.3,1)` and `spring(180,12,1)` on an ordinary preset do
+both. Everything past that is this file.
+
+## Curves by hand
+
+```json
+{"op": "animate_clip", "target": "Title", "animations": [
+  {"role": "in", "preset": "custom", "durationMs": 600,
+   "curves": [
+     {"property": "offsetY", "keyframes": [
+       {"t": 0, "value": 80}, {"t": 0.7, "value": -12, "easing": "easeOut"},
+       {"t": 1, "value": 0, "easing": "easeInOut"}]},
+     {"property": "opacity", "keyframes": [
+       {"t": 0, "value": 0}, {"t": 0.4, "value": 1}]}]}]}
+```
+
+`t` runs 0..1 over the animation's **window**, not the clip. `easing` on a
+keyframe eases the segment **ending** there. Keyframes are sorted, `t` is clamped
+to 0..1, and a curve that stops short of either end is extended by holding its
+end value — so sampling 0.05..0.95 does what it looks like.
+
+Limits: 16 curves per animation, one per property, 4096 keyframes each.
+
+`durationMs` defaults to the clip's own duration, so curves span the whole clip
+unless you say otherwise.
+
+## The channels, and how they combine
+
+Several animations can drive one channel. How they fold decides whether the
+second adds to the first or throws it away.
+
+| Fold | Channels | Identity | Result |
+|---|---|---|---|
+| add | `offsetX`, `offsetY`, `rotation` (radians), `rotationX`, `rotationY` (deg), `blur` (px), `brightness` (−1..1), `hue` (deg), `temperature`, `tint`, `cameraAzimuth`, `cameraElevation`, `cameraFov` (deg, 3D clips only) | 0 | Values sum |
+| multiply | `scale`, `scaleX`, `scaleY`, `opacity` (0..1), `saturation` (0..4), `contrast` (0..4), `cameraZoom` (3D clips only) | 1 | Values multiply |
+| min | `wipeProgress` (0..1) | 1 | The tightest wipe wins |
+| replace | `positionX`, `positionY` (canvas px), `anchorX`, `anchorY` (0..1), `trimStart`, `trimEnd` (0..1) | none | The last animation in document order wins; the other is discarded |
+
+The replace row is the trap. Two animations driving `positionX` over the same
+instants means one does nothing, reported as `replace_curves_overlap`. Move a
+clip with `offsetX` when it should compose with other motion, and with
+`positionX` only for an absolute placement nothing else touches.
+
+Land the last keyframe on the identity value unless you mean the clip to stay
+where the curve stopped — and remember the role decides whether it stays: an
+`in` window holds its `t: 0` values before it and contributes nothing after, an
+`out` window holds its `t: 1` values after it, `emphasis` holds neither, and
+`loop` repeats its cycle, so a loop curve must end on the value it started on.
+
+`list_animation_presets` reports this table from the engine. Read it there rather
+than from memory when a channel's range matters.
+
+## Style curves in a document
+
+Use `styleTracks` on a stored animation when the target is a visual property
+rather than a numeric motion channel. The target names a clip style such as
+`text.color`, `shape.cornerRadius`, `mask.featherPx`, or
+`clip.borderRadius`; an effect target is
+`effect.<effect-id>.<numeric-field>` or a supported effect color such as
+`effect.bg-field.colorB`. A target needs the matching style,
+mask, or effect on the clip. Color values interpolate through the supported
+CSS color parser. `shape.d` and `mask.d` paths need matching commands and point
+counts. Glyph targets need a text stagger. `validate_timeline` reports an
+invalid target, incompatible path, or unsupported color.
+
+This is one complete stored animation object to merge into an existing clip's
+`animations` array before the full-document write:
+
+```json
+{"id":"round-in","role":"in","preset":"fade","durationMs":600,"styleTracks":[{"target":"clip.borderRadius","keyframes":[{"t":0,"value":0},{"t":1,"value":30,"easing":"easeOutExpo"}]}]}
+```
+
+`styleTracks` can accompany a preset, so a title can fade while its color
+changes. The `id` is required in the stored document; `animate_clip` creates
+one for its own inputs. Use `timeline-edit-ops` § Document motion fields for
+links, text animators, beat binding, and the document write boundary.
+
+## The code body
+
+A JavaScript body run **once**, at author time, in the QuickJS sandbox. It
+returns keyframes; the keyframes are stored on the clip; every renderer samples
+those. Nothing evaluates per frame, which is why a body cannot react to playback
+and why the same animation looks identical in the preview, the export and the
+headless compositor.
+
+The bake is hermetic: no toolbelt, no `nodetool.*`, no network, no secrets. Just
+arithmetic, a 10-second ceiling, and `inputs`:
+
+| `inputs` field | What it is |
+|---|---|
+| `role` | `in`, `out`, `emphasis` or `loop` |
+| `durationMs` | The animation's own window |
+| `clipDurationMs` | The clip it sits on |
+| `canvasWidth`, `canvasHeight` | Sequence pixels — turn a normalized distance into px here |
+| `params` | The animation's `params`, untouched |
+| `staggerCount` | Units a text clip splits into, or 0 |
+| `sampleCount` | Suggested density for a continuous function |
+
+Return `{curves}` — the same shape as the JSON above — or `{samples}`, one bag
+per point in time:
+
+```js
+const n = inputs.sampleCount;
+const samples = [];
+for (let i = 0; i < n; i++) {
+  const t = i / (n - 1);
+  samples.push({ t, offsetY: 80 * (1 - t), opacity: t });
+}
+return { samples };
+```
+
+Returning both is an error, as is returning neither. A property present on some
+samples and absent from others is an error rather than a hole — interpolating
+across the gap would invent motion nobody wrote. A sample needs a finite numeric
+`t`; `easing` on a sample is optional and applies to the segment ending there.
+At most 4096 samples.
+
+Because the bake runs once, a body using `Math.random` is frozen at the value it
+drew: the result is stable forever after, but re-baking gives different motion.
+Seed your own generator when the same body has to produce the same wiggle twice.
+
+## Recipes
+
+**Overshoot and settle.** Two overshoots, the second smaller — what a single
+`easeOutBack` cannot express.
+
+```js
+const p = [[0, 0.6], [0.45, 1.09], [0.68, 0.97], [0.85, 1.02], [1, 1]];
+return { curves: [{ property: "scale",
+  keyframes: p.map(([t, value]) => ({ t, value, easing: "easeInOut" })) }] };
+```
+
+**Decaying bounce.** Hops that die out and land exactly at rest.
+
+```js
+const n = inputs.sampleCount, h = 0.06 * inputs.canvasHeight, hops = 3;
+const samples = [];
+for (let i = 0; i < n; i++) {
+  const t = i / (n - 1);
+  samples.push({ t, offsetY: -h * Math.abs(Math.sin(Math.PI * hops * t)) * (1 - t) });
+}
+return { samples };
+```
+
+**Anticipation.** A counter-move before the action, 60–120ms of the window.
+
+```js
+return { curves: [{ property: "offsetY", keyframes: [
+  { t: 0, value: 0 }, { t: 0.18, value: 10, easing: "easeInOut" },
+  { t: 0.8, value: -4, easing: "easeOut" }, { t: 1, value: 0 }] }] };
+```
+
+**Shaped wiggle.** For a steady seeded wiggle, use a stored
+`animationLinks` entry with `kind: "wiggle"` as described in
+`timeline-edit-ops` § Document motion fields. Bake a curve when its amplitude must fade in or out. This
+seeded generator reproduces the same shape on a re-bake.
+
+```js
+const n = inputs.sampleCount;
+const amp = Number(inputs.params.amplitude ?? 6);
+let seed = Number(inputs.params.seed ?? 1);
+const rand = () => (seed = (seed * 1103515245 + 12345) % 2147483648) / 2147483648 - 0.5;
+const samples = [];
+for (let i = 0; i < n; i++) {
+  const t = i / (n - 1);
+  const fade = Math.min(1, 4 * t, 4 * (1 - t));   // rest at both ends
+  samples.push({ t, offsetX: rand() * amp * fade, offsetY: rand() * amp * fade });
+}
+return { samples };
+```
+
+**Inertia.** A trailing part that lags the body and catches up — follow-through
+without a second clip.
+
+```js
+const n = inputs.sampleCount, lag = 0.12;
+const ease = (t) => 1 - Math.pow(1 - t, 3);
+const samples = [];
+for (let i = 0; i < n; i++) {
+  const t = i / (n - 1);
+  const behind = ease(Math.max(0, t - lag) / (1 - lag));
+  samples.push({ t, offsetX: (1 - behind) * -0.1 * inputs.canvasWidth });
+}
+return { samples };
+```
+
+**Arc.** Straight-line travel looks mechanical. Drive one axis linearly and the
+other as a shallow parabola over the same window; both fold as `add`.
+
+```js
+const n = inputs.sampleCount;
+const dx = 0.25 * inputs.canvasWidth, rise = 0.06 * inputs.canvasHeight;
+const samples = [];
+for (let i = 0; i < n; i++) {
+  const t = i / (n - 1);
+  samples.push({ t, offsetX: -dx * (1 - t), offsetY: -rise * 4 * t * (1 - t) });
+}
+return { samples };
+```
+
+**Pendulum.** A decaying rotation, in radians.
+
+```js
+const n = inputs.sampleCount, a = 0.12, cycles = 2.5;
+const samples = [];
+for (let i = 0; i < n; i++) {
+  const t = i / (n - 1);
+  samples.push({ t, rotation: a * Math.cos(2 * Math.PI * cycles * t) * (1 - t) });
+}
+return { samples };
+```
+
+**A loop with no visible join.** Any `loop` curve must return to its start, so
+build it from a whole number of cycles of a periodic function.
+
+```js
+const n = inputs.sampleCount, amp = 0.02 * inputs.canvasHeight;
+const samples = [];
+for (let i = 0; i < n; i++) {
+  const t = i / (n - 1);
+  samples.push({ t, offsetY: -amp * Math.sin(2 * Math.PI * t) });
+}
+return { samples };
+```
+
+**Path draw-on.** `trimEnd` 0 to 1 on a `path` shape clip. Both trim channels
+fold as `replace`, so one animation drives each and their windows must not
+overlap.
+
+```js
+return { curves: [{ property: "trimEnd",
+  keyframes: [{ t: 0, value: 0 }, { t: 1, value: 1, easing: "easeInOut" }] }] };
+```
+
+**Wipe with a shaped edge.** A `wipeProgress` curve needs the mask on the same
+animation, because direction and softness cannot be inferred:
+
+```json
+{"role": "in", "preset": "custom", "durationMs": 700,
+ "mask": {"direction": "left", "softness": 0.1},
+ "curves": [{"property": "wipeProgress", "keyframes": [
+   {"t": 0, "value": 0}, {"t": 0.6, "value": 0.8, "easing": "easeOut"},
+   {"t": 1, "value": 1}]}]}
+```
+
+## Failure modes
+
+- A body returning nothing, or both shapes, fails the bake with the reason. Read
+  it: the bake returns the error and the body's logs rather than throwing.
+- A property name outside the channel list fails the bake and names the ones it
+  will take.
+- A curve driving `wipeProgress` with no `mask` is refused.
+- An easing string the grammar cannot read eases linearly and shows up as
+  `unknown_easing` on `validate_timeline`. It is `easeOut`, not `ease-out`.
+- A window that does not fit the clip after its delay is `animation_exceeds_clip`
+  — the motion is clamped or never runs.
+- A runaway loop hits the 10-second ceiling. A curve generator is arithmetic over
+  a few hundred points; if it is slow, it is wrong.
+
+## Check the shape you wrote
+
+Curves are the one place where reading the numbers is not enough. Use
+`preview_timeline_frame` with a `range` across the animation's window and
+`sheet: true`, which tiles the sweep into one labelled contact sheet — the way
+to watch an overshoot actually overshoot rather than checking three instants
+that all happen to look right.