Define generalized animation event handling machinery

Overview.bs

@@ -97,7 +97,9 @@ urlPrefix: https://html.spec.whatwg.org/multipage/infrastructure.html; type: dfn
     text: fire; url: concept-event-fire
 urlPrefix: https://html.spec.whatwg.org/multipage/embedded-content.html; type: dfn; spec: html
     text: media element
-urlPrefix: https://www.w3.org/TR/hr-time/#dom-; type: interface; text: DOMHighResTimeStamp
+urlPrefix: https://w3c.github.io/hr-time/; spec: highres-time
+    text: time origin; type: dfn
+    text: DOMHighResTimeStamp; type: interface
 urlPrefix: https://dom.spec.whatwg.org/; type: dfn; spec: dom-ls
     text: constructing events
     text: node document; url: concept-node-document
@@ -108,6 +110,10 @@ urlPrefix: https://drafts.csswg.org/cssom/; type: dfn; spec: cssom
     text: CSS property to IDL attribute
     text: IDL attribute to CSS property
     text: serialize a CSS value
+urlPrefix: https://drafts.csswg.org/css-transitions/; type: dfn; spec: css-transitions-1
+    text: events from CSS transitions; url: transition-events
+urlPrefix: https://drafts.csswg.org/css-animations/; type: dfn; spec: css-animations-1
+    text: events from CSS animations; url: events
 </pre>
 <pre class="link-defaults">
 spec:dom; type:interface; text:EventTarget
@@ -597,6 +603,11 @@ A <a>timeline</a> is considered to be
 <dfn lt="inactive timeline">inactive</dfn>
 when its <a>time value</a> is <a>unresolved</a>.
 
+Specific types of [=timelines=] may define a procedure to <dfn lt="timeline time
+to origin-relative time" export>convert a timeline time to an
+origin-relative time</dfn> for [=time value=] |time|, so that the [=time
+values=] produced by wallclock-based timelines can be compared.
+
 <h4 id="document-timelines">Document timelines</h4>
 
 A <dfn>document timeline</dfn> is a type of <a>timeline</a> that is associated
@@ -1787,14 +1798,84 @@ animation.ready.then(function() {
 
 <h4 id="animation-events-section">Animation events</h4>
 
+<dfn>Animation events</dfn> include the [=animation playback events=] defined in
+this specification as well as the <a>events from CSS transitions</a>
+[[CSS-TRANSITIONS-1]] and <a>events from CSS animations</a>
+[[CSS-ANIMATIONS-1]].
+Future specifications may extend this set with further types of [=animation
+events=].
+
+Each {{Document}} maintains a <dfn>pending animation event queue</dfn> that
+stores [=animation events=] along with their corresponding event targets and
+<dfn>scheduled event time</dfn>.
+The [=scheduled event time=] is a [=time value=] relative to the [=time origin=]
+representing when the event would ideally have been dispatched were animations
+updated at an infinitely high frequency.
+Note that this value may be [=unresolved=] if, for example, the [=animation=]'s
+[=timeline=] produces values that are unrelated to the [=time origin=] (e.g.
+a timeline that tracks scroll-position) or if the [=timeline=] is <a
+lt="inactive timeline">inactive</a>.
+
+<h5 id="sorting-animation-events">Sorting animation events</h5>
+
+The following definitions are provided to assist with sorting queued events.
+
+To <dfn lt="animation time to timeline time">convert an animation time to
+timeline time</a> a [=time value=], |time|, that is relative to the [=start
+time=] of an animation, |animation|, perform the following steps:
+
+1.   If |time| is [=unresolved=], return |time|.
+
+1.   If |time| is infinity, return an [=unresolved=] [=time value=].
+
+1.   If |animation|'s <a lt="animation playback rate">playback rate</a> is zero,
+     return an [=unresolved=] [=time value=].
+
+1.   If |animation|'s [=start time=] is [=unresolved=],
+     return an [=unresolved=] [=time value=].
+
+1.   Return the result of calculating:
+     <code>|time| &times; (1 / |playback rate|) + |start time|</code>
+     (where |playback rate| and |start time| are the <a lt="animation playback
+     rate">playback rate</a> and [=start time=] of |animation|, respectively).
+
+To <dfn lt="animation time to origin-relative time">convert a timeline time to
+an origin-relative time</dfn> a [=time value=], |time|, that is expressed in the
+same scale as the [=time values=] of a [=timeline=], |timeline|, perform the
+following steps:
+
+1.   Let |timeline time| be the result of <a lt="animation time to timeline
+     time">converting</a> |time| from an animation time to a timeline time.
+
+1.   If |timeline time| is [=unresolved=],
+     return |time|.
+
+1.   If |animation| is not associated with a [=timeline=],
+     return an [=unresolved=] time value.
+
+1.   If |animation| is associated with an [=inactive timeline=],
+     return an [=unresolved=] time value.
+
+1.   If there is no procedure to <a lt="timeline time to origin-relative
+     time">convert a timeline time to an origin-relative time</a> for the
+     timeline associated with |animation|,
+     return an [=unresolved=] [=time value=].
+
+1.   Return the result of <a lt="timeline time to origin-relative
+     time">converting</a> |timeline time| to an origin-relative time using
+     the procedure defined for the [=timeline=] associated with |animation|.
+
+
+<h5 id="animation-playback-events-section">Animation playback events</h5>
+
 As <a>animations</a> play, they report changes to their status through
-<dfn>animation events</dfn>.
+<dfn>animation playback events</dfn>.
 
-<a>Animation events</a> are a property of the timing model. As a result they
-are dispatched even when the <a>target effect</a> of the <a>animation</a> is
-absent or has no observable result.
+<a>Animation playback events</a> are a property of the timing model. As a result
+they are dispatched even when the <a>target effect</a> of the <a>animation</a>
+is absent or has no observable result.
 
-<h5 id="animation-event-types">Types of animation events</h5>
+<h5 id="animation-playback-event-types">Types of animation playback events</h5>
 
 :   <dfn lt="finish event">finish</dfn>
 ::  Queued whenever an animation enters the <a>finished play state</a>.