Sandbox Timeline

Timelines as code

Specifier: @nodetool-ai/sandbox-timeline. One module. It builds a whole timeline document in plain JavaScript and saves it through nodetool.timelines, so a cut with hundreds of keyframed clips costs a handful of API calls instead of one edit op per clip. NodeTool's shipped example timelines (Cadence, Kite, Prism, Voltra, Tidewater, T minus 30) are built with it.

Use it for authored motion graphics: kinetic type, shapes, charts, placed stills, transitions between scenes. For a few changes to a cut that already exists, nodetool.timelines.edit(id, ops) is still the better tool.

Units are seconds, everywhere, local to the scope that created them. A scene's own clock starts at 0. There is no absolute-time option — v.series() is the only place a scene's position in the whole video is decided, and it is the only function that ever shifts a time. Author a moment once, at the time it happens in its own scene, and it is correct wherever that scene lands.

A two-scene piece

import { video } from "@nodetool-ai/sandbox-timeline";

const v = video({
  width: 1920, height: 1080, fps: 30,
  palette: { ink: "#06110e", ink2: "#0c2a21", text: "#f4fbf8", accent: "#34d399" },
  fonts: { display: "Space Grotesk", body: "Inter" }
});

const hello = v.scene("Hello", 2.5, (s) => {
  s.backdrop();
  const title = s.text("Hello, timeline", { size: 120, weight: 700, font: "display" });
  const sub = s.text("built from code", { size: 40, color: "#8fb3a6" });
  s.stack([title, sub], { gap: 20 });
  title.enter({ from: { scale: 1.2, opacity: 0 }, at: 0, dur: 0.3, ease: "outExpo" });
  sub.enter({ from: { offsetY: 24, opacity: 0 }, at: 0.15, dur: 0.25 });
  title.exit({ to: { opacity: 0 }, dur: 0.2 });
});

const outro = v.scene("Outro", 1.5, (s) => {
  s.backdrop({ colors: ["#0f3b2e", "#06110e"] });
  const cta = s.pill("Try it", { fillColor: "#f4fbf8", color: "#06110e" });
  cta.enter({ from: { scale: 0.6, opacity: 0 }, dur: 0.25 });
});

v.series([hello, v.transition("wipe", 0.3, { direction: "left" }), outro]);
v.adjust([{ type: "vignette", amount: 0.2 }], { name: "finish", trackId: "t_finish" });

const saved = await v.save(nodetool.timelines, { name: "Hello", showcase: true });
await output("timeline", saved);   // { timeline_id, errors, warnings }

Then look at it: nodetool.timelines.preview(saved.timeline_id, {count: 3}) returns composited frames, and render(id, {preview_scale: 0.5}) a draft video.

Study a reference and reuse scene helpers

nodetool.timelines.examples.list() lists shipped cuts with structural stats. nodetool.timelines.examples.get("kite", {clip_limit: 12}) returns its scene catalog and a bounded scene excerpt. Select another scene_id or page with clip_offset to read more layers. Inspect the clip hierarchy, curve windows and effects before choosing your own scene structure.

nodetool.timelines.examples.source("kite") returns the script that made that excerpt: full JavaScript, imports included.

video({width, height, fps, palette, fonts})

The entry point. palette supplies colours the craft helpers fall back to: ink, ink2, text, dim, accent. fonts maps short keys (display, body) to real family names; a text element's font option takes either a key or a literal family string.

Scenes and series

v.scene(name, seconds, fn) builds one scene at its own local clock, fn(s) receiving the scene's authoring object. It returns a scene descriptor — nothing is placed in the document yet.

v.series([scene, transition?, scene, transition?, scene, ...]) lays scenes end to end and assigns every clip's absolute position. A v.transition(type, seconds, opts) item between two scenes overlaps them by its own duration and sets transitionIn on the incoming scene's group; omitting one between a pair makes a hard cut. type is one of the document's transition types ("wipe", "whip", "iris", "gradientWipe", "crossfade", "push", "slide", "zoom", "zoomBlur", "glitch", "dipToColor", "lightLeak"); opts carries that type's own fields (direction, easing, color, softness, map, seed, …). Scenes are banked onto two alternating track sets so an overlapping pair never shares a track — you never see or name a track.

v.series must run before v.adjust, v.document or v.save.

Local time nests

Everything inside a scene builder is measured from that scene's own start. s.seq(atSec, durSec, fn) opens a nested local clock: fn(q) receives a scoped authoring object whose own atSec/durationSec for elements and motion are relative to atSec inside the enclosing scope, not to the whole video. Nest as deep as you like — the shift out to absolute time happens once, in v.series().

// fragment
v.scene("Beat", 4, (s) => {
  s.seq(1.2, 1.0, (q) => {
    const chip = q.text("+$0.60", {});
    chip.enter({ from: { offsetY: 20, opacity: 0 }, at: 0, dur: 0.2 }); // 1.2s into the scene
  });
});

Elements

Every element is a scene method returning a clip object with motion methods attached. at/dur (seconds, defaulting to the whole enclosing scope) narrow where in that scope the clip lives; everything else is the clip's own fields.

