Web Animations

1. Introduction

2. Web Animations model overview

This section is non-normative

At a glance, the Web Animations model consists of two largely independent pieces, a timing model and an animation model. The role of these pieces is as follows:

Timing model

Takes a moment in time and converts it to a proportional distance within a single iteration of an animation called the iteration progress. The iteration index is also recorded since some animations vary each time they repeat.

Animation model

Takes the iteration progress values and iteration indices produced by the timing model and converts them into a series of values to apply to the target properties and attributes.

Graphically, this flow can be represented as follows:

Overview of the operation of the Web Animations model.
The current time is input to the timing model which produces an iteration progress value and an iteration index.
These parameters are used as input to the animation model which produces the values to apply.

For example, consider an animation that:

• starts after 3 seconds

• runs twice,

• takes 2 seconds every time, and

• changes the width of a rectangle from 50 pixels to 100 pixels.

The first three points apply to the timing model. At a time of 6 seconds, it will calculate that the animation should be half-way through its second iteration and produces the result 0.5. The animation model then uses that information to calculate a width.

This specification begins with the timing model and then proceeds to the animation model.

3. Timing model

This section describes and defines the behavior of the Web Animations timing model.

3.1. The timing model at a glance

3.2. Timing model concepts

In Web Animations, timing is based on a hierarchy of time relationships between timing nodes. Parent nodes provide timing information to their child nodes in the form of time values. A time value#time-valueReferenced in:3.2. Timing model concepts (2) (3) (4) (5)3.3. The global clock (2) (3) (4)3.4. Timelines (2) (3) (4) (5) (6) (7)3.4.1. Document timelines3.4.2. The default document timeline (2) (3)3.5. Animations (2) (3)3.5.4. The current time of an animation (2)3.5.5. Setting the current time of an animation3.5.6. Setting the start time of an animation3.5.7. Waiting for the target effect3.5.10. Playing an animation3.5.14. Updating the finished state (2)3.5.15. Finishing an animation3.5.16. Canceling an animation3.5.17. Speed control (2)3.8.3. Iteration time space3.9.3.1. Calculating the active time (2) (3)3.9.3.2. Calculating the scaled active time3.11.5. Calculating the transformed time3.11.6. Calculating the iteration progress5.1. Time values in the programming interface5.2. The AnimationTimeline interface5.19. Model liveness (2)7. Interaction with page display (2) is a real number which nominally represents a number of milliseconds from some moment. The connection between time values and wall-clock milliseconds may be obscured by any number of transformations applied to the value as it passes through the time hierarchy.

In the future we may have timelines that are based on UI gestures in which case the connection between time values and milliseconds will be weakened even further.

A time value may also be unresolved#unresolvedReferenced in:3.4. Timelines (2)3.5. Animations (2)3.5.1. Setting the timeline of an animation3.5.2. Responding to a newly inactive timeline3.5.4. The current time of an animation (2) (3)3.5.5. Setting the current time of an animation (2) (3) (4) (5) (6) (7)3.5.6. Setting the start time of an animation (2) (3) (4) (5) (6) (7) (8) (9)3.5.7. Waiting for the target effect (2)3.5.10. Playing an animation (2) (3) (4) (5) (6) (7) (8)3.5.11. Pausing an animation (2) (3)3.5.14. Updating the finished state (2) (3) (4) (5) (6) (7) (8) (9)3.5.15. Finishing an animation (2) (3) (4)3.5.16. Canceling an animation (2) (3) (4)3.5.17.1. Updating the playback rate of an animation3.5.19. Play states (2) (3)3.5.20.2. Event parameters (2)3.6.4. Local time3.6.5. Animation effect phases and states (2) (3) (4) (5)3.7.1. Fill modes3.9.3.1. Calculating the active time (2) (3) (4)3.9.3.2. Calculating the scaled active time (2)3.9.3.3. Calculating the iteration time (2)3.9.4. Calculating the current iteration (2)3.10.1. Calculating the directed time (2)3.11.4. Timing in discrete steps3.11.5. Calculating the transformed time (2)3.11.6. Calculating the iteration progress (2)5.1. Time values in the programming interface5.9. The ComputedTimingProperties dictionary if, for example, a timing node is not in a state to produce a time value.

Periodically, the user agent will update the timing model in a process called sampling#samplingReferenced in:3.2. Timing model concepts3.4.2. The default document timeline3.5.14. Updating the finished state3.5.19. Play states4.1. Keyframe effects5.19. Model liveness (2) (3). On each sample#single-sampleReferenced in:3.4. Timelines the time values of each timing node are updated.

Further requirements on the frequency and sequencing of sampling are specified by HTML’s processing model [HTML].

Note: HTML currently refers to a “run CSS animations and send events” operation but this should be understood to include sampling all animations covered by this specification, not only CSS animations. Furthermore, the now parameter passed to this operation is ignored in this specification since we define a more general model that supports timelines whose time origin is not relative to navigationStart.

3.3. The global clock

At the root of the Web Animations timing hierarchy is the global clock.

The global clock#global-clockReferenced in:3.3. The global clock (2) (3) (4) (5) (6)3.4. Timelines (2) (3) (4) (5)3.4.1. Document timelines3.4.2. The default document timeline5.19. Model liveness7. Interaction with page display is a source of monotonically increasing time values unaffected by adjustments to the system clock. The time values produced by the global clock represent wall-clock milliseconds from an unspecified historical moment. Because the zero time of the global clock is not specified, the absolute values of the time values produced by the global clock are not significant, only their rate of change.

Note: The global clock is not exposed in the programming interface and nor is it expected to be exposed by markup. As a result the moment from which global clock time values are measured, that is, the zero time of the clock, is implementation-dependent. One user agent may measure the number of milliseconds since the the user agent was loaded whilst another may use the time when the device was started. Both approaches are acceptable and produce no observable difference in the output of the model.

3.4. Timelines

A timeline#timelineReferenced in:3.4. Timelines (2) (3)3.4.1. Document timelines3.5. Animations (2) (3) (4) (5) (6)3.5.1. Setting the timeline of an animation (2)3.5.2. Responding to a newly inactive timeline (2) (3)3.5.4. The current time of an animation (2) (3)3.5.5. Setting the current time of an animation (2) (3) (4) (5)3.5.6. Setting the start time of an animation (2)3.5.7. Waiting for the target effect3.5.10. Playing an animation3.5.14. Updating the finished state3.5.15. Finishing an animation (2)3.5.16. Canceling an animation3.5.17. Speed control (2) (3)3.5.18. Reversing an animation (2)3.5.20.2. Event parameters (2) (3)5.2. The AnimationTimeline interface5.4. The Animation interface (2) (3)5.19. Model liveness (2)7. Interaction with page display provides a source of time values for the purpose of synchronization.

Typically, a timeline is tied to the global clock such that its absolute time is calculated as a fixed offset from the time of the global clock. This offset is established by designating some moment as the timeline’s zero time#zero-timeReferenced in:3.4. Timelines3.4.1. Document timelines5.3. The DocumentTimeline interface and recording the time value of the global clock at that moment. At subsequent moments, the time value of the timeline is calculated as the difference between the current time value of the global clock and the value recorded as the zero time.

On each sample, the time value of the global clock at the beginning of the sample is recorded and this recorded value is used as the time value of the global clock until the next sample.

Note: We anticipate that other types of timelines may be introduced in the future that are not tied to the global clock. For example, a timeline whose time values are related to the progress of a UI gesture.

Since a timeline may be defined relative to a moment that has yet to occur, it may not always be able to return a meaningful time value, but only an unresolved time value. A timeline is considered to be inactive#inactive-timelineReferenced in:3.4.1. Document timelines (2)3.5.2. Responding to a newly inactive timeline (2)3.5.4. The current time of an animation3.5.5. Setting the current time of an animation (2)3.5.6. Setting the start time of an animation3.5.7. Waiting for the target effect3.5.14. Updating the finished state3.5.15. Finishing an animation3.5.18. Reversing an animation3.5.20.2. Event parameters5.2. The AnimationTimeline interface when its time value is unresolved.

3.4.1. Document timelines

A document timeline#document-timelineReferenced in:3.4.1. Document timelines (2) (3)3.4.2. The default document timeline (2) (3)5.3. The DocumentTimeline interface5.19. Model liveness is a type of timeline that is associated with a document.

The time values of a document timeline are calculated as a fixed offset from the global clock such that the zero time corresponds to the navigationStart moment [NAVIGATION-TIMING] plus a signed delta known as the origin time#origin-timeReferenced in:3.4.2. The default document timeline. Prior to establishing the navigationStart moment, the document timeline is inactive.

A document timeline that is associated with a document which is not an active document is also considered to be inactive.

3.4.2. The default document timeline

Each document has a document timeline called the default document timeline#default-document-timelineReferenced in:3.4.2. The default document timeline (2) (3)3.8.3. Iteration time space5.3. The DocumentTimeline interface5.4. The Animation interface5.14. The Animatable interface5.15. Extensions to the Document interface5.19. Model liveness. The default document timeline is unique to each document and persists for the lifetime of the document including calls to document.open() [HTML].

The default document timeline has an origin time of zero.

3.5. Animations

An animation#concept-animationReferenced in:3.5. Animations (2) (3) (4)3.5.1. Setting the timeline of an animation3.5.2. Responding to a newly inactive timeline (2) (3)3.5.3. Setting the target effect of an animation3.5.4. The current time of an animation3.5.6. Setting the start time of an animation3.5.7. Waiting for the target effect (2)3.5.9. The current ready promise3.5.11. Pausing an animation3.5.12. Reaching the end (2)3.5.14. Updating the finished state (2) (3) (4)3.5.16. Canceling an animation3.5.17. Speed control3.5.17.1. Updating the playback rate of an animation (2)3.5.18. Reversing an animation3.5.19. Play states (2)3.5.20. Animation events (2)3.5.20.1. Types of animation events3.5.20.2. Event parameters (2) (3) (4)3.6.1. Relationship between animation effects and animations (2) (3)3.6.3. The active interval (2)3.6.4. Local time3.9.1. Overview4.1.3.1. Not animatable4.3.1. Animation types4.3.2. The effect stack4.3.5.1. Applying the composited result to a CSS property (2)5.4. The Animation interface (2) (3)5.6. The AnimationEffectTimingReadOnly interface5.9. The ComputedTimingProperties dictionary5.14. The Animatable interface5.15. Extensions to the Document interface (2) connects a single animation effect, called its target effect#target-effectReferenced in:3.5. Animations (2)3.5.3. Setting the target effect of an animation (2) (3)3.5.4. The current time of an animation3.5.7. Waiting for the target effect3.5.10. Playing an animation3.5.11. Pausing an animation3.5.12. Reaching the end (2) (3) (4) (5)3.5.14. Updating the finished state (2) (3)3.5.16. Canceling an animation3.5.20. Animation events3.6.1. Relationship between animation effects and animations (2)3.8.4. Interval timing5.4. The Animation interface (2) (3) (4) (5) (6)5.14. The Animatable interface5.15. Extensions to the Document interface (2), to a timeline and provides playback control. Both of these associations are optional and configurable such that an animation may have no associated target effect or timeline at a given moment.

An animation’s start time#animation-start-timeReferenced in:3.5. Animations3.5.4. The current time of an animation (2)3.5.5. Setting the current time of an animation (2) (3) (4) (5) (6)3.5.6. Setting the start time of an animation (2) (3)3.5.7. Waiting for the target effect (2)3.5.10. Playing an animation (2) (3)3.5.11. Pausing an animation (2) (3) (4)3.5.14. Updating the finished state (2) (3)3.5.15. Finishing an animation (2) (3) (4)3.5.16. Canceling an animation3.5.19. Play states (2)3.6.3. The active interval (2) (3) (4)5.4. The Animation interface (2)5.6. The AnimationEffectTimingReadOnly interface5.9. The ComputedTimingProperties dictionary is the time value of its timeline when its target effect is scheduled to begin playback. An animation’s start time is initially unresolved.

An animation also maintains a hold time#hold-timeReferenced in:3.5. Animations3.5.4. The current time of an animation (2)3.5.5. Setting the current time of an animation (2) (3) (4)3.5.6. Setting the start time of an animation (2) (3) (4)3.5.10. Playing an animation (2) (3) (4) (5) (6) (7)3.5.11. Pausing an animation (2) (3) (4) (5) (6)3.5.14. Updating the finished state (2) (3) (4) (5) (6) (7) (8) (9)3.5.15. Finishing an animation (2)3.5.16. Canceling an animation10. Changes since last publication time value which is used to fix the animation’s output time value, called its current time, in circumstances such as pausing. The hold time is initially unresolved.

