Temporal Composition

ef-timegroup implements temporal composition: a declarative system where parent-child relationships automatically compute precise timing for every element in a video timeline. This architecture eliminates manual timeline calculations and provides automatic updates when any part of the composition changes.

The problem with manual timeline arrangement

Using imperative position calculation presents several engineering challenges:

• Manual start-time calculation. Changing one element's duration requires recalculating all subsequent positions. Complex nested timelines require extensive manual math.
• Fragile updates. Code like item2.startTime = item1.endTime creates tight coupling — one change requires updates in multiple places, and timing errors are hard to find.
• No automatic propagation. There is no guarantee that downstream elements stay in sync when an upstream duration changes.

The declarative solution

Timegroups replace imperative position math with four composition modes:

Mode	Duration rule
fixed	Explicit duration you set directly
sequence	Sum of children (serial playback)
contain	Longest child duration (parallel playback)
fit	Inherited from parent

These compose. A contain parent with a sequence child and a fit background is a common pattern: the sequence computes its own total, the contain adopts it, and the fit background spans the whole thing automatically.

Changing Item 1's duration from 2s to 5s automatically shifts Item 2's start time and updates the total from 5s to 8s — no other code changes needed.

---