x/y are px from the frame centre, or from the parent's own position when the clip is reparented into a group. rotation (degrees) and anchor ({x, y} pivot fraction, default {0.5, 0.5}) are friendly options for the two transform fields authored most; tx: {extra fields} is the raw escape hatch for the rest (rotationX/rotationY, perspective, depthPx, …), and a full transform: {position, scale, rotation, anchor, depthPx, ...} override still works when nothing else fits. Every element option also takes clip fields as-is: effects (an id/enabled: true an entry leaves out is filled in — write {type: "glow", radius: 30, ...}, not {id: "...", enabled: true, type: "glow", ...}), opacity, blendMode, mask (a static crop mask — ClipMask, {kind: "rect"|..., ...} — not the wipe mask enter()/animate() take, below), matte, crop, motionBlur, steppedTime, repeater, inPointMs, outPointMs, speedBaked, fadeInShape, fadeOutShape. There is no field a clip carries that needs mutating after creation — anything video/audio/text don't name a friendly option for still passes through by its own document field name.

Layout containers

s.stack(children, o) and s.row(children, o) build a real CSS/Yoga flex container (layout: {display: "flex", flexDirection: "column" | "row", gap, alignItems, justifyContent, padding, width, height}) and reparent children onto it (child.parentId = container.id) — real nesting, not a sibling list. Nest freely: a container can be a child of another container (a row of stacks, a stack holding a nested row), and the renderer's Yoga resolver lays out the whole tree.

The container's own placement in the frame is o.at ({x, y}, default the frame centre) plus o.anchor (default "center"). at is canvas-centre-relative — the same coordinate space every clip's own position already is: {x: 0, y: 0} is frame centre, negative x is left of centre, negative y is above it. anchor names the point of the container's own computed box that lands at at — {x: 0, y: 0.5} or the name "left" put that box's left edge at at.x, no measuring a sibling's width required. Example: on a 1920-wide frame, anchor: "left" with at: {x: -860, y: -212} puts that left edge near the frame's own left margin (-860 is 960px left of centre, i.e. near x=100 on screen); at: {x: 110, ...} would instead land it just right of centre. Named anchors: "top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right", or pass {x, y} fractions directly. A container's own time window is o.start/ o.dur (seconds) — the one place in this API at doesn't mean seconds, because the container's placement already claims it.

o.gap (px), o.padding (px, or {top, right, bottom, left}), o.width/ o.height (px or "N%") size the container. o.parent nests it inside another clip (e.g. a phone mockup) instead of the scene root. o.wrap turns on flexWrap.

o.align is "start" (default), "center", "end", "stretch" or "baseline" — the cross axis (alignItems): a row's shared y, a stack's shared x. o.justify is "start", "center", "end", "between", "around" or "evenly" — the main axis (justifyContent), unset by default (children pack at the start with the authored gap). A stack/row call with an unknown align/justify throws, naming the value.

A child's own flex sizing/placement is o.flexItem on that child's own call (grow, shrink, basis, alignSelf, width, height, margin, position: "absolute", inset) — pass it through any element's own options, e.g. s.rect(..., { flexItem: { grow: 1 } }). s.rect/s.ellipse also take absolute: true as sugar for flexItem: {position: "absolute", inset: 0} — taken out of flow and resized to fill its flex parent's box exactly, which is how a pill's plate or a card's backdrop sits behind its content: create the background before the foreground children (so its _z draws below), then reparent it onto the container.

A leaf's flex-measured size is its own content, never a guessed line height — a text child reflows to whatever width Yoga offers, and a text's own mw does nothing once it sits inside a stack/row: its width comes from the container, not from itself, so don't pass mw to a text child of a container — leave it unset there. mw still matters on a standalone text (one placed directly with at/x/y, no enclosing container); a shape/ellipse's size is its own shapeStyle.width/height (unset defaults to 0, not the frame, so an undecorated plate doesn't force its siblings into a shrink negotiation); a plain (non-flex) group nested as a leaf measures as its children's own union box — give a plain group wrapping e.g. an icon + a drawn path (each a leaf with its own small authored size) an explicit flexItem: {width, height} when any of its children is a bare path() (no authored shapeStyle.width/ height of its own — path() never sets one), since that child's un-measured intrinsic size falls back to the whole frame and the group would measure as canvas-sized.

s.center(child, o) repositions child directly at o.at (default the frame centre) — for a single element, no container needed.

Motion primitives

All local to the clip's own start (at: 0 is the moment the clip appears), unless stagger() set a default at for it.

enter/animate/count/tween take by ("word"/"character"/"line") and staggerMs to stagger across the units of one text clip — a headline that rises in word by word, a wordmark that types in letter by letter. A glyph.* tween() target needs a stagger — the document validator refuses one without a unit, since animating per-glyph style with no split is the un-staggered block case enter/animate already cover. tween() left with no by of its own inherits the stagger of the last enter()/animate() call on the same clip, so a glyph.color tween riding the same word-by-word reveal as its enter() needs no repeated by:

// fragment
const title = s.text("Every purchase", { anchor: "left" });
title.enter({ from: { offsetY: 40, opacity: 0 }, by: "word", staggerMs: 90 });
title.tween("glyph.color", [[0, "#8fb3a6"], [1, "#f4fbf8"]]); // inherits by: "word"

A wipeProgress animation needs mask: {direction, softness} — a wipe reveal has nowhere else to say which edge it sweeps from. Pass it on the same enter()/animate() call that drives wipeProgress, not as a follow-up mutation:

// fragment
area.animate({ wipeProgress: [0, 1] }, { at: 0.4, dur: 1.3, mask: { direction: "left", softness: 0.02 } });

s.stagger(items, offsetSec, fn) offsets several already-created elements' default motion at by index * offsetSec, then calls fn(item, index):

// fragment
const words = ["Round-ups", "on", "every", "card"].map((w) => s.text(w, { anchor: "left" }));
s.stagger(words, 0.06, (w) => w.enter({ from: { offsetY: 40, opacity: 0 } }));

ease names: "in", "out", "inOut", "outExpo", "inExpo", "linear", or a raw curve string such as "spring(170,16,1)" or "cubic-bezier(0.65,0,0.35,1)".

Craft

Scene methods for the recurring structural moves. Every helper takes seconds and px like everything else, and every option has a default, so s.backdrop() alone renders a full bleed. palette supplies the colours a call does not override.

s.backdrop({colors: [a, b]}) uses a twice — as the solid base rect underneath, and as the first stop of the animated gradientField wash on top of it. There is no separate base colour: pass colors: [a, b] to mean "base and wash both start at a, wash drifts toward b", not "a solid a behind a b-to-something wash".

A slam, a rise, or a grow are el.enter()/el.animate() calls with the right from/props — there is no separate name for them:

// fragment
title.enter({ from: { scale: 1.35, blur: 26, opacity: 0 }, dur: 0.27, ease: "outExpo" }); // slam
sub.enter({ from: { offsetY: 24, opacity: 0 }, dur: 0.3 });                                     // rise
bar.animate({ scaleY: [0, 1], offsetY: [h / 2, 0] }, { dur: 0.4, ease: "out" });           // grow from its base

Components

component(name, {props, duration}, (s, props) => {...}) — a reusable piece (a lower third, a stat card, a CTA end card) with typed props, used inside a scene with s.use(Comp, {...props}, {at, dur}). props maps a name to {type: "string"|"number"|"color"|"boolean", default, description?}; duration (seconds) is the piece's own natural length, used when use() gets no dur. build(s, props) is a scene builder exactly like scene()'s own — it adds clips with s.text/s.rect/craft helpers/nested use() the usual way; use() folds everything the build left at the enclosing scope into one group, the way pill() folds its own dot+label+plate.

// fragment
const Badge = component("Badge", {
  props: {
    label: { type: "string", default: "New" },
    tone: { type: "color", default: "#34d399" }
  },
  duration: 1
}, (s, p) => {
  s.pill(p.label, { fillColor: p.tone });
});

v.scene("Hero", 3, (s) => {
  s.use(Badge, { label: "Live now" }, { at: 0.5 });
});

use() checks propsIn against Comp.props and fills defaults, throwing and naming the offending prop on a type mismatch or an unknown name — the same failure a bad caret/align value gets from the type declarations below.

Saving a component as a composition

Comp.saveAsComposition(nodetool.timelines, {width, height, fps, palette?, fonts?, name?, description?}) bridges a component into the editor's composition system (list_compositions/get_composition/ insert_composition): it builds Comp at its prop defaults into a scratch timeline, then rebuilds it once per prop with a value distinct from that default and diffs the two builds to find the one JSON pointer (packages/timeline/src/composition.ts's path) that prop reaches — the same field a hand-written save_composition call would have to name. It requires {width, height, fps} because a bare component() descriptor carries none of its own; a call with no matching field found (unused, reaching more than one field, or the prop only toggles whether a field exists at all rather than setting its value) leaves that prop out of the saved composition and lists it in skippedParams rather than saving a pointer that would write the wrong thing.

A nested stack/row inside a component round-trips too. A composition captures the group's whole descendant subtree, not just its direct children, so a card holding a row of icons saves and re-inserts with the row's own children intact and correctly nested. saveAsComposition's prop probing walks the same subtree, so a prop reaching into a nested container's field still gets a pointer — only a prop with no single-field effect (unused, structural, or toggling whether a field exists rather than setting it) ends up in skippedParams.

Charts

Motion graphics are often data. Every chart is built from the same shapes and text everything else uses — bars, a line, a filled area, a ring — with growth, staggering, and a value that counts up baked in, so it composes with s.stack/s.row/parenting like any other element. Each returns {group, ...pieces}: move/parent group like any other clip; the pieces (bars, line, segments, …) are the real shapes and labels for anything you want to touch individually.

// fragment
s.barChart([420, 680, 1150], { at: 0.2, stagger: 0.08, highlight: 2, format: { prefix: "$" } });
s.donut([{ value: 62, label: "Rent" }, { value: 38, label: "Everything else" }], { highlight: 0 });