In order to establish the relative ordering of conflicting animations, animations are appended to a global animation list#global-animation-listReferenced in:4.3.2. The effect stack in the order in which they are created. Certain types of animations, however, may provide alternative means of ordering animations (see §4.3.1 Animation types).

3.5.1. Setting the timeline of an animation

The procedure to set the timeline of an animation#set-the-timeline-of-an-animationReferenced in:5.4. The Animation interface (2), animation, to new timeline which may be null, is as follows:

1. Let old timeline be the current timeline of animation, if any.

2. If new timeline is the same object as old timeline, abort this procedure.

3. Let previous animation time be the current time of animation.

4. If new timeline is null and old timeline is not null, run the procedure to reset an animation’s pending tasks on animation.

   Note that if new timeline is not null and animation has a pending play task or a pending pause task no special handling is required: the pending task will run as soon as the animation is ready even though this may occur at a different moment than it might have done with the old timeline.

5. Let the timeline of animation be new timeline.

6. If previous animation time is resolved, run the procedure to silently set the current time of animation to previous animation time.

7. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

The procedure to reset an animation’s pending tasks#reset-an-animations-pending-tasksReferenced in:3.5.1. Setting the timeline of an animation3.5.3. Setting the target effect of an animation3.5.16. Canceling an animation for animation is as follows:

1. If animation has a pending play task, cancel that task.

2. If animation has a pending pause task, cancel that task.

3. Reject animation’s current ready promise with a DOMException named "AbortError".

4. Let animation’s current ready promise be the result of creating a new resolved Promise object.

3.5.2. Responding to a newly inactive timeline

When the timeline associated with an animation, animation, becomes newly inactive, if animation’s previous current time is resolved, the procedure to silently set the current time of animation to previous current time is run.

3.5.3. Setting the target effect of an animation

The procedure to set the target effect of an animation#set-the-target-effect-of-an-animationReferenced in:3.5.3. Setting the target effect of an animation5.4. The Animation interface (2), animation, to new effect which may be null, is as follows:

1. Let old effect be the current target effect of animation, if any.

2. If new effect is the same object as old effect, abort this procedure.

3. If new effect is null and old effect is not null, run the procedure to reset an animation’s pending tasks on animation.

4. If animation has a pending pause task, reschedule that task to run as soon as animation is ready.

5. If animation has a pending play task, reschedule that task to run as soon as animation is ready to play new effect.

6. If new effect is not null and if new effect is the target effect of another animation, previous animation, run the procedure to set the target effect of an animation (this procedure) on previous animation passing null as new effect.

7. Let the target effect of animation be new effect.

8. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

3.5.4. The current time of an animation

Animations provide a time value to their target effect called the animation’s current time#current-timeReferenced in:3.5. Animations3.5.1. Setting the timeline of an animation3.5.4. The current time of an animation (2) (3) (4)3.5.5. Setting the current time of an animation (2) (3)3.5.6. Setting the start time of an animation (2) (3) (4)3.5.10. Playing an animation (2) (3) (4) (5) (6) (7)3.5.11. Pausing an animation (2) (3)3.5.12. Reaching the end (2) (3) (4) (5) (6) (7)3.5.14. Updating the finished state (2) (3) (4) (5) (6) (7) (8) (9) (10)3.5.16. Canceling an animation3.5.17. Speed control (2) (3)3.5.17.1. Updating the playback rate of an animation (2)3.5.19. Play states (2) (3) (4) (5) (6) (7)3.5.20.2. Event parameters3.6.4. Local time5.4. The Animation interface10. Changes since last publication.

The current time is calculated from the first matching condition from below:

3.5.5. Setting the current time of an animation

The current time of an animation can be set to a new value to seek the animation. The procedure for setting the current time is split into two parts.

The procedure to silently set the current time#silently-set-the-current-timeReferenced in:3.5.1. Setting the timeline of an animation3.5.2. Responding to a newly inactive timeline3.5.5. Setting the current time of an animation3.5.15. Finishing an animation3.5.17.1. Updating the playback rate of an animation of an animation, animation, to seek time is as follows:

1. If seek time is an unresolved time value, then perform the following steps.

   1. If the current time is resolved, then throw a TypeError.

   2. Abort these steps.

2. Update either animation’s hold time or start time as follows:

   If any of the following conditions are true:

   • animation’s hold time is resolved, or

   • animation’s start time is unresolved, or

   • animation has no associated timeline or the associated timeline is inactive, or

   • animation’s playback rate is 0,

   Set animation’s hold time to seek time.

   Otherwise,

   Set animation’s start time to the result of evaluating timeline time - (seek time / playback rate) where timeline time is the current time value of timeline associated with animation.

3. If animation has no associated timeline or the associated timeline is inactive, make animation’s start time unresolved.

   This preserves the invariant that when we don’t have an active timeline it is only possible to set either the animation start time or the animation’s current time.

4. Make animation’s previous current time unresolved.

The procedure to set the current time#set-the-current-timeReferenced in:3.5.14. Updating the finished state (2)3.5.17.1. Updating the playback rate of an animation (2)5.4. The Animation interface of an animation, animation, to seek time is as follows:

1. Run the steps to silently set the current time of animation to seek time.

2. If animation has a pending pause task, synchronously complete the pause operation by performing the following steps:

   1. Set animation’s hold time to seek time.

   2. Make animation’s start time unresolved.

   3. Cancel the pending pause task.

   4. Resolve animation’s current ready promise with animation.

3. Run the procedure to update an animation’s finished state for animation with the did seek flag set to true, and the synchronously notify flag set to false.

3.5.6. Setting the start time of an animation

The procedure to set the animation start time#set-the-animation-start-timeReferenced in:5.4. The Animation interface of animation, animation, to start time, new start time, is as follows:

1. Let timeline time be the current time value of the timeline that animation is associated with. If there is no timeline associated with animation or the associated timeline is inactive, let the timeline time be unresolved.

2. If timeline time is unresolved and new start time is resolved, make animation’s hold time unresolved.

   This preserves the invariant that when we don’t have an active timeline it is only possible to set either the animation start time or the animation’s current time.

3. Let previous current time be animation’s current time.

   Note: This is the current time after applying the changes from the previous step which may cause the current time to become unresolved.

4. Set animation’s start time to new start time.

5. Update animation’s hold time based on the first matching condition from the following,

   If new start time is resolved,

   If animation’s playback rate is not zero, make animation’s hold time unresolved.

   Otherwise (new start time is unresolved),

   Set animation’s hold time to previous current time even if previous current time is unresolved.

6. If animation has a pending play task or a pending pause task, cancel that task and resolve animation’s current ready promise with animation.

7. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

Is this right? If you shift an animation backwards in time so that it is now finished, should the current time jump to the end of the target effect, or be allowed to sit past the end of the target effect?

3.5.7. Waiting for the target effect

An animation is ready#readyReferenced in:3.5.1. Setting the timeline of an animation3.5.3. Setting the target effect of an animation (2)3.5.7. Waiting for the target effect3.5.10. Playing an animation (2) (3) at the first moment where both of the following conditions are true:

• the user agent has completed any setup required to begin the playback of the animation’s target effect including rendering the first frame of any keyframe effect.

• the animation is associated with a timeline that is not inactive.

3.5.8. Promise objects

Promise objects are defined by [ECMA-262].

To resolve a Promise#resolve-a-promiseReferenced in:3.5.5. Setting the current time of an animation3.5.6. Setting the start time of an animation3.5.10. Playing an animation3.5.11. Pausing an animation3.5.14. Updating the finished state3.5.15. Finishing an animation (2) with value, call the [[Call]] internal [[Resolve]] method on the PromiseCapability record for the promise, passing undefined as thisArgument and (value) as argumentsList.

To reject a Promise#reject-a-promiseReferenced in:3.5.1. Setting the timeline of an animation3.5.16. Canceling an animation with reason, call the [[Call]] internal [[Reject]] method on the PromiseCapability record for the promise, passing undefined as thisArgument and (reason) as argumentsList.

To create a new resolved Promise#create-a-new-resolved-promiseReferenced in:3.5.1. Setting the timeline of an animation3.5.9. The current ready promise with value, call Promise.resolve, passing value as x.

3.5.9. The current ready promise

Each animation has a current ready promise#current-ready-promiseReferenced in:3.5.1. Setting the timeline of an animation (2)3.5.5. Setting the current time of an animation3.5.6. Setting the start time of an animation3.5.9. The current ready promise (2) (3)3.5.10. Playing an animation (2) (3)3.5.11. Pausing an animation (2)3.5.14. Updating the finished state3.5.15. Finishing an animation (2)3.5.18. Reversing an animation5.4. The Animation interface. The current ready promise is initially a resolved Promise created using the procedure to create a new resolved Promise.

The object is replaced with a new Promise object every time the animation enters the pending play state as well as when the animation is canceled (see §3.5.16 Canceling an animation).

animation.pause();
animation.ready.then(function() {
  // Displays 'running'
  alert(animation.playState);
});
animation.play();

3.5.10. Playing an animation

The procedure to play an animation#play-an-animationReferenced in:3.5.11. Pausing an animation3.5.18. Reversing an animation5.4. The Animation interface5.14. The Animatable interface10. Changes since last publication, animation, given a flag auto-rewind, is as follows:

Note: The auto-rewind flag is provided for other specifications that build on this model but do not require the rewinding behavior, such as CSS Animations [CSS3-ANIMATIONS].

1. Let aborted pause be a boolean flag that is true if animation has a pending pause task, and false otherwise.

2. Let has pending ready promise be a boolean flag that is initially false.

3. Perform the steps corresponding to the first matching condition from the following, if any:

   If animation playback rate > 0, the auto-rewind flag is true and either animation’s:

   • current time is unresolved, or

   • current time < zero, or

   • current time ≥ target effect end,

   Set animation’s hold time to zero.

   If animation playback rate < 0, the auto-rewind flag is true and either animation’s:

   • current time is unresolved, or

   • current time ≤ zero, or

   • current time > target effect end,

   If target effect end is positive infinity, throw an InvalidStateError and abort these steps. Otherwise, set animation’s hold time to target effect end.

   If animation playback rate = 0 and animation’s current time is unresolved,

   Set animation’s hold time to zero.

4. If animation has a pending play task or a pending pause task,

   1. Cancel that task.

   2. Set has pending ready promise to true.

5. If animation’s hold time is unresolved and aborted pause is false, abort this procedure.

6. If animation’s hold time is resolved, let its start time be unresolved.

7. If has pending ready promise is false, let animation’s current ready promise be a new (pending) Promise object.

8. Schedule a task to run as soon as animation is ready. The task shall perform the following steps:

   1. Let ready time be the time value of the timeline associated with animation at the moment when animation became ready.

   2. If animation’s start time is unresolved, perform the following steps:

      1. Let new start time be the result of evaluating ready time - hold time / animation playback rate for animation. If the animation playback rate is zero, let new start time be simply ready time.

      2. If animation’s playback rate is not 0, make animation’s hold time unresolved.

      3. Set the animation start time of animation to new start time.

   3. Resolve animation’s current ready promise with animation.

   4. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

      Note that the order of the above two steps is important since it means that an animation with zero-length target effect will resolve its current ready promise before its current finished promise.

      So long as the above task is scheduled but has yet to run, animation is described as having a pending play task#pending-play-taskReferenced in:3.5.1. Setting the timeline of an animation (2)3.5.3. Setting the target effect of an animation3.5.6. Setting the start time of an animation3.5.10. Playing an animation3.5.11. Pausing an animation3.5.14. Updating the finished state3.5.15. Finishing an animation3.5.19. Play states.

      A user agent MAY execute the above task immediately (if it determines animation is immediately ready) thereby bypassing the pending play state altogether.

9. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

3.5.11. Pausing an animation

Whenever an animation has an unresolved start time, its current time will be suspended.

As with playing an animation, pausing may not happen instantaneously (see §3.5.7 Waiting for the target effect). For example, if animation is performed by a separate process, it may be necessary to synchronize the current time to ensure that it reflects the state drawn by the animation process.

The procedure to pause an animation#pause-an-animationReferenced in:5.4. The Animation interface10. Changes since last publication, animation, is as follows:

1. If animation has a pending pause task, abort these steps.

2. If the play state of animation is paused, abort these steps.

3. If the animation’s current time is unresolved, perform the steps according to the first matching condition from below:

   If animation’s playback rate is ≥ 0,

   Let animation’s hold time be zero.

   Should we throw an exception for playback rate = 0?

   Otherwise,

   If target effect end for animation is positive infinity, throw an InvalidStateError and abort these steps. Otherwise, let animation’s hold time be target effect end.

4. Let has pending ready promise be a boolean flag that is initially false.

5. If animation has a pending play task, cancel that task and let has pending ready promise be true.

6. If has pending ready promise is false, set animation’s current ready promise to a new (pending) Promise object.

7. Schedule a task to be executed at the first possible moment after the user agent has performed any processing necessary to suspend the playback of animation’s target effect, if any. The task shall perform the following steps:

   1. If animation’s start time is resolved and its hold time is not resolved, let animation’s hold time be the result of evaluating ready time - (start time / playback rate).

      Note: The hold time might be already set if the animation is finished, or if the animation is pending, waiting to begin playback. In either case we want to preserve the hold time as we enter the paused state.

   2. Make animation’s start time unresolved.

   3. Resolve animation’s current ready promise with animation.

   4. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

   So long as the above task is scheduled but has yet to run, animation is described as having a pending pause task#pending-pause-taskReferenced in:3.5.1. Setting the timeline of an animation (2)3.5.3. Setting the target effect of an animation3.5.5. Setting the current time of an animation (2)3.5.6. Setting the start time of an animation3.5.10. Playing an animation (2)3.5.11. Pausing an animation (2)3.5.14. Updating the finished state3.5.15. Finishing an animation (2)3.5.19. Play states10. Changes since last publication. While the task is running, however, animation does not have a pending pause task.

8. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

3.5.12. Reaching the end

This section is non-normative

DVD players or cassette players typically continue playing until they reach the end of their media at which point they stop. If such players are able to play in reverse, they typically stop playing when they reach the beginning of their media. In order to emulate this behavior and to provide consistency with HTML’s media elements [HTML], the current time of Web Animations' animations do not play forwards beyond the end time of their target effect or play backwards past time zero.

An animation that has reached the natural boundary of its playback range is said to have finished.

Graphically, the effect of limiting the current time is shown below.

The effect of limiting the current time of an animation with a start time of 1s, a target effect of length 3s, and a positive animation playback rate. After the current time of the animation reaches the end of the target effect, it is capped at 3s.

It is possible, however, to seek the current time of an animation to a time past the end of the target effect. When doing so, the current time will not progress but the animation will act as if it had been paused at the seeked time.

This allows, for example, seeking the current time of an animation with no target effect to 5s. If target effect with an end time later than 5s is later associated with the animation, playback will begin from the 5s mark.

Similar behavior to the above scenario may arise when the length of an animation’s target effect changes.

Similarly, when the animation playback rate is negative, the current time does not progress past time zero.

3.5.13. The current finished promise

Each animation has a current finished promise#current-finished-promiseReferenced in:3.5.10. Playing an animation3.5.13. The current finished promise3.5.14. Updating the finished state (2) (3) (4) (5) (6)3.5.16. Canceling an animation (2)4.1.3.1. Not animatable5.4. The Animation interface10. Changes since last publication. The current finished promise is initially a pending Promise object.

The object is replaced with a new (pending) Promise object every time the animation leaves the finished play state.

3.5.14. Updating the finished state

For an animation with a positive playback rate, the current time continues to increase until it reaches the target effect end.

The target effect end#target-effect-endReferenced in:3.5.10. Playing an animation (2) (3) (4)3.5.11. Pausing an animation (2)3.5.14. Updating the finished state (2) (3) (4) (5)3.5.15. Finishing an animation (2)3.5.19. Play states of an animation is equal to the end time of the animation’s target effect. If the animation has no target effect, the target effect end is zero.

An animation with a negative playback rate, the current time continues to decrease until it reaches zero.

A running animation that has reached this boundary (or overshot it) and has a resolved animation start time is said to be finished.

The crossing of this boundary is checked on each modification to the animation object using the procedure to update an animation’s finished state defined below. This procedure is also run on each sample and each time the timing properties of the target effect associated with an animation are updated.

For each animation, the user agent maintains a previous current time#previous-current-timeReferenced in:3.5.2. Responding to a newly inactive timeline3.5.5. Setting the current time of an animation3.5.14. Updating the finished state (2) (3) time value that is originally unresolved.

Whilst during normal playback the current time of an animation is limited to the boundaries described above, it is possible to seek the current time of an animation to times outside those boundaries using the procedure to set the current time of an animation.

The procedure to update an animation’s finished state#update-an-animations-finished-stateReferenced in:3.5.1. Setting the timeline of an animation3.5.3. Setting the target effect of an animation3.5.5. Setting the current time of an animation3.5.6. Setting the start time of an animation3.5.10. Playing an animation (2)3.5.11. Pausing an animation (2)3.5.14. Updating the finished state3.5.15. Finishing an animation10. Changes since last publication for animation, given a flag did seek (to indicate if the update is being performed after setting the current time), and a flag synchronously notify (to indicate the update was called in a context where we expect finished event queueing and finished promise resolution to happen immediately, if at all) is as follows:

1. If both of the following conditions are true,

   • animation’s start time is resolved, and

   • animation does not have a pending play task or a pending pause task,

   then update animation’s hold time based on the first matching condition for animation from below, if any:

   If animation playback rate > 0 and current time is resolved and greater than or equal to target effect end,

   If did seek is true, let the hold time be the value of current time.

   If did seek is false, let the hold time be the maximum value of previous current time and target effect end. If the previous current time is unresolved, let the hold time be target effect end.

   If animation playback rate < 0 and current time is resolved and less than or equal to 0,

   If did seek is true, let the hold time be the value of current time.

   If did seek is false, let the hold time be zero.

   If current time is resolved, and animation playback rate ≠ 0, and animation is associated with an active timeline,

   Perform the following steps:

   1. If did seek is true and the hold time is resolved, let animation’s start time be equal to the result of evaluating timeline time - (hold time / playback rate) where timeline time is the current time value of timeline associated with animation.

   2. Let the hold time be unresolved.

2. Set the previous current time of animation be the result of calculating its current time.

3. Let current finished state be true if the play state of animation is finished. Otherwise, let it be false.

4. If current finished state is true and the current finished promise is not yet resolved, perform the following steps:

   1. Let finish notification steps#finish-notification-stepsReferenced in:3.5.14. Updating the finished state (2) (3) refer to the following procedure:

      1. If animation’s play state is not equal to finished, abort these steps.

      2. Resolve animation’s current finished promise object with animation.

      3. Queue a task to fire a finish event at animation. The task source for this task is the DOM manipulation task source.

   2. If synchronously notify is true, cancel any queued microtask to run the finish notification steps for this animation, and run the finish notification steps immediately.

      Otherwise, if synchronously notify is false, queue a microtask to run finish notification steps for animation unless there is already a microtask queued to run those steps for animation.

5. If current finished state is false and animation’s current finished promise is already resolved, set animation’s current finished promise to a new (pending) Promise object.

var animation = elem.animate({ left: '100px' }, 2000);
animation.playbackRate = 2;
animation.currentTime = 1000; // animation is now finished
animation.effect.timing.iterationCount = 2; // animation is no longer finished

var animation = elem.animate({ left: '100px' }, 1000);
animation.finish(); // finish event is queued immediately and finished promise
                    // is resolved despite the fact that the following statement
                    // causes the animation to leave the finished state
animation.currentTime = 0;

3.5.15. Finishing an animation

An animation can be advanced to the natural end of its current playback direction by using the procedure to finish an animation#finish-an-animationReferenced in:3.5.14. Updating the finished state (2)5.4. The Animation interface10. Changes since last publication for animation defined below:

1. If animation playback rate is zero, or if animation playback rate > 0 and target effect end is infinity, throw an InvalidStateError and abort these steps.

2. Set limit as follows:

   If animation playback rate > 0,

   Let limit be target effect end.

   Otherwise,

   Let limit be zero.

3. Silently set the current time to limit.

4. If animation’s start time is unresolved and animation has an associated active timeline, let the start time be the result of evaluating timeline time - (limit / playback rate) where timeline time is the current time value of the associated timeline.

5. If there is a pending pause task and start time is resolved,

   1. Let the hold time be unresolved.

      Typically the hold time will already be unresolved except in the case when the animation was previously idle.

   2. Cancel the pending pause task.

   3. Resolve the current ready promise of animation with animation.

6. If there is a pending play task and start time is resolved, cancel that task and resolve the current ready promise of animation with animation.

7. Run the procedure to update an animation’s finished state animation with the did seek flag set to true, and the synchronously notify flag set to true.

3.5.16. Canceling an animation

An animation can be canceled which causes the current time to become unresolved hence removing any effects caused by the target effect.

The procedure to cancel an animation#cancel-an-animationReferenced in:3.5.2. Responding to a newly inactive timeline3.5.14. Updating the finished state5.4. The Animation interface for animation is as follows:

1. If animation’s play state is not idle, perform the following steps:

   1. Run the procedure to reset an animation’s pending tasks on animation.

   2. Reject the current finished promise with a DOMException named "AbortError".

   3. Let current finished promise be a new (pending) Promise object.

   4. If animation is not idle, queue a task to fire a cancel event at animation. The task source for this task is the DOM manipulation task source.

      The event current time for the dispatched cancel event is unresolved and the event timeline time is the current time value of the timeline associated with animation at the moment the task is queued.

2. Make animation’s hold time unresolved.

3. Make animation’s start time unresolved.

3.5.17. Speed control

Animations have a playback rate#animation-playback-rateReferenced in:3.5.4. The current time of an animation (2)3.5.5. Setting the current time of an animation (2)3.5.6. Setting the start time of an animation3.5.10. Playing an animation (2) (3) (4) (5) (6)3.5.11. Pausing an animation (2) (3)3.5.12. Reaching the end (2)3.5.14. Updating the finished state (2) (3) (4) (5) (6)3.5.15. Finishing an animation (2) (3) (4)3.5.17. Speed control (2)3.5.17.1. Updating the playback rate of an animation (2) (3)3.5.18. Reversing an animation3.5.19. Play states (2) (3)5.4. The Animation interface (2) (3) (4) that provides a scaling factor from the rate of change of the associated timeline’s time values to the animation’s current time. The playback rate is initially 1.

Setting an animation’s playback rate to zero effectively pauses the animation (however, the play state does not necessarily become paused).

3.5.17.1. Updating the playback rate of an animation

Changes to the playback rate trigger a compensatory seek so that that the animation’s current time is unaffected by the change to the playback rate.

The procedure to set the animation playback rate#set-the-animation-playback-rateReferenced in:5.4. The Animation interface of an animation, animation to new playback rate is as follows:

1. Let previous time be the value of the current time of animation before changing the playback rate.

2. Set the playback rate to new playback rate.

3. If previous time is resolved, set the current time of animation to previous time.

The procedure to silently set the animation playback rate#silently-set-the-animation-playback-rateReferenced in:3.5.18. Reversing an animation of animation, animation to new playback rate is identical to the above procedure except that rather than invoking the procedure to set the current time in the final step, the procedure to silently set the current time is invoked instead.

3.5.18. Reversing an animation

The procedure to reverse an animation#reverse-an-animationReferenced in:5.4. The Animation interface of animation animation is as follows:

1. If there is no timeline associated with animation, or the associated timeline is inactive throw an InvalidStateError and abort these steps.

2. Silently set the animation playback rate of animation to −animation playback rate.

   This must be done silently or else we may end up resolving the current ready promise when we do the compensatory seek despite the fact that we are most likely not exiting the pending play state.

3. Run the steps to play an animation for animation with the auto-rewind flag set to true.

3.5.19. Play states

An animation may be described as being in one of the following play states#play-stateReferenced in:3.5.11. Pausing an animation3.5.14. Updating the finished state (2)3.5.16. Canceling an animation3.5.17. Speed control3.5.19. Play states5.4. The Animation interface for each of which, a non-normative description is also provided:

The play state of animation, animation, at a given moment is the state corresponding to the first matching condition from the following:

animation.effect.timing.duration = 5000;
animation.currentTime = 4000;
animation.pause();
animation.ready.then(function() {
  animation.effect.timing.duration = 3000;
  alert(animation.playState); // Displays 'paused'
  animation.startTime =
    document.timeline.currentTime - animation.currentTime * animation.playbackRate;
  alert(animation.playState); // Displays 'finished'
});

3.5.20. Animation events

As animations play, they report changes to their status through animation events#animation-eventsReferenced in:3.5.20. Animation events3.5.20.2. Event parameters5.18. The AnimationPlaybackEvent interface10. Changes since last publication.

Animation events are a property of the timing model. As a result they are dispatched even when the target effect of the animation is absent or has no observable result.

3.5.20.1. Types of animation events

finish#finish-eventReferenced in:3.5.14. Updating the finished state (2)5.4. The Animation interface

Queued whenever an animation enters the finished play state.

cancel#cancel-eventReferenced in:3.5.14. Updating the finished state3.5.16. Canceling an animation (2)3.5.20.1. Types of animation events5.4. The Animation interface

