DefinedMotion v0.4.0

This new version makes agentic scene development a first-class workflow. Coding agents can build scenes, inspect exact frames and scene state, find visual problems, and verify the result through documented tools. This allows them to converge into good results with feedback instead of building blind.

The release also comes with significant general improvements. It includes a simpler animation API, flex, grid, and relative layout tools, scene selection in the viewer, and video support. Text and LaTeX measurement is more stable with more polished primitives, and generated projects are now smaller and cleanly separated from the framework.

A more structured animation API

The animation API is now centered on a function called bind(). Built-in and custom animations capture their starting values when the animation begins, rather than when the scene is built. This replaces the earlier split between regular and deferred animations with one simpler API.

// Before
scene.addAnims() // Build-time values
scene.addDeferredAnims() // Runtime values, required a factory function
scene.addSequentialBackgroundAnims() // Sequential animations without moving timeline pointer
scene.insertAnimsAt() // Animations at a chosen frame
scene.do() // Action at the current frame
scene.doAt() // Action at a chosen frame
scene.onEachTick() // Callback on every frame

// Now
scene.addAnims() // Runtime values through bind()
scene.do() // Action at the current frame
scene.onEachTick() // Callback on every frame
scene.getTimelinePointer() // Read the current frame
scene.setTimelinePointer() // Move to frame

The new system removes much of the complexity of build time values versus run time values. DefinedMotion still builds the entire animation plan in advance, but it now schedules animations that capture state at animation start with bind().

Scenes can now also define named timeline beats. Beats describe validated, non-overlapping windows on the global timeline and provide beat-local frame, time, and progress values. This makes it easier to organize editorial phases without replacing the ordinary scene timeline.

Layout and visual tools

Text and LaTeX were already important parts of DefinedMotion. This release gives them stronger primitives. They now provide unified features and can be measured to work in a new layout system.

New and expanded visual tools include:

• Flex and grid layouts
• Relative positioning and layout-owned surfaces
• More stable text and LaTeX measurement
• Curve primitives
• Camera-attached UI helpers
• A cleaned up and focused set of built-in effects

Inspect and verify scenes from the CLI

Version 0.4.0 adds an automation CLI for inspecting and validating scenes outside the viewer. You can use it to:

• Discover the scenes available in a project
• Render exact still images
• Generate image grids that show how a scene changes over time or looks from different cameras
• Inspect objects, transforms, bounds, and scene state
• Find layout collisions across the full timeline
• Run verification rules defined by a scene
• Keep a persistent runtime session open for faster repeated checks
• Render final videos with progress reporting

These commands make it possible to review timing, composition, and authored checks while a scene is being built. They are useful for manual development, coding-agent workflows, and CI.

Viewer workflow

The viewer keeps the existing live preview and timeline workflow, but it can now switch between project scenes, examples, and test scenes.

The viewer also includes an optional FPS monitor with frame timing and information about timeline frames that were not presented.

Video, audio, and rendering

• Video support is new. Scenes can place video planes on the timeline and optionally include their embedded audio.
• Audio mixing handles larger projects more efficiently.
• Full-resolution viewport frames can be saved directly.
• Invalid video dimensions are rejected before rendering starts.
• Multiple requests sent to a persistent rendering session are queued and rendered one at a time.

Packages, documentation, and examples

DefinedMotion is now organized as a runtime package and a separate create-definedmotion project generator. New projects stay small and keep their scenes and assets separate from the installed framework.

The package now includes published TypeScript declarations, documented public entry points, canonical guides, curated examples, and a version-matched reference collection. These files ship with the package so the documentation and examples match the installed version.

Breaking changes

• Legacy authoring APIs have been removed. Use the documented scene, animation, layout, and rendering APIs instead.
• Import from the documented public entry points only. These are definedmotion, definedmotion/animation, definedmotion/assets, definedmotion/latex, definedmotion/math, definedmotion/media, definedmotion/reference, and definedmotion/rendering.
• DefinedMotion and newly generated projects now require Node.js 24.11 or newer.

Getting started

Create a new project:

npx create-definedmotion@0.4.0 my-animation
cd my-animation
npm install
npm run dev

Updating existing projects

From a 0.4.0 alpha

npm install definedmotion@0.4.0

From 0.3.1 or earlier

Projects generated by earlier releases bundled DefinedMotion's framework source directly and cannot be upgraded by installing the new runtime package alone. Create a fresh 0.4.0 project, then migrate your scenes and assets into it:

npx create-definedmotion@0.4.0 my-animation-v040

Scenes written against the earlier authoring model must also be updated to use the documented public imports and current animation, layout, and rendering APIs. In particular, migrate uses of the legacy APIs listed above rather than copying the old framework or project configuration into the new project.