Common element fields#

Every element type — text, shape, image, video, audio, group, caption, particles — shares the fields on this page. Variant-specific fields live on each element's own reference page.

interface BaseElement {
  id?: string;
  name?: string;
  type: ElementType;
  layer: number;          "tok-cmt">// required, unique per container
  visible?: boolean;
  time?: number | string;
  duration?: number | string | "tok-str">'auto' | "tok-str">'end';

  "tok-cmt">// Transform (2D)
  x?: number | string | Keyframe[] | Expr;
  y?: number | string | Keyframe[] | Expr;
  x_anchor?: number | string;
  y_anchor?: number | string;
  width?: number | string | Keyframe[] | Expr;
  height?: number | string | Keyframe[] | Expr;
  aspect_ratio?: number;
  rotation?: number | Keyframe[] | Expr;   "tok-cmt">// alias: z_rotation (same slot)
  scale?: number | Keyframe[] | Expr;

  "tok-cmt">// Transform (3D — only meaningful under a camera)
  z?: number | Keyframe[] | Expr;
  x_rotation?: number | Keyframe[] | Expr;
  y_rotation?: number | Keyframe[] | Expr;
  x_scale?: number | string | Keyframe[] | Expr;
  y_scale?: number | string | Keyframe[] | Expr;
  x_skew?: number | Keyframe[] | Expr;
  y_skew?: number | Keyframe[] | Expr;

  "tok-cmt">// Visual
  opacity?: number | Keyframe[] | Expr;
  blend_mode?: "tok-str">'normal' | "tok-str">'multiply' | "tok-str">'screen' | "tok-str">'add' | "tok-str">'overlay' | "tok-str">'hard-light' | "tok-str">'soft-light';

  "tok-cmt">// Filters
  blur_radius?: number | Keyframe[] | Expr;
  brightness?: number | Keyframe[] | Expr;
  contrast?: number | Keyframe[] | Expr;
  saturation?: number | Keyframe[] | Expr;
  hue_rotate?: number | Keyframe[] | Expr;

  "tok-cmt">// Effects & material
  effects?: Effect[];
  material?: Material;

  "tok-cmt">// Animation
  animations?: Animation[];
  keyframe_animations?: KeyframeAnimation[];
}

Identity#

Timing#

Generated sets#

Image, text, shape and group elements. One grid, chart, step sequence, slideshow or word sequence is one element (PROTOCOL §3.7).

Transform#

Positions use the top-left convention by default (the CSS / SVG / Canvas model): (x, y) is where the element's anchor lands on the canvas, and the anchor defaults to the element's top-left corner unless x_anchor / y_anchor say otherwise. So x: 0, y: 0 is the top-left corner and a full-frame layer is just x: 0, y: 0, width: W, height: H. Set x_anchor: '50%', y_anchor: '50%' to position by center. Rotation and scale always pivot the element's center, independent of the anchor.

3D transform#

These only have a visible effect under a Source camera (see PROTOCOL.md §4.4); otherwise they default to identity.

Visual#

Filters#

Per-element color/blur filters. brightness/contrast/saturation are multipliers (not percentages): 1 = unchanged, 0 = removed, 2 = double.

Effects & material#

Animation#

animations#

Named animation presets. Declarative — each one is a tag the runtime expands into a keyframe sequence. AI agents and humans both pick from this list; you don't write the curves yourself.

interface Animation {
  type: AnimationType;                          "tok-cmt">// required
  duration?: number;
  easing?: EasingFunction;
  split?: "tok-str">'letter' | "tok-str">'word';                    "tok-cmt">// text presets only
  stagger?: number;
  time?: "tok-str">'start' | "tok-str">'end' | number;
  frequency?: number;
  rotation?: number;
  distance?: number;
  direction?: "tok-str">'left' | "tok-str">'right' | "tok-str">'up' | "tok-str">'down';
  scale?: number;
  seed?: number;
  axis?: "tok-str">'x' | "tok-str">'y' | "tok-str">'z';
}

Preset names#

All 31 presets:

fade-in, fade-out, slide-left-in, slide-right-in, slide-up-in, slide-down-in, slide-left-out, slide-right-out, slide-up-out, slide-down-out, scale-in, scale-out, rotate-in, rotate-out, bounce-in, bounce-out, spin, shake, wiggle, squash, pan, shift, drift, breathe, orbit, text-appear, text-slide, text-fly, text-typewriter, text-wave, text-flip.

Example#

"animations": [
  { "type": "fade-in", "duration": 0.6 },
  { "type": "slide-up-in", "duration": 0.6, "easing": "ease-out-cubic" },
  { "type": "fade-out", "duration": 0.4, "time": "end" }
]

keyframe_animations#

Raw keyframe animation on any property. Use this when no preset fits — explicit position curves, color shifts, scale ramps tied to specific times.

interface KeyframeAnimation {
  property: string;
  keyframes: Keyframe[];                  "tok-cmt">// at least one
  easing?: EasingFunction;
  auto_orient?: boolean;                  "tok-cmt">// "tok-str">'position' paths only
  loop?: boolean | "tok-str">'ping-pong';
}

interface Keyframe {
  time: number | string;
  value: number | string | [number, number] | [number, number, number];
  easing?: EasingFunction;
}

Example#

"keyframe_animations": [
  {
    "property": "y",
    "keyframes": [
      { "time": 0,   "value": 200, "easing": "ease-out-cubic" },
      { "time": 1.5, "value": 540 }
    ]
  }
]

Expressions#

Any numeric field above (x, y, width, height, rotation, scale, opacity, blur/filter params, effect params) also accepts an expression object — a formula evaluated per frame, instead of a static value or a keyframe table:

{ "y": { "expr": "540 + sin(t * PI) * 30" } }

The formula is a pure function of the element's own clock: t (element-local seconds), dur, i (index in a generated set), n (siblings), value (the field's base default), the constants PI/TAU/E, and a fixed math function set (sin, cos, clamp, lerp, smoothstep, linear, ease, noise, wiggle, random, …). It cannot reference other elements or read runtime input, so it is deterministic and can be baked to keyframes. Full grammar: PROTOCOL.md §3.6.

Easing functions#

36 named easings plus 2 parametric forms.

linear, ease, ease-in, ease-out, ease-in-out, ease-in-cubic, ease-out-cubic, ease-in-out-cubic, ease-in-quad, ease-out-quad, ease-in-out-quad, ease-in-quart, ease-out-quart, ease-in-out-quart, ease-in-quint, ease-out-quint, ease-in-out-quint, ease-in-sine, ease-out-sine, ease-in-out-sine, ease-in-expo, ease-out-expo, ease-in-out-expo, ease-in-circ, ease-out-circ, ease-in-out-circ, ease-in-back, ease-out-back, ease-in-out-back, spring (damped harmonic with mass=1, damping=10, stiffness=100 — overshoots ~5% then settles), elastic-in, elastic-out, elastic-in-out, bounce-in, bounce-out, bounce-in-out.

Two parametric forms are also accepted as strings:

• cubic-bezier(x1, y1, x2, y2) — a custom Bézier curve.
• steps(n) — n discrete steps (positive integer).