Queued whenever an animation enters the idle play state from another state. Creating a new animation that is initially idle does not generate a new cancel event.

3.5.20.2. Event parameters

Animation events have an associated event current time and event timeline time.

The event current time#event-current-timeReferenced in:3.5.16. Canceling an animation3.5.20.2. Event parameters5.18. The AnimationPlaybackEvent interface is the current time of the animation that generated the event at the moment the event is queued. This will be unresolved if the animation was idle at the time the event was generated.

The event timeline time#event-timeline-timeReferenced in:3.5.16. Canceling an animation3.5.20.2. Event parameters5.18. The AnimationPlaybackEvent interface is the time value of the timeline with which the animation that generated the event is associated at the moment the event is queued. This will be unresolved if the animation was not associated with a timeline at the time the event was generated or if the associated timeline was inactive.

3.6. Animation effects

An animation effect#animation-effectReferenced in:3.5. Animations (2) (3) (4)3.6.1. Relationship between animation effects and animations (2) (3)3.6.2. Types of animation effects (2) (3)3.6.3. The active interval (2) (3) (4) (5) (6) (7) (8) (9)3.6.4. Local time (2)3.6.5. Animation effect phases and states (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17) (18) (19) (20) (21) (22) (23) (24) (25) (26)3.7. Fill behavior3.8.2. Controlling iteration (2) (3) (4) (5) (6)3.9.1. Overview3.9.3.1. Calculating the active time3.9.3.2. Calculating the scaled active time3.10. Direction control (2)3.11.1. Scaling the time (2) (3) (4)3.11.2. Timing functions (2) (3)3.11.4. Timing in discrete steps3.11.5. Calculating the transformed time3.11.6. Calculating the iteration progress (2) (3)4. Animation Model4.1. Keyframe effects4.1.3.1. Not animatable (2)4.3. Combining effects (2)4.3.2. The effect stack (2)5.5. The AnimationEffectReadOnly interface (2) (3) (4)5.6. The AnimationEffectTimingReadOnly interface (2) (3) (4) (5) (6) (7)5.7. The AnimationEffectTiming interface (2)5.9. The ComputedTimingProperties dictionary (2) (3) (4) (5) (6) (7)5.9.1. The FillMode enumeration5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2)5.10.4. The KeyframeEffectOptions dictionary5.11. The IterationCompositeOperation enumeration (2)5.12. The CompositeOperation enumeration (2) (3) (4)5.14. The Animatable interface5.15. Extensions to the Document interface10. Changes since last publication is an abstract term referring to an item in the timing hierarchy.

3.6.1. Relationship between animation effects and animations

The target effect of an animation, if set, is a type of animation effect. The target effect of an animation is said to be associated#associated-with-an-animationReferenced in:3.6.1. Relationship between animation effects and animations (2)3.6.4. Local time3.6.5. Animation effect phases and states4.3.2. The effect stack5.9. The ComputedTimingProperties dictionary (2) with that animation. At a given moment, an animation effect can be associated with at most one animation.

An animation effect, effect, is associated with a timeline, timeline, if effect is associated with an animation which, in turn, is associated with timeline.

3.6.2. Types of animation effects

This specification defines a single type of animation effect: keyframe effects. Subsequent levels of this specification will define further types of animation effects. All types of animation effects define a number of common properties which are described in the following sections.

3.6.3. The active interval

The period that an animation effect is scheduled to run is called its active interval. Each animation effect has only one such interval.

The lower bound of the active interval typically corresponds to the start time of the animation associated with this animation effect but may be shifted by a start delay on the animation effect.

The upper bound of the interval is determined by the active duration.

The relationship between the start time, start delay, and active duration is illustrated below.

Examples of the effect of the start delay on the endpoints of the active interval.
(a) An animation effect with no delay; the start time and beginning of the active interval are coincident.
(b) An animation effect with a positive delay; the beginning of the active interval is deferred by the delay.
(c) An animation effect with a negative delay; the beginning of the active interval is brought forward by the delay.

An end delay may also be specified but is primarily only of use when sequencing animations.

Animation effects define an active interval#active-intervalReferenced in:3.6.3. The active interval (2) (3) (4) (5) (6) (7) (8) (9)3.6.5. Animation effect phases and states (2) (3) (4)3.7.1. Fill modes (2)3.8.1. Iteration intervals (2)3.9.1. Overview3.9.4. Calculating the current iteration3.11.4. Timing in discrete steps3.11.6. Calculating the iteration progress5.6. The AnimationEffectTimingReadOnly interface (2) (3) which is the period of time during which the effect is scheduled to produce its effect with the exception of fill modes which apply outside the active interval.

The lower bound of the active interval is defined by the start delay.

The start delay#start-delayReferenced in:3.6.3. The active interval (2) (3) (4) (5) (6)3.6.5. Animation effect phases and states (2) (3) (4)3.9.1. Overview3.9.3.1. Calculating the active time (2)3.11.6. Calculating the iteration progress (2)5.6. The AnimationEffectTimingReadOnly interface5.10.1. Creating a new KeyframeEffect object of an animation effect is a signed offset from the start time of the animation with which the animation effect is associated

The length of the active interval is called the active duration, the calculation of which is defined in §3.9.2 Calculating the active duration.

Similar to the start delay, an animation effect also has an end delay#end-delayReferenced in:3.6.3. The active interval (2)5.6. The AnimationEffectTimingReadOnly interface5.9. The ComputedTimingProperties dictionary which is primarily of use when sequencing animations based on the end time of another animation effect. Although this is typically only useful in combination with sequence effects which are introduced in a subsequent level of this specification, it is included here for the purpose of representing the min attribute in SVG ([SVG11], Chapter 19).

The end time#end-timeReferenced in:3.5.12. Reaching the end (2)3.5.14. Updating the finished state3.6.3. The active interval3.6.5. Animation effect phases and states (2) (3)5.4. The Animation interface5.9. The ComputedTimingProperties dictionary10. Changes since last publication of an animation effect is simply the sum of its start delay, active duration, and end delay.

3.6.4. Local time

The local time#local-timeReferenced in:3.6.5. Animation effect phases and states (2) (3) (4) (5) (6) (7) (8) (9)3.9.1. Overview (2) (3) (4) (5)3.9.3.1. Calculating the active time (2) (3)3.11.6. Calculating the iteration progress (2)5.9. The ComputedTimingProperties dictionary (2) of an animation effect at a given moment is based on the first matching condition from the following:

3.6.5. Animation effect phases and states

This section is non-normative

At a given moment, an animation effect may be in one of three possible phases. If an animation effect has an unresolved local time it will not be in any phase.

The different phases are illustrated below.

An example of the different phases and states used to describe an animation effect.

The phases are as follows:

before phase

The animation effect’s local time falls before the effect’s active interval.

active phase

The animation effect’s local time falls inside the effect’s active interval.

after phase

The animation effect’s local time falls after the effect’s active interval.

In addition to these phases, an animation effect may also be described as being in one of several overlapping states. These states are only established for the duration of a single sample and are primarily a convenience for describing stative parts of the model.

These states and their useage within the model are summarized as follows:

in play

Corresponds to an animation effect whose active time is changing on each sample.

current

Corresponds to an animation effect that is either in play or may become in play in the future. This will be the case if the animation effect is in play or in its before phase, or it has an ancestor for which this is true thereby opening up the possibility that this animation effect might play again (e.g. due to repeating).

in effect

Corresponds to an animation effect that has a resolved active time. This occurs when either the animation effect is in its active phase or outside the active interval but at a time where the effect’s fill mode (see §3.7 Fill behavior) causes its active time to be resolved. Only in effect animation effects apply a result to their target.

The normative definition of each of these states follows.

An animation effect is in the before phase#before-phaseReferenced in:3.6.5. Animation effect phases and states (2) (3)3.7.1. Fill modes (2)3.9.3.1. Calculating the active time3.9.4. Calculating the current iteration3.11.4. Timing in discrete steps if the animation effect’s local time is not unresolved and is less than min(start delay, end time).

An animation effect is in the active phase#active-phaseReferenced in:3.6.5. Animation effect phases and states (2) (3)3.9.3.1. Calculating the active time if all of the following conditions are met:

1. the animation effect’s local time is not unresolved, and

2. the animation effect’s local time is greater than or equal to its start delay, and

3. the animation effect’s local time is less than min(start delay + active duration, end time).

An animation effect is in the after phase#after-phaseReferenced in:3.6.5. Animation effect phases and states3.7.1. Fill modes (2)3.9.3.1. Calculating the active time3.9.4. Calculating the current iteration3.11.4. Timing in discrete steps10. Changes since last publication if the animation effect’s local time is not unresolved and is greater than or equal to min(start delay+ active duration, end time).

An animation effect is in play#in-playReferenced in:3.6.5. Animation effect phases and states (2) (3) (4) (5)3.7. Fill behavior3.7.1. Fill modes (2) (3) (4) (5)3.8.4. Interval timing if all of the following conditions are met:

1. the animation effect is in the active phase, and

2. the animation effect is associated with an animation that is not finished.

An animation effect is current#currentReferenced in:3.6.5. Animation effect phases and states5.14. The Animatable interface5.15. Extensions to the Document interface (2) if either of the following conditions is true:

• the animation effect is in the before phase, or

• the animation effect is in play.

An animation effect is in effect#in-effectReferenced in:3.6.5. Animation effect phases and states (2)4.3. Combining effects (2)5.14. The Animatable interface5.15. Extensions to the Document interface if its active time as calculated according to the procedure in §3.9.3.1 Calculating the active time is not unresolved.

3.7. Fill behavior

The effect of an animation effect when it is not in play is determined by its fill mode#fill-modeReferenced in:3.6.3. The active interval3.6.5. Animation effect phases and states3.7. Fill behavior3.7.1. Fill modes3.9.3.1. Calculating the active time (2) (3)3.11.4. Timing in discrete steps5.6. The AnimationEffectTimingReadOnly interface (2) (3) (4).

The possible fill modes are:

• none,

• forwards,

• backwards, and

• both.

The normative definition of these modes is incorporated in the calculation of the active time in §3.9.3.1 Calculating the active time.

3.7.1. Fill modes

This section is non-normative

The effect of each fill mode is as follows:

none

The animation effect has no effect when it is not in play.

forwards

When the animation effect is in the after phase, the animation effect will produce the same transformed time value as the last moment it is scheduled to be in play.

For all other times that the animation effect is not in play, it will have no effect.

backwards

When the animation effect is in the before phase, the animation effect will produce the same transformed time value as the earliest moment that it is scheduled to be in play.

For all other times that the animation effect is not in play, it will have no effect.

both

When the animation effect is in its before phase, backwards fill behavior is used.

When the animation effect is in its after phase, forwards fill behavior is used.

Some examples of the these fill modes are illustrated below.

Examples of various fill modes and the states produced.
(a) fill mode ‘none’. The animation effect has no effect outside its active interval.
(b) fill mode ‘forwards’. After the active interval has finished, the timed value continues to maintain a fill value.
(c) fill mode ‘backwards’. The animation effect produces a fill value until the start of the active interval.
(d) fill mode ‘both’. Both before and after the active interval the animation effect produces a fill value.

Note: setting a fill mode has no bearing on the endpoints of the active interval. However, the fill mode does have an effect on various other properties of the timing model since the active time of an animation effect is only defined (that is, not unresolved) inside the active interval or when a fill is applied.

Currently timing functions that generate results outside the range [0, 1] will behave unexpectedly when applied to group effects, as children will increase iterations or enter into fill mode rather than continuing to extrapolate along their defined behavior (which is what they would do if the timing function applied to them directly).

To fix this it is possible we will wish to introduce overflow fill modes that respond to time values larger than or smaller than the active time range by extrapolating rather than filling.

See section 15 (Overflowing fill) of minuted discussion from Tokyo 2013 F2F.

3.8. Repeating

3.8.1. Iteration intervals

It is possible to specify that an animation effect should repeat a fixed number of times or indefinitely. This repetition occurs within the active interval. The span of time during which a single repetition takes place is called an iteration interval#iteration-intervalReferenced in:3.8.1. Iteration intervals3.8.2. Controlling iteration5.6. The AnimationEffectTimingReadOnly interface.

Unlike the active interval, an animation effect can have multiple iteration intervals although typically only the interval corresponding to the current iteration is of interest.

