motion-state

Motion State

The layer that turns a motion project into data the agent can see and edit.

Today, the agent's only window into a project is scene.js — strings of GSAP calls it has to read, parse, and rewrite. That is not a chatcut loop; that is "edit source code with chat." This skill replaces it with a queryable, mutable state.

Target agent

This skill is not a general-purpose animation tool. It is the data backbone for agents that already possess — or are paired with — strong frontend aesthetics or multimodal design capability. The state layer stores timing and primitive choices; it does not make design decisions for you. Selecting the right primitive, dialing motionIntensity, choosing args.direction / args.stagger, and locking a single accent all require design judgment that this skill assumes you have.

If the agent lacks aesthetic direction, do not use this skill in isolation. Instead:

• Load the design-layer skills first (motion-design-taste, motion-recipes, motion-anti-slop) to establish the motion mode, aesthetic family, and anti-slop guardrails.
• Use the /motion-craft commands (/init, /shape, /animate) which orchestrate the design-to-state pipeline.
• Only then write state.json and let scripts/state-to-scene.mjs generate the scene.js.

The contract

Every /studio project carries a state.json at its root:

{
  "schemaVersion": 1,
  "duration": 8.0, "fps": 30, "width": 1080, "height": 1920,
  "accent": "#FF5A1F",
  "layers": [
    { "id": "headline", "selector": ".headline", "type": "text", "content": "Hello" }
  ],
  "beats": [
    { "id": "b1", "layerId": "headline", "primitive": "splitReveal",
      "at": 0.4, "duration": 0.9, "args": { "direction": "up", "stagger": 0.06 } }
  ],
  "assets": []
}

This file is the source of truth. scene.js is generated from it (node scripts/state-to-scene.mjs). render.mjs reads duration / fps / width / height from it.

Runtime

skills/motion-state/runtime.mjs exports: