Project Schema

Canonical envelope

A stored or exported project is canonical version 3. Its durable concerns are:

• title and project-level settings;
• cast definitions and optional voice configuration;
• typed variables and resolved parameter bindings;
• reusable media metadata;
• ordered scenes with duration, background, instances, narration, and audio clips;
• actor transforms and bounded transform keyframes. (engine.js:5-18, SVG-Animator-BIBLE.md:148-157)

The engine caps projects at 12 scenes, 32 cast members, 16 instances per bounded context, 64 variables, 64 media entries, 32 keyframes, and 32 audio clips. The canonical stage is 1600 by 900. Treat these source constants—not UI affordances—as the bounds authority. (engine.js:9-18)

Input and migration

parseProjectFile bounds text parsing, migrates v1/v2 input, and returns { project, warnings }. compileRuntimeProject then performs the one canonical validation/default/repair path and returns an immutable runtime. Never preserve malformed fields by adding a UI-side alternate schema. (docs/ARCHITECTURE.md:18-26, SVG-Animator-BIBLE.md:131-146)

Timeline semantics

Scenes form the global timeline. Evaluation maps global time into the active scene and calculates actor transforms, movements, variables, and visible scene state. Base transform, keyframed transform, evaluated value, and variable binding are distinct authoring concepts. Keyframe insertion at non-zero time begins from the evaluated pose. (SVG-Animator-BIBLE.md:148-157, tests/engine-v3-evaluator.test.js:1-80)

Serialization and export

Canonical serialization persists project data; it does not persist compiled runtime objects, UI state, provider capability state, or cached binary blobs. Standalone SVG export consumes canonical compiled visual truth, resolves visual assets, and omits all audio items. (SVG-Animator-BIBLE.md:159-165, docs/ARCHITECTURE.md:48-59)