The length of a single iteration is called the iteration duration#iteration-durationReferenced in:3.8.1. Iteration intervals (2) (3) (4) (5) (6)3.9.1. Overview3.9.2. Calculating the active duration (2)3.9.3.2. Calculating the scaled active time (2)3.9.3.3. Calculating the iteration time (2) (3)3.9.4. Calculating the current iteration (2) (3) (4) (5)3.10.1. Calculating the directed time3.11.5. Calculating the transformed time (2) (3) (4) (5)3.11.6. Calculating the iteration progress (2) (3) (4) (5) (6) (7) (8) (9)5.5. The AnimationEffectReadOnly interface5.6. The AnimationEffectTimingReadOnly interface5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces5.10.1. Creating a new KeyframeEffect object5.10.3. Processing a frames argument. The initial iteration duration of an animation effect is zero.

This section is non-normative

Comparing the iteration duration and the active duration we have:

Iteration duration

The time taken for a single iteration of the animation effect to complete.

Active duration

The time taken for the entire animation effect to complete, including repetitions. This may be longer or shorter than the iteration duration.

The relationship between the iteration duration and active duration is illustrated below.

A comparison of the iteration duration and active duration of an animation effect with an iteration count of 2.5. Note that the iteration duration for the final iteration does not change, it is simply cut-off by the active duration.

3.8.2. Controlling iteration

The number of times an animation effect repeats is called its iteration count#iteration-countReferenced in:3.8.1. Iteration intervals3.8.2. Controlling iteration (2) (3) (4) (5) (6) (7)3.9.1. Overview3.9.2. Calculating the active duration (2)3.9.3.3. Calculating the iteration time (2) (3) (4) (5)3.9.4. Calculating the current iteration (2) (3) (4) (5) (6)3.11.6. Calculating the iteration progress5.6. The AnimationEffectTimingReadOnly interface. The iteration count is a real number greater than or equal to zero. The iteration count may also be positive infinity to represent that the animation effect repeats indefinitely.

In addition to the iteration count, animation effects also have an iteration start#iteration-startReferenced in:3.8.2. Controlling iteration (2) (3) (4) (5) (6)3.9.1. Overview3.9.3.2. Calculating the scaled active time (2) (3)3.9.3.3. Calculating the iteration time (2)3.9.4. Calculating the current iteration (2) (3) (4)3.11.6. Calculating the iteration progress5.6. The AnimationEffectTimingReadOnly interface property which specifies an offset into the series of iterations at which the animation effect should begin. The iteration start is a finite real number greater than or equal to zero.

The behavior of these parameters is defined in the calculations in §3.9 Core animation effect calculations.

This section is non-normative

The effect of the iteration count and iteration start parameters is illustrated below.

The effect of the iteration count and iteration start parameters.
In the first case the iteration count is 2.5 resulting in the third iteration being cut-off half way through its iteration interval.
The second case is the same but with an iteration start of 0.5. This causes the animation effect to begin half way through the first iteration.

Unlike the iteration count parameter, the iteration start parameter does not effect the length of the active duration.

Note that values of iteration start greater than or equal to one are generally not useful unless used in combination with an animation effect that has an iteration composite operation of accumulate.

3.8.3. Iteration time space

This section is non-normative

In Web Animations all times are relative to some point of reference. These different points of reference produce different time spaces.

This can be compared to coordinate spaces as used in computer graphics. The zero time of a time space is analogous to the origin of a coordinate space.

We can describe animations that repeat as establishing a new time space each time the animation repeats: the iteration time space.

Iteration time space is a time space whose zero time is the beginning of an animation effect’s current iteration.

Within the Web Animations model we also refer to active time which is a time relative to the beginning of the active interval. This time space, however, is internal to the model and not exposed in the programming interface or in markup.

These time spaces are illustrated below.

A comparison of local time, active time, and iteration time for an animation with a iteration duration of 1s and an iteration count of 2.5.

Note: While the time spaces themselves are not bounded, Web Animations defines active time and iteration time such that they are clamped to a set range as shown in the diagram. For example, whilst a time of -1 second is a valid time in active time space, the procedure for calculating the active time defined in §3.9.3.1 Calculating the active time will never return a negative value.

In addition to these time spaces we can also refer to the document time space which is time space of the time values of the default document timeline of the active document.

3.8.4. Interval timing

This section is non-normative

When an animation effect repeats we must define the behavior at the iteration boundaries. For this, and indeed for all interval timing, Web Animations uses an endpoint-exclusive timing model. This means that whilst the begin time of an interval is included in the interval, the end time time is not. In interval notation this can written [begin, end). This model provides sensible behavior when intervals are repeated and sequenced since there is no overlap between the intervals.

In the examples below, for the repeated effect, at local time 1s, the iteration time is 0. For the sequenced animations, at timeline time 1s, only animation B’s target effect will be in play; there is no overlap.

Illustration of end-point exclusive timing. For both repeated and sequenced animation effects there is no overlap at the boundaries between intervals.

An exception to this behavior is that when performing a fill, if the fill begins at an interval endpoint, the endpoint is used. This behavior falls out of the algorithm given in §3.9.3.3 Calculating the iteration time and is illustrated below.

After one iteration, the iteration time is 0, but after two iterations (and there onwards), the iteration time is equal to the iteration duration due to the special behavior defined when an animation effect fills.

3.9. Core animation effect calculations

3.9.1. Overview

3.9.2. Calculating the active duration

The active duration is calculated as follows:

active duration#active-durationReferenced in:3.6.3. The active interval (2) (3) (4)3.6.5. Animation effect phases and states (2)3.8.1. Iteration intervals (2) (3) (4)3.8.2. Controlling iteration3.9.1. Overview (2) (3) (4)3.9.2. Calculating the active duration (2)3.9.3.1. Calculating the active time3.9.3.3. Calculating the iteration time3.11.6. Calculating the iteration progress5.9. The ComputedTimingProperties dictionary = iteration duration × iteration count

If either the iteration duration or iteration count are zero, the active duration is zero.

This clarification is needed since the result of infinity multiplied by zero is undefined according to IEEE 754-2008.

3.9.3. Transforming the local time

3.9.3.1. Calculating the active time

The active time#active-timeReferenced in:3.6.5. Animation effect phases and states (2) (3) (4)3.7. Fill behavior3.7.1. Fill modes3.8.3. Iteration time space (2) (3)3.9.1. Overview (2)3.9.3.2. Calculating the scaled active time (2) (3)3.9.3.3. Calculating the iteration time3.9.4. Calculating the current iteration3.11.4. Timing in discrete steps is based on the local time and start delay. However, it is only defined when the animation effect should produce an output and hence depends on its fill mode and phase as follows,

3.9.3.2. Calculating the scaled active time

Before the active time can be converted to an iteration time we must factor in the animation effect’s iteration start. The result is called the scaled active time.

In order to calculate the scaled active time we first define the start offset as follows:

start offset#start-offsetReferenced in:3.9.3.2. Calculating the scaled active time (2) (3) = iteration start × iteration duration

If the iteration start is zero, the start offset is zero.

Note: This clarification is needed since the iteration duration may be infinity and the result of infinity multiplied by zero is undefined according to IEEE 754-2008.

The scaled active time#scaled-active-timeReferenced in:3.9.1. Overview (2)3.9.3.2. Calculating the scaled active time (2)3.9.3.3. Calculating the iteration time (2)3.9.4. Calculating the current iteration is calculated according to the following steps:

1. If the active time is unresolved, return an unresolved time value.

2. Return active time + start offset.

3.9.3.3. Calculating the iteration time

The iteration time#iteration-timeReferenced in:3.8.3. Iteration time space3.9.1. Overview (2) (3)3.9.3.2. Calculating the scaled active time3.10.1. Calculating the directed time (2) (3) (4) (5)3.11.6. Calculating the iteration progress is calculated according to the following steps:

1. If the scaled active time is unresolved, return unresolved.

2. If the iteration duration is zero, return zero.

3. If the active time is equal to the active duration, and the iteration count is not zero, and (iteration count + iteration start) % 1 is zero, return the iteration duration.

   If iteration count is infinity, then for the purpose of evaluating (iteration count + iteration start) % 1 in the above condition, treat iteration count as zero.

4. Otherwise, return scaled active time % iteration duration.

3.9.4. Calculating the current iteration

The current iteration#current-iterationReferenced in:3.8.1. Iteration intervals3.10.1. Calculating the directed time (2)3.11.6. Calculating the iteration progress4. Animation Model4.1. Keyframe effects4.1.4. Effect values5.6. The AnimationEffectTimingReadOnly interface5.9. The ComputedTimingProperties dictionary (2)5.11. The IterationCompositeOperation enumeration10. Changes since last publication can be calculated using the following steps:

1. If the active time is unresolved, return unresolved.

2. If the animation effect is in the before phase or the iteration count is zero, return floor(iteration start).

   This step is required to handle the following special cases:

   • the iteration duration is zero (and we are filling backwards)

   • the iteration count is zero

3. If the animation effect is in the after phase,

   1. If the iteration count is infinity, return infinity.

   2. Otherwise, return ceil(iteration start + iteration count) - 1.

   The above is required to handle the following special cases:

   • the iteration duration is zero (and we are filling forwards)

   • the iteration duration is zero and the iteration count is infinity

   • the active interval ends exactly at the end of an iteration (i.e. iteration start + iteration count is an integer)

4. If the iteration duration is infinity, return floor(iteration start).

5. Otherwise, return floor(scaled active time / iteration duration).

3.10. Direction control

Animation effects may also be configured to run iterations in alternative directions using direction control. For this purpose, animation effects have a playback direction#playback-directionReferenced in:3.9.1. Overview3.10.1. Calculating the directed time (2) (3)3.11.6. Calculating the iteration progress (2)5.6. The AnimationEffectTimingReadOnly interface parameter which takes one of the following values:

• normal,

• reverse,

• alternate, or

• alternate-reverse.

The semantics of these values are incorporated into the calculation of the directed time which follows.

3.10.1. Calculating the directed time

The directed time#directed-timeReferenced in:3.9.1. Overview (2)3.10. Direction control3.11.5. Calculating the transformed time (2) (3) (4)3.11.6. Calculating the iteration progress is calculated from the iteration time using the following steps:

1. If the iteration time is unresolved, return unresolved.

2. Calculate the current direction using the first matching condition from the following list:

   If playback direction is normal,

   Let the current direction be forwards.

   If playback direction is reverse,

   Let the current direction be reverse.

   Otherwise,

   1. Let d be the current iteration.

   2. If playback direction is alternate-reverse increment d by 1.

   3. There used to be a step here which seemed to be adding special handling for filling when the effect ends on a repeat boundary but it seems like that is taken care of by the calcuation of iteration time and current iteration. Is anything actually needed here?

   4. If d % 2 == 0, let the current direction be forwards, otherwise let the current direction be reverse. If d is infinity, let the current direction be forwards.

3. If the current direction is forwards then return the iteration time.

   Otherwise, return the iteration duration - iteration time.

3.11. Time transformations

3.11.1. Scaling the time

This section is non-normative

It is often desirable to control the rate at which an animation effect progresses. For example, easing the rate of animation can create a sense of momentum and produce a more natural effect. Conversely, in other situations such as when modeling a discrete change, a smooth transition is undesirable and instead it is necessary for the animation effect to progress in a series of distinct steps.

For such situations Web Animations provides timing functions that scale the progress of an animation effect.

Timing functions take an input progress value and produce a scaled output progress value.

Example of a timing function that produces an ease-in effect. Given an input progress of 0.7, the timing function scales the value to produce an output progress of 0.52.
By applying this timing function, time will appear to progress more slowly at first but then gradually progress more quickly.

Timing functions are applied to an iteration of an animation effect.

3.11.2. Timing functions

A timing function#timing-functionReferenced in:3.7.1. Fill modes3.11.1. Scaling the time (2) (3)3.11.2. Timing functions (2)3.11.3. Scaling using a cubic Bézier curve3.11.4. Timing in discrete steps3.11.5. Calculating the transformed time3.11.6. Calculating the iteration progress (2)4.1.2. Procedures for animating properties4.2. Keyframes (2)5.6. The AnimationEffectTimingReadOnly interface5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2)5.10.3. Processing a frames argument (2) (3) (4) (5) (6) (7) (8) takes an input progress value in the range [0, 1] and produces an output progress value whose range is unbounded (i.e. positive and negative infinity are permitted).

Animation effects have one timing function associated with them. The default timing function is the linear timing function#linear-timing-functionReferenced in:3.11.2. Timing functions whose output is identical to its input. The linear timing function can be represented by the string “linear”.

The range of timing functions that may be applied to a given animation effects depends on the type of the animation effects.

3.11.3. Scaling using a cubic Bézier curve

This section is non-normative

A common method of producing easing effects is to use a cubic Bézier curve to scale the time. The endpoints of the curve are fixed at (0, 0) and (1, 1) while two control points P1 and P2 define the shape of the curve. Provided the x values of P1 and P2 lie within the range [0, 1] such a curve produces a function that is used to map input times (the x values) onto output times (the y values). This arrangement is illustrated below.

A cubic Bézier curve used as a timing function.
The shape of the curve is determined by the location of the control points P1 and P2.
Input progress values serve as x values of the curve, whilst the y values are the output progress values.

Some example cubic Bézier timing functions are illustrated below.

The timing functions produced by each of the keyword values associated with cubic Bézier timing functions accepted by the easing member of the AnimationEffectTiming interface member from the programming interface.

A cubic Bézier timing function#cubic-bzier-timing-functionReferenced in:3.11.3. Scaling using a cubic Bézier curve (2) is a type of timing function defined by four real numbers that specify the two control points, P1 and P2, of a cubic Bézier curve whose end points are fixed at (0, 0) and (1, 1). The x coordinates of P1 and P2 are restricted to the range [0, 1].

The evaluation of this curve is covered in many sources such as [FUND-COMP-GRAPHICS].

A cubic Bézier timing function may be specified as a string using the following syntax (using notation from [CSS3VAL]):

<cubic-bezier-timing-function>#typedef-cubic-bezier-timing-functionReferenced in:5.6. The AnimationEffectTimingReadOnly interface = ease | ease-in | ease-out | ease-in-out | cubic-bezier(<number>, <number>, <number>, <number>)

The meaning of each value is as follows:

ease

Equivalent to cubic-bezier(0.25, 0.1, 0.25, 1).

ease-in

Equivalent to cubic-bezier(0.42, 0, 1, 1).

ease-out

Equivalent to cubic-bezier(0, 0, 0.58, 1).

ease-in-out

Equivalent to cubic-bezier(0.42, 0, 0.58, 1).

cubic-bezier(<number>, <number>, <number>, <number>)

Specifies a cubic Bézier timing function. The four numbers specify points P1 and P2 of the curve as (x1, y1, x2, y2). Both x values must be in the range [0, 1] or the definition is invalid.

cubic-bezier( [ <number>{6} ; ]* <number>{4} )

3.11.4. Timing in discrete steps

This section is non-normative It is possible to scale an animation effect’s timing so that the group effect occurs in a series of discrete steps using a stepping function.

Some example step timing functions are illustrated below.

Example step timing functions. In each case the domain is the input progress whilst the range represents the output progress produced by the step function.
The first row shows the function for each transition point when only one step is specified whilst the second row shows the same for three steps.

A step timing function#step-timing-functionReferenced in:3.11.4. Timing in discrete steps (2) (3) is a type of timing function that divides the input time into a specified number of intervals that are equal in duration. The output time, starting at zero, rises by an amount equal to the interval duration once during each interval at the transition point which may be either the start, midpoint, or end of the interval.

In keeping with Web Animations' model of endpoint exclusive interval timing (see §3.8.4 Interval timing), the output time at the transition point is the time after applying the increase (i.e. the top of the step) with the following exception.

When a transition point coincides with the end of the active interval extra care must be taken to produce the correct result when performing a fill. To achieve this, when a step timing function is applied to an animation effect or applied to an keyframe associated with a keyframe effect, an additional before flag#before-flagReferenced in:3.11.4. Timing in discrete steps (2) (3) (4) is passed. The value of the before flag is determined as follows:

1. If the active time of the animation effect is unresolved, the before flag is not set and these steps should be aborted.

2. Determine the current direction using the procedure defined in §3.10.1 Calculating the directed time.

3. If the current direction is forwards, let going forwards be true, otherwise it is false.

4. The before flag is set if the animation effect is in the before phase and going forwards is true; or if the animation effect is in the after phase and going forwards is false.

When a step timing function is evaluated at a transition point, if the before flag is set the result is the value before applying the increase.

A step timing function may be specified as a string using the following syntax:

<step-timing-function>#typedef-step-timing-functionReferenced in:5.6. The AnimationEffectTimingReadOnly interface = step-start | step-middle | step-end | steps(<integer>[, [ start | middle | end ] ]?)

The meaning of each value is as follows:

step-start

Equivalent to steps(1, start);

step-middle

Equivalent to steps(1, middle);

step-end

Equivalent to steps(1, end);

steps(<integer>[, [ start | middle | end ] ]?)

Specifies a step timing function. The first parameter specifies the number of intervals in the function. It must be a positive integer (greater than 0). The second parameter, which is optional, specifies the point at which the change of values occur within the interval. If the second parameter is omitted, it is given the value end.

3.11.5. Calculating the transformed time

The transformed time#transformed-timeReferenced in:3.7.1. Fill modes (2)3.9.1. Overview (2) (3)3.11.6. Calculating the iteration progress (2) (3) (4) (5) is calculated from the directed time using the following steps:

1. If the directed time is unresolved, return an unresolved time value.

2. If the iteration duration is infinity, return the directed time.

3. Let unscaled progress be the result of evaluating directed time / iteration duration unless iteration duration is zero, in which case let unscaled progress be zero.

4. Let scaled progress be the result of evaluating the animation effect’s timing function with unscaled progress as the input progress.

5. Return the result of evaluating scaled progress × iteration duration. If the scaled progress is zero, let the result be zero.

   Note: This clarification is needed since the iteration duration may be infinity and the result of infinity multiplied by zero is undefined according to IEEE 754-2008.

3.11.6. Calculating the iteration progress

Before the transformed time is passed to the animation model, it is normalized to represent a fraction of the iteration duration, known as a iteration progress.

The iteration progress#iteration-progressReferenced in:3.11.6. Calculating the iteration progress (2) (3) (4)4. Animation Model4.1. Keyframe effects4.1.4. Effect values4.2.2. The effect value of a keyframe effect (2)5.9. The ComputedTimingProperties dictionary of an animation effect is calculated by running the steps corresponding to the first matching condition from the following:

Note: Since timing functions are allowed to produce output progress values outside the range [0, 1] it is possible that the value calculated for the iteration progress also lies outside this range.

4. Animation Model

4.1. Keyframe effects

Keyframe effects#keyframe-effectReferenced in:3.5.7. Waiting for the target effect3.6.2. Types of animation effects3.11.4. Timing in discrete steps4.1. Keyframe effects4.1.1. Target properties4.1.3.4. Animatable as length, percentage, or calc4.1.4. Effect values4.2. Keyframes (2) (3) (4)4.2.1. Spacing keyframes (2)4.2.2. The effect value of a keyframe effect (2) (3) (4)4.3. Combining effects (2) (3) (4) (5) (6) (7)4.3.2. The effect stack (2) (3)4.3.3. Calculating the result of an effect stack (2) (3) (4) (5)4.3.4. Effect composition4.3.6. Effect accumulation5.6. The AnimationEffectTimingReadOnly interface5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2) (3) (4) (5) (6) (7) (8) (9) (10)5.10.3. Processing a frames argument (2) (3)5.10.5. Computed keyframes5.17. Extensions to the CSSPseudoElement interface10. Changes since last publication are a kind of animation effect that use the output of the timing model to update CSS properties and DOM attributes of an element or pseudo-element such as ::before or ::after [SELECT] referred to as the target element#target-elementReferenced in:4.1.1. Target properties4.1.3.4. Animatable as length, percentage, or calc5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces5.10.5. Computed keyframes (2)5.14. The Animatable interface5.15. Extensions to the Document interface.

Since the result of a keyframe effect is based on the iteration progress and current iteration value, it is updated whenever the timing model is updated including whenever it is sampled.

4.1.1. Target properties

Each keyframe effect can have zero or more associated target properties#target-propertyReferenced in:4.1.1. Target properties (2)4.1.2. Procedures for animating properties4.1.3. Specific animation behaviors4.1.3.2. Animatable as string4.1.3.3. Animatable as real number4.1.3.4. Animatable as length, percentage, or calc4.1.3.5. Animatable as color4.1.3.6. Animatable as transform list4.1.4. Effect values4.2.2. The effect value of a keyframe effect4.3. Combining effects (2) (3) (4) (5) (6)4.3.2. The effect stack4.3.5. Applying the composited result4.3.5.1. Applying the composited result to a CSS property (2)4.3.5.2. Applying the composited result to a DOM attribute.

Target properties may be CSS properties or DOM attributes. If a given target element has an attribute with the same name as a CSS property, any target property of that name is taken to refer to to the CSS property.

Note: If there ever exists a situation where we need to animate an attribute with the same name as a property (other than a presentation attribute [SVG2]) then we will need to introduce a disambiguation strategy. Generally, however, such naming should be avoided.

4.1.2. Procedures for animating properties

Unless specifically defined otherwise, all properties are considered animatable#concept-animatableReferenced in:4.1.4. Effect values. In order to animate a target property, the following procedures must be defined.

• interpolation#animation-interpolationReferenced in:4.1.2. Procedures for animating properties4.1.3.1. Not animatable4.1.3.2. Animatable as string4.1.3.3. Animatable as real number4.1.3.4. Animatable as length, percentage, or calc4.1.3.5. Animatable as color4.1.3.6. Animatable as transform list4.2.2. The effect value of a keyframe effect — given two target property values V_start and V_end, produces an intermediate value V_res at a distance of p along the interval between V_start and V_end such that p = 0 produces V_start and p = 1 produces V_end. The range of p is (−∞, ∞) due to the effect of timing functions. As a result, this procedure must also define extrapolation behavior for p outside [0, 1].

• addition#animation-additionReferenced in:4.1.2. Procedures for animating properties (2) (3) (4)4.1.3. Specific animation behaviors (2) (3)4.1.3.1. Not animatable4.1.3.3. Animatable as real number4.1.3.4. Animatable as length, percentage, or calc4.1.3.5. Animatable as color4.1.3.6. Animatable as transform list (2)4.3.4. Effect composition (2)5.12. The CompositeOperation enumeration — given two target property values V_a and V_b, returns the sum of the two properties, V_result. For addition that is not commutative (for example, matrix multiplication) V_a represents the first term of the operation and V_b represents the second.

  This section is non-normative

  While addition can often be expressed in terms of the same weighted sum function used to define interpolation, this is not always the case. For example, interpolation of transform matrices involves decomposing and interpolating the matrix components whilst addition relies on matrix multiplication.

• accumulation#animation-accumulationReferenced in:4.1.2. Procedures for animating properties (2) (3)4.1.3. Specific animation behaviors (2)4.1.3.6. Animatable as transform list4.2.2. The effect value of a keyframe effect4.3.4. Effect composition (2)4.3.6. Effect accumulation5.12. The CompositeOperation enumeration — given two target property values V_a and V_b, returns the result, V_result, of combining the two operands such that V_b is treated as a delta from V_a. For accumulation that is not commutative (for example, accumulation of mismatched transform lists) V_a represents the first term of the operation and V_b represents the second.

  This section is non-normative

  For many types of animation such as numbers or lengths, accumulation is defined to be identical to addition.

  A common case where the definitions differ is for list-based types where addition may be defined as appending to a list whilst accumulation may be defined as component-based addition. For example, the filter list values "blur(2)" and "blur(3)", when added together may produce "blur(2) blur(3)", but when accumulated, may produce "blur(5)".

• distance computation#distance-computationReferenced in:4.1.3. Specific animation behaviors (2)4.1.3.1. Not animatable4.1.3.3. Animatable as real number4.1.3.4. Animatable as length, percentage, or calc (2)4.1.3.5. Animatable as color4.1.3.6. Animatable as transform list (2)4.2.1. Spacing keyframes4.2.1.1. Applying spacing to keyframes — given two target property values V_start and V_end, calculates some notion of scalar distance between the values, distance.

4.1.3. Specific animation behaviors

The specific procedures used for animating a given target property are referred to as the property’s animation behavior#animation-behaviorReferenced in:4.1.3. Specific animation behaviors (2) (3) (4) (5) (6) (7) (8) (9)4.1.3.1. Not animatable (2)4.1.3.2. Animatable as string4.1.3.3. Animatable as real number4.1.3.4. Animatable as length, percentage, or calc (2)4.1.3.5. Animatable as color4.1.3.6. Animatable as transform list4.1.3.7. Other animation behaviors4.1.4. Effect values4.2.1. Spacing keyframes4.2.1.1. Applying spacing to keyframes4.2.2. The effect value of a keyframe effect (2) (3)4.3.4. Effect composition (2)4.3.5.2. Applying the composited result to a DOM attribute.

The animation behavior of CSS properties is defined by the "Animatable:" line in the summary of the property’s definition or in [CSS3-TRANSITIONS] for properties that lack a such a line.

The default animation behavior for CSS properties is "as string". Should this be defined here or in CSS Animations Level 2?

For DOM attributes, the animation behavior is defined alongside the attribute definition. Unlike CSS properties, if such a definition is not provided the default animation behavior is “not animatable”.

Following is a series of pre-defined animation behaviors. [CSS3-TRANSITIONS] provides further CSS-specific animation behaviors.

For animation behaviors that do not define a specific procedure for addition or which are defined as not additive, the addition procedure is simply V_res = V_b.

For animation behaviors that do not define a specific procedure for accumulation, the accumulation procedure is identical to the addition procedure for that behavior.

For animation behaviors that do not define a specific procedure for distance computation or which are defined as not paceable#not-paceableReferenced in:4.1.3.4. Animatable as length, percentage, or calc (2), the distance computation procedure is simply distance = 1.

4.1.3.1. Not animatable

Some properties are specifically defined as not animatable#concept-not-animatableReferenced in:4.1.3. Specific animation behaviors4.1.3.1. Not animatable (2) (3)4.2.2. The effect value of a keyframe effect4.3.5.2. Applying the composited result to a DOM attribute. For example, properties defining animation parameters are not animatable since doing so would create complex recursive behavior.

Unlike other animation behaviors, no procedures for interpolation, addition and distance computation are defined for properties whose animation behavior is not animatable since these properties should not be modified.

An animation effect that targets a property that is not animatable will still exhibit the usual behavior for an animation effect such as delaying the fulfilment of an animation’s current finished promise.

4.1.3.2. Animatable as string

A target property that is animatable as string has the following animation behavior:

• interpolation:

  $V_{\mathrm{res}}=\left\{\begin{array}{cc}{V}_{\mathrm{start}}\hfill & \text{if }p<0.5\hfill \\ V_{\mathrm{end}}\hfill & \text{if }p\ge 0.5\hfill \end{array}\right.$

  V_res = V_start, if p < 0.5 or V_end, if p ≥ 0.5

4.1.3.3. Animatable as real number

A target property that is animatable as real number#animatable-as-real-numberReferenced in:4.1.3.4. Animatable as length, percentage, or calc4.1.3.5. Animatable as color has the following animation behavior:

• interpolation: V_res = (1 - p) × V_start + p × V_end

• addition: V_a + V_b

• distance computation: distance = |V_end - V_start|

4.1.3.4. Animatable as length, percentage, or calc

A target property that is animatable as length, percentage, or calc has the following animation behavior:

• interpolation: as defined in [CSS3-TRANSITIONS].

• addition: calc(V_a + V_b)
  (Nested calc() functions are expanded when determining the computed value as defined in CSS Values and Units [CSS3VAL].)

• distance computation: as with animatable as real number but using the used value [CSS21] for V_start and V_end.

  When there is insufficient context to calculate a used value for all possible values of V_start and V_end, the result of the distance computation calculation is 1 (i.e. the behavior degenerates to not paceable).

  For example, for a keyframe effect that does not have an target element, there is no containing block for resolving percentage values against. As a result, the following code snippet falls back to not paceable animation behavior.

  var effect =
    new KeyframeEffect([ { top: '10%' },
                         { top: '20%' },
                         { top: '50%' } ],
                       { spacing: 'paced(top)'});
  // Prints '0, 0.5, 1'
  effect.getFrames().map(frame => frame.computedOffset).join(', ');

  For consistency, this definition applies even when a used value could be calculated for each of the animation values in question. As such, the following code fragment produces the same result.

  var effect =
    new KeyframeEffect([ { top: '10px' },
                         { top: '20px' },
                         { top: '50px' } ],
                       { spacing: 'paced(top)'});
  // Prints '0, 0.5, 1'
  effect.getFrames().map(frame => frame.computedOffset).join(', ');

4.1.3.5. Animatable as color

A target property that is animatable as color has the following animation behavior:

• interpolation: as defined in [CSS3-TRANSITIONS].

• addition: as with animatable as real number but performed on each RGBA color component in premultiplied space.

  Note: Since negative color is not currently supported, clamping of the channel values may be performed upon each addition or once when composition is complete.

• distance computation:

  $\mathrm{distance}=\sqrt{{\left(R_{\mathrm{end}}-R_{\mathrm{start}}\right)}^2+{\left(G_{\mathrm{end}}-G_{\mathrm{start}}\right)}^2+{\left(B_{\mathrm{end}}-B_{\mathrm{start}}\right)}^2+{\left(A_{\mathrm{end}}-A_{\mathrm{start}}\right)}^2}$

  distance = sqrt((R_end - R_start)^2 + (G_end - G_start)^2 + (B_end - B_start)^2 + (A_end - A_start)^2)

  where <RGB|A_start|end> represents the red, green, blue, or alpha channel of V_start or V_end respectively. Each value is normalized to the [0.0, 1.0] range and expressed in premultiplied color space.

4.1.3.6. Animatable as transform list

A target property that is animatable as transform list has the following animation behavior:

• interpolation: as defined in Interpolation of Transforms [CSS3-TRANSFORMS].

• addition: performed by concatenating transform lists as ‘V_a V_b’.

• accumulation:

  1. Beginning at the end of each list, V_a and V_b, find the largest contiguous portion of each list where the corresponding list elements from each list have the same transform type. Call the matching portions from V_a and V_b, V_matching-a and V_matching-b respectively and likewise V_remainder-a and V_remainder-b for the non-matching parts.

     We should probably expand 2d functions to their 3d equivalents before matching?

  2. Let V_combined be a transform list combining V_matching-a and V_matching-b by adding the numeric components of each corresponding function.

     This needs to be more specific, e.g. when combining translate(20px) and translate(30px 10px) we have to expand the first function to translate(20px 0px) first. Probably need to define unit conversion too.

  3. The result of accumulation is a transform list created by adding the combined result with the non-matching portions of the two lists as follows: ‘V_remainder-a V_remainder-b V_combined’.

• distance computation: See issue below.

4.1.3.7. Other animation behaviors

The set of animation behaviors defined here may be extended by other specifications. For example, properties with using the <image> type are animated using the interpolation behavior defined in CSS Image Values and Replaced Content [CSS4-IMAGES].

4.1.4. Effect values

Given an iteration progress, a current iteration, and an underlying value, a keyframe effect produces an effect value#effect-valueReferenced in:4.2. Keyframes4.2.2. The effect value of a keyframe effect (2)4.3. Combining effects (2) (3) (4) (5)4.3.3. Calculating the result of an effect stack (2) (3)4.3.4. Effect composition (2) (3) (4) (5) (6) (7) (8)4.3.6. Effect accumulation (2)5.11. The IterationCompositeOperation enumeration for each animatable target property by applying the animation behavior appropriate to the property.

4.2. Keyframes

The effect values for a keyframe effect are calculated by interpolating between a series of property values positioned at fractional offsets. Each set of property values indexed by an offset is called a keyframe#keyframeReferenced in:3.11.4. Timing in discrete steps4.2. Keyframes (2) (3) (4) (5) (6) (7)4.2.1. Spacing keyframes (2) (3)4.2.1.1. Applying spacing to keyframes (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12)4.2.2. The effect value of a keyframe effect (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17) (18) (19) (20) (21)5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2) (3) (4) (5) (6) (7) (8) (9)5.10.3. Processing a frames argument (2) (3) (4) (5) (6) (7) (8) (9) (10)5.10.4. The KeyframeEffectOptions dictionary (2)5.10.5. Computed keyframes5.13. The SharedKeyframeList interface (2)5.14. The Animatable interface.

The offset of a keyframe#keyframe-offsetReferenced in:4.2. Keyframes (2)4.2.1. Spacing keyframes (2) (3) (4) (5) (6) (7) (8) (9)4.2.1.1. Applying spacing to keyframes5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2)5.10.3. Processing a frames argument (2) (3) (4) is a value in the range [0, 1] or the special value null. The list of keyframes for a keyframe effect is loosely sorted by offset#loosely-sorted-by-offsetReferenced in:5.10.3. Processing a frames argument which means that for each keyframe in the list that has a keyframe offset that is not null, the offset is greater than or equal to the offset of the previous keyframe in the list with a keyframe offset that is not null, if any.

The behavior when keyframes overlap or have unsupported values is defined in §4.2.2 The effect value of a keyframe effect.

Each keyframe also has a timing function associated with it that is applied to the period of time between the keyframe on which it is specified and the next keyframe in the list. The timing function specified on the last keyframe in the list is never applied.

Each keyframe may also have a keyframe-specific composite operation#keyframe-specific-composite-operationReferenced in:4.2. Keyframes5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2)5.10.3. Processing a frames argument (2)5.10.4. The KeyframeEffectOptions dictionary that is applied to all values specified in that keyframe. The possible operations and their meanings are identical to those defined for the composite operation associated with the keyframe effect as a whole in §4.3.4 Effect composition. If no keyframe-specific composite operation is specified for a keyframe, the composite operation specified for the keyframe effect as a whole is used for values specified in that keyframe.

4.2.1. Spacing keyframes

This section is non-normative.

It is often useful to be able to provide a series of property values without having calculate the keyframe offset of each value in time but instead to rely on some automatic spacing.

For example, rather than typing:

elem.animate([ { color: 'blue', offset: 0 },
               { color: 'green', offset: 1/3 },
               { color: 'red', offset: 2/3 },
               { color: 'yellow', offset: 1 } ], 2000);

It should be possible to type the following and allow the user agent to calculate the offset of each keyframe:

elem.animate([ { color: 'blue' },
               { color: 'green' },
               { color: 'red' },
               { color: 'yellow' } ], 2000);

Web Animations provides spacing modes for this purpose. The default spacing mode for keyframe effects is “distribute” which produces the result described above.

The other spacing mode, “paced”, is useful when it is desirable to maintain an even rate of change such as for motion path animation.

For example, consider the following animation:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px' },
               { left: '50px' } ], 1000);

The resulting value of the left property is illustrated below:

The animated value of the left property over time when applying the distribute spacing mode. The values are evenly spaced in time but the rate of change differs for each segment as indicated the varying slope of the graph.

We can use the paced spacing mode as follows:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px' },
               { left: '50px' } ],
             { duration: 1000, spacing: "paced(left)" });

The result is illustrated below:

The animated value of the left property over time when applying the paced spacing mode. The absolute value of the slope is graph is equal for all segments of the animation indicating a constant rate of change.

It is also possible to combine fixed keyframe offsets with spacing modes as follows:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px', offset: 0.5 },
               { left: '50px' } ],
             { duration: 1000, spacing: "paced(left)" });

The result is illustrated below:

The animated value of the left property over time when applying the paced spacing mode and a fixed keyframe offset that puts the 100px value at 0.5. The slope of the graph is equal for the first two segments but changes for the last segment in order to accommodate the fixed offset.

Before calculating effect values from a keyframe effect, an absolute value must be computed for keyframe offset of each keyframe with a null offset.

The values computed depend on the keyframe spacing mode#keyframe-spacing-modeReferenced in:4.2.1.1. Applying spacing to keyframes5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2) (3) (4) (5)5.10.3. Processing a frames argument (2) (3)5.10.4. The KeyframeEffectOptions dictionary5.10.5. Computed keyframes specified for the keyframe effect. The keyframe spacing modes are:

distribute#distribute-keyframe-spacing-modeReferenced in:4.2.1. Spacing keyframes (2)4.2.1.1. Applying spacing to keyframes5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces5.10.3. Processing a frames argument

Indicates that keyframes with a null keyframe offset are positioned so that the difference between subsequent keyframe offsets are equal.

paced#paced-keyframe-spacing-modeReferenced in:4.2.1. Spacing keyframes (2) (3) (4) (5)4.2.1.1. Applying spacing to keyframes (2)5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces

Indicates that keyframes with a null keyframe offset are positioned so that the distance between subsequent values of a specified paced property#paced-propertyReferenced in:4.2.1. Spacing keyframes4.2.1.1. Applying spacing to keyframes (2) (3)5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces are equal. The distance is calculated using the distance computation procedure defined by the animation behavior associated with the paced property.

Since the absolute value calculated for a keyframe offset may change depending on the keyframe values, the number of values, or external context (such as when using paced keyframe spacing mode in combination with percentage values or em-based units), the original null values are not overwritten, rather, the calculated absolute values are stored as a separate value on each keyframe known as its computed keyframe offset#computed-keyframe-offsetReferenced in:4.2.1.1. Applying spacing to keyframes (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14)4.2.2. The effect value of a keyframe effect (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12)5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2) (3)5.10.3. Processing a frames argument (2).

4.2.1.1. Applying spacing to keyframes

We define a generic procedure for evenly distributing a keyframe#evenly-distributing-a-keyframeReferenced in:4.2.1.1. Applying spacing to keyframes (2) (3), keyframe, between two reference keyframes, start and end, whose computed keyframe offsets are not null, as follows:

1. Let offset_k#offsetkReferenced in:4.2.1.1. Applying spacing to keyframes (2) (3) (4) (5) (6) be the computed keyframe offset of a keyframe k.

2. Let n be the number of keyframes between and including start and end minus 1.

3. Let index refer to the position of keyframe in the sequence of keyframes between start and end such that the first keyframe after start has an index of 1.

4. Set the computed keyframe offset of keyframe to offset_start + (offset_end − offset_start) × index / n.

The procedure to apply spacing to a series of keyframes#apply-spacing-to-a-series-of-keyframesReferenced in:5.10.3. Processing a frames argument5.10.5. Computed keyframes takes the following parameters:

• a sequence of keyframes: keyframes,

• a spacing mode, spacing, and

• a context element used for resolving relative units, context element, (only required when spacing is paced)

and has the following steps:

1. For each keyframe, in keyframes, let the computed keyframe offset of the keyframe be equal to its keyframe offset value.

2. If keyframes contains more than one keyframe and the computed keyframe offset of the first keyframe in keyframes is null, set the computed keyframe offset of the first keyframe to 0.

3. If the computed keyframe offset of the last keyframe in keyframes is null, set its computed keyframe offset to 1.

4. For each pair of keyframes A and B where:

   • A appears before B in keyframes, and

   • A and B have a computed keyframe offset that is not null, and

   • all keyframes between A and B have a null computed keyframe offset,

   calculate the computed keyframe offset of each keyframe between A and B depending on the value of spacing as follows:

   If spacing is paced,

   1. Define a keyframe as paceable#paceableReferenced in:4.2.1.1. Applying spacing to keyframes (2) (3) (4) (5) if it contains a value for the paced property.

   2. Let paced A be the first keyframe in the range [A, B] that is paceable, if any.

   3. Let paced B be the last keyframe in the range [A, B] that is paceable, if any.

   4. If there is no paced A or paced B let both refer to B.

      Note: In this case the spacing behavior degenerates to distribute spacing.

   5. For each keyframe in the range (A, paced A] and [paced B, B), apply the procedure for evenly distributing a keyframe using A and B as the start and end keyframes respectively.

      Yes, this is correct. We want, index and n in that procedure to reflect all the keyframes between A and B, not just the keyframes between, for example, A and paced A.

   6. For each keyframe in the range (paced A, paced B) that is paceable:

      1. Let dist_k#distkReferenced in:4.2.1.1. Applying spacing to keyframes (2) represent the cumulative distance to a keyframe k from paced A as calculated by applying the distance computation defined by the animation behavior of the paced property to the values of the paced property on each pair of successive paceable keyframes in the range [paced A, k]. Use context element as the basis for resolving context-sensitive values such as percentages units and font-size based units.

      2. Set the computed keyframe offset of k to offset_{paced A} + (offset_{paced B} − offset_{paced A}) × dist_k / dist_{paced B}

   7. For each keyframe in the range (paced A, paced B) that still has a null computed keyframe offset (because it is not paceable), apply the procedure for evenly distributing a keyframe using the nearest keyframe before and after the keyframe in question in keyframes that has a computed keyframe offset that is not null, as the start and end keyframes respectively.

   Otherwise,

   Apply the procedure for evenly distributing a keyframe to each keyframe in the range (A, B) using A and B as the start and end keyframes respectively.

4.2.2. The effect value of a keyframe effect

The effect value of a single property referenced by a keyframe effect as one of its target properties, for a given iteration progress, current iteration and underlying value is calculated as follows.

1. Let target property be the property for which the effect value is to be calculated.

2. If animation behavior of the target property is not animatable abort this procedure since the effect cannot be applied.

3. Define the neutral value for composition#neutral-value-for-compositionReferenced in:4.2.2. The effect value of a keyframe effect (2) as a value which, when combined with an underlying value using the add composite operation, produces the underlying value.

4. Let property-specific keyframes be a copy of the list of keyframes specified on the effect.

5. Remove any keyframes from property-specific keyframes that do not have a property value for target property or for which the property value is invalid or unsupported by the implementation.

   Note: It is important that this step is performed after applying spacing to keyframes since they should be spaced as if the value was supported.

6. If property-specific keyframes is empty, return underlying value.

7. If there is no keyframe in property-specific keyframes with a computed keyframe offset of 0, create a new keyframe with a computed keyframe offset of 0, a property value set to the neutral value for composition, and a composite operation of add, and prepend it to the beginning of property-specific keyframes.

8. Similarly, if there is no keyframe in property-specific keyframes with a computed keyframe offset of 1, create a new keyframe with a computed keyframe offset of 1, a property value set to the neutral value for composition, and a composite operation of add, and append it to the end of property-specific keyframes.

9. Let interval endpoints be an empty sequence of keyframes.

10. Populate interval endpoints by following the steps from the first matching condition from below:

    If iteration progress < 0 and there is more than one keyframe in property-specific keyframes with a computed keyframe offset of 0,

    Add the first keyframe in property-specific keyframes to interval endpoints.

    If iteration progress ≥ 1 and there is more than one keyframe in property-specific keyframes with a computed keyframe offset of 1,

    Add the last keyframe in property-specific keyframes to interval endpoints.

    Otherwise,

    1. Append to interval endpoints the last keyframe in property-specific keyframes whose computed keyframe offset is less than or equal to iteration progress and less than 1. If there is no such keyframe (because, for example, the iteration progress is negative), add the last keyframe whose computed keyframe offset is 0.

    2. Append to interval endpoints the next keyframe in property-specific keyframes after the one added in the previous step.

11. For each keyframe in interval endpoints:

    1. If keyframe has a composite operation that is not replace, or keyframe has no composite operation and the composite operation of this keyframe effect is not replace, then perform the following steps:

       1. Let composite operation to use be the composite operation of keyframe, or if it has none, the composite operation of this keyframe effect.

       2. Let value to combine be the property value of target property specified on keyframe.

       3. Replace the property value of target property on keyframe with the result of combining underlying value (V_a) and value to combine (V_b) using the composite operation to use procedure defined by the target property’s animation behavior.

    2. If this keyframe effect has an iteration composite operation of accumulate, apply the following step current iteration times:

       • replace the property value of target property on keyframe with the result of combining the property value (V_a) with the property value on the final keyframe in property-specific keyframes (V_b) using the accumulation procedure defined for target property.

       It seems like this could be done as a separate step at the end and applied to all types of animation effects consistently.

12. If there is only one keyframe in interval endpoints return the property value of target property on that keyframe.

13. Let start offset be the computed keyframe offset of the first keyframe in interval endpoints.

14. Let end offset be the computed keyframe offset of last keyframe in interval endpoints.

15. Let interval distance be the result of evaluating (iteration progress - start offset) / (end offset - start offset)

16. Return the result of applying the interpolation procedure defined by the animation behavior of the target property, to the values of the target property specified on the two keyframes in interval endpoints taking the first such value as V_start and the second as V_end and using interval distance as the interpolation parameter p.

Note: this procedure permits overlapping keyframes. The behavior is that at the point of overlap the output value jumps to the value of the last defined keyframe at that offset. For overlapping frames at 0 or 1, the output value for iteration progress values less than 0 or greater than or equal to 1 is the value of the first keyframe or the last keyframe in keyframes respectively.

4.3. Combining effects

This section is non-normative

After calculating the effect values for a keyframe effect, they are applied to the animation effect’s target properties.

Since it is possible for multiple in effect keyframe effects to target the same property it is often necessary to combine the results of several keyframe effects together. This process is called compositing#compositionReferenced in:4.1.3.5. Animatable as color and is based on establishing an effect stack for each property targeted by an in effect animation effect.

After compositing the results of keyframe effects together, the composited result is combined with other values specified for the target property.

For a CSS target property the arrangement is illustrated below:

Overview of the application of effect values to their target properties.
The results of keyframe effects targeting the same property are composited together using an effect stack.
The result of this composition is then inserted into the CSS cascade at an appropriate point.

For a target property that specifies a DOM attribute, the composited result is combined with the value of the attribute specified in the DOM or the lacuna value for that attribute if it is not specified.

For the first part of this operation—combining effect values that target the same property— it is necessary to determine both how keyframe effects are combined with one another, as well as the order in which they are applied, that is, their relative composite order.

The matter of how effect values are combined is governed by the composite operation of the corresponding keyframe effects.

The relative composite order of effect values is determined by an effect stack established for each animated property.

4.3.1. Animation types

This specification provides a common animation model intended to be used by other specifications that define markup or programming interfaces on top of this model. The particular markup or programming interface that generated an animation defines its animation type#animation-typeReferenced in:3.5. Animations4.3.1. Animation types4.3.2. The effect stack (2)4.3.5.1. Applying the composited result to a CSS property (2).

Further specifications may define specialized behavior for composite ordering between different types of animations or within a particular type.

4.3.2. The effect stack

Associated with each property targeted by one or more keyframe effects is an effect stack#effect-stackReferenced in:4. Animation Model4.3. Combining effects (2) (3)4.3.2. The effect stack (2)4.3.3. Calculating the result of an effect stack (2) (3)4.3.5.1. Applying the composited result to a CSS property (2) (3) (4)4.3.5.2. Applying the composited result to a DOM attribute (2)5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces5.10.4. The KeyframeEffectOptions dictionary that establishes the relative composite order of the keyframe effects.

The relative composite order of any two keyframe effects, A and B, within an effect stack is established by comparing their properties as follows:

1. Let the associated animation of an animation effect#associated-animation-of-an-animation-effectReferenced in:4.3.5.1. Applying the composited result to a CSS property (2) be the animation associated with the animation effect that affecting the property with which this effect stack is associated.

2. Sort A and B by applying the following conditions in turn until the order is resolved,

   1. If A and B’s associated animations differ by type, sort by any inter-type composite order defined for the corresponding types.

   2. If A and B are still not sorted, sort by any type-specific composite order defined by the common type of A and B’s associated animations.

   3. If A and B are still not sorted, sort by their corresponding position in the global animation list.

Animation effects that sort earlier have lower composite order.

4.3.3. Calculating the result of an effect stack

In order to calculate the final value of an effect stack, the effect values of each keyframe effect in the stack are combined in composite order.

Each step in the process of evaluating an effect stack takes an underlying value#underlying-valueReferenced in:4.1.4. Effect values4.2.2. The effect value of a keyframe effect (2)4.3.3. Calculating the result of an effect stack (2) (3)4.3.4. Effect composition (2) (3) (4) (5) (6)4.3.5.1. Applying the composited result to a CSS property4.3.5.2. Applying the composited result to a DOM attribute5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces5.10.3. Processing a frames argument5.12. The CompositeOperation enumeration (2) (3) as input.

For each keyframe effect in the stack, the appropriate effect value from the keyframe effect is combined with the underlying value to produce a new value. This resulting value becomes the underlying value for combining the next keyframe effect in the stack.

The final value of an effect stack, called the composited value#composited-valueReferenced in:4.3.5. Applying the composited result4.3.5.1. Applying the composited result to a CSS property (2) (3) (4) (5)4.3.5.2. Applying the composited result to a DOM attribute (2) (3), is simply the result of combining the effect value of the final (highest composite order) keyframe effect in the stack with the underlying value at that point.

4.3.4. Effect composition

The specific operation used to combine an effect value with an underlying value is determined by the composite operation#composite-operationReferenced in:4.2. Keyframes (2)4.2.2. The effect value of a keyframe effect (2) (3) (4) (5) (6) (7) (8)4.3. Combining effects4.3.4. Effect composition5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces (2) (3)5.10.3. Processing a frames argument5.10.4. The KeyframeEffectOptions dictionary5.12. The CompositeOperation enumeration (2) (3)10. Changes since last publication of the keyframe effect that produced the effect value.

This specification defines three composite operations as follows:

replace#composite-operation-replaceReferenced in:4.2.2. The effect value of a keyframe effect (2)5.12. The CompositeOperation enumeration

The result of compositing the effect value with the underlying value is simply the effect value.

add#composite-operation-addReferenced in:4.2.2. The effect value of a keyframe effect (2) (3)5.12. The CompositeOperation enumeration

The effect value is added to the underlying value. For animation behaviors where the addition operation is defined such that it is not commutative, the order of the operands is underlying value + effect value.

accumulate#composite-operation-accumulateReferenced in:5.12. The CompositeOperation enumeration

The effect value is accumulated onto the underlying value. For animation behaviors where the accumulation operation is defined such that it is not commutative, the order of the operands is underlying value followed by effect value.

4.3.5. Applying the composited result

The process for applying a composited value depends on if the target property refers to a CSS property or a DOM attribute.

4.3.5.1. Applying the composited result to a CSS property