[web-animations-1] Make animations become idle when they have an inactive timeline

[birtles]

From @birtles on November 24, 2016 7:31

In experimenting with scroll-driven timelines we often have the situation where we want the state of the timeline to determine whether animations are in-effect or not. For example, you may want the timeline to be active for a certain scroll range and animations to have no effect outside that range.

This is quite tricky, because I imagine that there are some use cases were you have multiple animations associated with the same ScrollTimeline where you want some to fill backwards and others not to. However, I can't see any combination of timeline and effect fillMode that will produce that result.

That suggests to me that timelines actually have four states:

• truly inactive -- i.e. some sort of preconditions are not satisfied and the timeline cannot produce any kind of sensible state (this state might not be needed)
• before start -- i.e. the timeline current time is effectively a hairs' width before zero. Backwards-filling animations associated with it fill backwards, other animations are idle
• after end -- i.e. the timeline has reached its natural end. Forwards-filling animations associated with it fill forwards, other animations are idle
• in range -- i.e. playing normally

That analysis might not be right, but whatever approach we take I think we need to have a consistent answer to the following questions:

• If you play an animation associated with a timeline that is out of its range--what is the state of the animation?
• If you play an animation not associated with a timeline, what does it do initially, and when you later attach a timeline?
• If you set the startTime of an animation not associated with a timeline, what does it do initially, and when you later attach a timeline?
• If you hot-swap timelines, is the current time preserved? And, closely related, do the following code fragments produce the same result:

// A:
anim.timeline = timeline2;
// B:
anim.timeline = null;
anim.timeline = timeline2;

• Similarly, do animations preserve their state (startTime I guess) when re-attaching to the same timeline. i.e. in what circumstances is the following effectively a no-op:

const timeline = anim.timeline;
anim.timeline = null;
anim.timeline = timeline;

I think we have pretty consistent answers to the above currently, but our answers don't work well with inactive timelines and finite timelines.

We also need to bear in mind the following use cases:

1. An animation that is idle until its timeline starts to play
2. An animation that is filling backwards until its timeline starts to play
3. Likewise for the above at the other end of the timeline
4. Set the initial playback position of an animation so that when its timeline starts to play, it picks up from that point
5. Hot-swapping timelines (switch from scroll-based to time-based)
6. Seek an animation that is not attached to a timeline and get meaningful values out of it

The last one is particularly interesting and would be nice to support if possible (we currently do).

Do we also need to support timelines with multiple independent playback ranges? i.e. are the four states above insufficiently general?

theres-waldo/scroll-driven-animations#1 contains some further details of issues we've hit with this.

Copied from original issue: w3c/web-animations#174

[birtles]

To explain some of the background to how this currently works (for my own notes as much as anything), animations have two values: start time and current time which are tied together as follows:

• During normal playback, current time is calculated from start time using the timeline time.
• In some circumstances, we calculate the start time from the current time such as:
  • When setting the current time (assuming we're playing normally; including when calling finish())
  • When playing an animation with a fixed current time (i.e. a paused animation)
  • When updating the playback rate where we want to preserve the current time

In general, the start time and current time are tied together by the timeline time. When we're paused, we have a current time but no start time. Setting the start time, sends you to either the idle state (if you have no active timeline) or the pending/running state.

If we have no active timeline, we have an invariant that you can only set either the current time (hold time) or start time but not both. If we allowed you to set both, then when you later have an active timeline we'd have to choose which one to use. So, while you have an inactive timeline, setting one will clear the other.

In fact, it's generally true to say that you can only ever set one--the other one will be cleared (and then calculated immediately, or when we go to play the animation).

[birtles]

One thought is to have scroll-timelines report negative infinity and positive infinity when outside their range. Then fill modes on animations would work as expected. We'd still need to make the model work correctly with infinite timeline time values (which may be non-trivial) but it would obviate the need for passing further state from timeline to animation to effect (and the extra IDL members to represent it and potential bugs when you failed to check those extra IDL members).

[birtles]

Chatting with @theres-waldo one possibility for preserving the current time when hot-swapping timelines (that probably addresses the requirements in the first comment) is that we say that if you set the timeline to null, we set the hold time. i.e.

const currentTime = anim.currentTime;
anim.timeline = null;
assert(anim.currentTime === currentTime); // Animation is frozen

[birtles]

This is quite confusing. I tried making animations preserve their current time as the hold time but it's complicated by the fact that pause state is represented by the lack of a start time, and when an animation doesn't have a timeline, you can really only set either the start time or the hold time meaningfully.

For example, suppose we have:

const anim = elem.animate(...);
await anim.ready;

At this point anim has a startTime relative to elem.ownerDocument.timeline.

Now if we clear the timeline...

anim.timeline = null;

What we're suggesting in this issue is that anim's hold time is set such that it keeps its current time. However, we have an invariant in the model that says that if an animation doesn't have an active timeline it can only have either a resolved hold time or a resolved start time since otherwise once you attach another timeline we don't know which one to honor.

That means that we'd need to clear the startTime giving us:

console.log(anim.currentTime); // Some number like 52.12...
console.log(anim.startTime); // null
console.log(anim.playState); // paused

Now, what should happen if we re-attach a timeline?

anim.timeline = new DocumentTimeline();
console.log(anim.playState); // running? paused?

Whether it is running or paused will depend on whether or not we resolve a new startTime based on the hold time. Presumably we do want to do that.

That begs the question, however, what should happen if we do the following?

anim.pause();
anim.timeline = null;
anim.timeline = new DocumentTimeline();

Assuming we resolve a new startTime as suggested above, suddenly anim would start playing just because we attached a new timeline which is a little odd. (And we'd need to be careful to make the behavior consistent between whether we set null first or not.)

We currently avoid this by saying that the hold time is cleared when we change timelines. That way the paused state is preserved (through the resolved-ness of the startTime which is not updated).

A few options that come to mind here if we do want to preserve the current time:

• Just say that setting a timeline is equivalent to playing. Get used to it.
• Drop the invariant about only being able to set startTime or hold time on an animation without an active timeline and say that when we re-attach a timeline, if the hold time is set we recalculate the startTime from it (i.e. hold time has priority over startTime).

That last option is fairly attractive. It does mean, however, that you can end up with pretty useless startTime values for an animation without an active timeline (in many cases we'd just be preserving it to represent paused-ness).

Furthermore, such animations will report themselves as running. i.e.

const anim = elem.animate(...);
anim.timeline = null;
console.log(anim.playState); // running

But maybe that's ok? In a sense it tells you what the animation will do when you do attach a timeline. Furthermore, in an academic sense, maybe you could say the animation actually is running, it's just that it is following the infinitely slow null timeline hence why it doesn't progress.

That last point might make even more sense if we later make a distinction between monotonic timelines and infinite timelines (see #2075) where in the latter the startTime is possibly ignored. In that case, the null timeline would simply be an instance of an infinite timeline where the startTime is ignored. (Although I'm not sure how we'll indicate paused-ness in that world -- presumably we still want to be able to pause scroll-driven timelines? Maybe they will have a startTime that is either zero or null depending on if they're running or not?)

[ogerchikov]

In an effort to integrate ScrollTimeline with web animations we came along undefined behaviors, such as:

• Handling unresolved timeline current time by animations. Use cases, based on ScrollTimeline spec:
  • scroll < scrollTimeline.startScrollOffset and scrollTimeline.fill == none or backwards
  • scroll > scrollTimeline.endScrollOffset and scrollTimeline.fill == none or forwards
  • scrollTimeline.startScrollOffset == scrollTimeline.endScrollOffset
• Handling inactive timelines by animations. Use cases, based on ScrollTimeline spec:
  • scroll source does not currently have a CSS layout box
  • scroll source layout box is not a scroll container

To eliminate a requirement to handle unresolved current time we proposed removing scrollTimeline.fill attribute. Instead, resolve the current time for cases when scroll is outside of start and end offsets as follows:

• If scrollTimeline.startScrollOffset is specified and scroll < startScrollOffset, current time = (0 - epsilon) (or -infinity).
• If scrollTimeline.endScrollOffset is specified and scroll > endScrollOffset, current_time = (duration + epsilon) (or +infinity).

What was the original intention to bring scrollTimeline.fill attribute in and which functionality is compromised if the attribute is removed?

As a result, we extended scroll timeline inactiveness definition to include scrollTimeline.startScrollOffset == scrollTimeline.endScrollOffset condition and specified the following behavior of animations in regards to handling inactive timelines:

• If animation is playing and timeline becomes inactive, the animation should have no effect applied as if animation.play() was never called.
• As soon as the timeline becomes active, the animation should start playing again without user intervention.

scroll_timeline = new ScrollTimeline({scrollSource: scroller, ...});
animation = new Animation(new KeyframeEffect(...}], { duration: 2000}), scroll_timeline);
animation.play();

scroller.scrollTop = 50px;
console.log(animation.startTime); // 0
console.log(animation.currentTime); // some number
console.log(animation.playState); // running

scroller.style.overflow="none"

console.log(animation.startTime); // null
console.log(animation.currentTime); // null
console.log(animation.playState); // running

scroller.style.overflow="scroll"

console.log(animation.startTime); // 0
console.log(animation.currentTime); // some number
console.log(animation.playState); // running

Problems with this proposal:

• Hold time is lost when transitioning between active and inactive states. See this diagram.
• Requires substantial changes in web animations spec to redefine playState.

@majido brought a case that perhaps inactive timelines should be handled similarly to null timelines. Intuitively these cases look similar and it would be nice to unify the behavior. Currently running animations with null timeline have start_time = null and hold_time = 0 as illustrated in this example, which works in Firefox too. However animation effect is applied and it is undesired behavior for inactive timelines.

We are looking for suggestions and insights on this subject.

[majido]

Removing ScrollTimeline fill

I support removing ScrollTimeline.fill. It makes sense and improves quite a few thing:

• The current fill property actually does not work as expected in combination with AnimationEffect.fill. See [scroll-animations] ScrollTimeline fill-mode has asymmetric interaction with animation fill modes. #4325 for more info on this.
• Once removed, we no longer need to special case the end scroll offset auto to be inclusive
• Author are able to control the animation value in the before/after portion of scrollRange using AnimationEffect.fill
• As a minor benefit, with this change the timeline is no longer considered "inactive" for a valid scroller that is outside scrollRange. This limits "inactive" to only occur for more specific and rare cases. I think this is a good side benefit of this change. More on this below.

Inactive Timeline Behavior

If we apply the above change to fill then timeline in-activeness become limited to the case where
the scroll timeline scroll source element is null or not a valid scroller (e.g., overflow: visible).

One interesting case that I like to focus here is a scroller with overflow:auto whose content changes overtime. Consider such a scroller that (1) its content initially overflowing, then at some point (2) its content shrinks so it no longer overflows, and finally (3) its content grows again so that the scroller overflows again. I believe if scroll timeline can handle this correctly most other cases would naturally follow. Which is why I think it is a good example.

Per above comment, ideally we went for scroll-linked animation at (1) to have an effect according to the scroll offset, at (2) to have no effect, at (3) to again have effect according to the scroll offset. All of these without requiring authors to anticipate and care about the size of the scroller inner content.

Also my preference is if we can have ScrollTimeline with none-scrolling source to behave similar to a null timeline. The following note in the spec suggests this was also the intent:

This step makes the behavior when an animation’s timeline becomes inactive consistent with when it is disassociated with a timeline. Furthermore, it ensures that the only occasion on which an animation becomes idle, is when the procedure to cancel an animation is performed.

But I think the current prose behaves differently, in particular it causes the animation to be in the paused play state when timeline becomes inactive as opposed to the idle.

My tests with Firefox nightly suggests that Gecko behaves very closely to what I would think is the most desired behavior when timeline is switched between a null and and active timeline (e.g., document.timeline).

Here is a simple code pen that shows this.

A. An animation with an active timeline plays as expected.
B. If animation.timeline is set to null, animation goes into idle and has no effect.
C. As soon as animation timeline is set to document.timeline, animations starts playing again with play state running
C**. Same as C, but if animation was "paused" when timeline changes from null to active, the animation goes from idle to "paused".

Basically, when timeline goes from active<=>null, the animation goes from paused/running <=> idle and back as expected without any action from the author. I think timeline going from active to inactive should behave the same.

[birtles]

To eliminate a requirement to handle unresolved current time we proposed removing scrollTimeline.fill attribute.

I don't think this is the right reason to drop the fill attribute. We still have to handle unresolved current times one way or another.

However, I think a good reason for dropping the fill attribute is the scenario described in the second paragraph of the first comment in this issue and in Majid's comment above this one.

Instead, resolve the current time for cases when scroll is outside of start and end offsets as follows:

• If scrollTimeline.startScrollOffset is specified and scroll < startScrollOffset, current time = (0 - epsilon) (or -infinity).

• If scrollTimeline.endScrollOffset is specified and scroll > endScrollOffset, current_time = (duration + epsilon) (or +infinity).

We should make this magic explicit and introduce the states described in the first comment in this issue.

As a result, we extended scroll timeline inactiveness definition to include scrollTimeline.startScrollOffset == scrollTimeline.endScrollOffset condition and specified the following behavior of animations in regards to handling inactive timelines:

• If animation is playing and timeline becomes inactive, the animation should have no effect applied as if animation.play() was never called.

What does this mean? Is it equivalent to canceling? Is the start time preserved?

• As soon as the timeline becomes active, the animation should start playing again without user intervention.

Right, this is use case 1 from the first comment in this issue.

@majido brought a case that perhaps inactive timelines should be handled similarly to null timelines.

Yep, that same suggestion is made earlier in this thread.

This step makes the behavior when an animation’s timeline becomes inactive consistent with when it is disassociated with a timeline. Furthermore, it ensures that the only occasion on which an animation becomes idle, is when the procedure to cancel an animation is performed.

But I think the current prose behaves differently, in particular it causes the animation to be in the paused play state when timeline becomes inactive as opposed to the idle.

I think that's what the text is saying--it should be come paused, not idle. I think Firefox might have a bug there, or maybe the spec text for the two cases just got out of sync.

Going through this issue and all the others, I think we're converging on something like the following approach:

• Drop fill modes from ScrollTimeline
  • This should fix [scroll-animations] ScrollTimeline fill-mode has asymmetric interaction with animation fill modes. #4325 and may partially address [scroll-animations] Should animation events fire every time active range is left / reentered? #4324 (since we would presumably no longer enter the idle state).
• Introduce the additional timeline states mentioned in the first comment in this thread (e.g. before-start, after-end, in range).
  • This would address [scroll-animations] ScrollTimeline with unresolved time value shouldn't be considered as "inactive" in some cases #4347 too (and possibly [scroll-animations] Animations end up finishing at scroll-position == max #4341).
• Introduce a distinction between montonic timelines (DocumentTimeline) and finite timelines (ScrollTimeline). Define it such that the null timeline is a finite timeline.
• Drop the invariant about being only able to set the hold time or start time when we have an inactive timeline.
• When attaching an active timeline or when an inactive timeline becomes active, always prioritize using the hold time over the start time (that is we re-calculate the start time from the hold time if they are both set, then clear the hold time), but we preserve both for the sake of representing paused-ness.
  • I think this might happen to fix [web-animations-1] Seeking without an active timeline should probably not transition to paused #2048 too.
• Make the play procedure differentiate between different types of timelines such that for finite timelines, if the current time is unresolved we effectively set the start time to zero, ignoring the current state of the timeline. We could possibly pass a flag for this and address [web-animations-1] suggestion: make Animation play method more convenient (add 'time' parameter) #2051 at the same time. (This is a bit awkward and needs more thought. If we want to allow the startTime to represent an offset from the timeline in this case, we will need different logic for pausing/unpausing.)
  • This should fix [web-animations-1] Don't preserve current time for scroll linked animations when changing playbackRate #2075 and is basically (B) from what Majid suggested there.

So the last point is the main one that needs work and one of the questions it raises is whether or not it is ever useful to have an animation that runs at some offset from a fixed timeline (i.e. whether it is ok to simply always make startTime zero). I think it is preferable if we can keep startTime having some meaning. Being able to seek a scroll animation seems useful, and giving startTime some meaning for finite timelines makes the model a little less awkward.

However, it raises questions about how pausing/unpausing works since normally we'd recalculate the startTime from the timeline time then. Pausing/unpausing with finite timelines is already weird though, so maybe it doesn't matter too much.

We also still need to check the 6 use cases in the start of this issue are addressed by this.

[birtles]

Thinking about the start time issue bit further:

• For a paused animation linked to a scroll timeline, making play() cause the animation to jump to the current position of the scroller seems fine for most cases. That is, the current Chromium implementation of setting startTime to 0 or null seems fine for most cses.
• However, we still need to allow setting the startTime to other values because:
  • At very least, we want to be able to seek an Animation without a timeline and if a null timeline and a scroll timeline are in the same class of timelines, that suggests we should be able to set the currentTime on an animation attached to a scroll timeline, which, in turn, implies being able to set the startTime to something other than zero.
  • Being able to seek a scroll-driven animation seems somewhat useful.
  • Having the startTime setter throw when setting any other value than zero or null while the animation is attached to a scroll timeline is odd.
  • When hot-swapping from a document timeline to a scroll timeline, presumably we want to preserve the currentTime, which also implies being able to set the startTime (this use case could use more careful thought, however).
  • (It would be nice to be able to set up a scroll-driven animation that runs at some offset from its scroll timeline by using startTime seems useful but preserving that offset could be hard.)
• The different classes of timelines needs more thought. If we think about a timeline based on a media element (e.g. <video>) it is generally both finite (except for the streaming case) and non-monotonic. In that sense, it is similar to the scroll timeline case. However, it differs in that if you hit play() on an animation bound to the <video> timeline, you probably want it to start at the current video time--or at least I believe there are use cases for both.

In some sense, we can already handle these different cases by, e.g. doing anim.startTime = 0 instead of anim.play() but I suspect authors are going to reach for anim.play() first so we need to make that do something sensible.

[ogerchikov]

Proposal for Spec Changes Based on Discussion on 2019-12-18

Scroll Timeline - Dropping Fill Mode

1. https://drafts.csswg.org/scroll-animations-1/#dom-scrolltimeline-fill - remove fill attribute.
2. https://drafts.csswg.org/scroll-animations-1/#current-time-algorithm - update ScrollTimeline.currentTime calculation as follows:
   • If current scroll offset is less than startScrollOffset, return (0 - epsilon) or -infinity.
   • If current scroll offset is greater than or equal to endScrollOffset, return ( effective time range + epsilon) or +infinity.
   • Consider: do we need explicitly address a case when startScrollOffset equals to endScrollOffset?
3. https://drafts.csswg.org/web-animations-1/#animationtimeline - add timeline state readonly attribute: TimelineState {Inactive, BeforeStart, InRange, AfterEnd}

Timeline State	Document Timeline	Scroll Timeline	Null Timeline	Animation Behavior
Inactive	https://drafts.csswg.org/web-animations-1/#document-timelines: Prior to establishing the time origin for its associated document, a 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.	If scrollSource is null, does not currently have a CSS layout box, or if its layout box is not a scroll container, return an unresolved time value.	always	‘Paused’ animations - no change. Other animations become idle unless animation.currentTime is set.
BeforeStart	never	If current scroll offset is less than startScrollOffset	never	Backwards filling animations fill backwards, other show no effect.
InRange	Always when the timeline is active.	If current scroll offset is greater than or equal to startScrollOffset and less than endScrollOffset.	never	Playing normally
AfterEnd	never	If current scroll offset is greater than or equal to endScrollOffset	never	Forwards filling animations fill forwards, other show no effect.

Web Animations Spec Changes

For the purpose of this discussion null timeline is handled the same as inactive timeline.

1. https://drafts.csswg.org/web-animations/#responding-to-a-newly-inactive-timeline - drop this section. Instead clarify animation state when responding to inactive timeline as follows:
   • Start time is preserved.
   • Hold time is unresolved.
   • Play state is ‘idle’.
2. Add a section “Responding to a newly active timeline”:
   • If hold_time is resolved, calculate start_time based on the hold_time and timeline current time.
3. https://drafts.csswg.org/web-animations/#playing-an-animation-section - update to handle inactive timelines as follows:
   • If the timeline is inactive and both animation start and current time are unresolved, set start time to zero (or timeline.getInitialCurrentTime())
4. https://drafts.csswg.org/web-animations/#pausing-an-animation-section - update to handle inactive timelines. Differentiate between states:
   • Start and hold time are unresolved, play state is ‘idle’ (animation.play was not called).
   • Start time is resolved, hold time is unresolved, play state is ‘idle’ (play was called).
   • Start and hold time are resolved, play stay is ‘paused’ (play was called, timeline became inactive, animation.currentTime was set)
5. https://drafts.csswg.org/web-animations/#setting-the-current-time-of-an-animation - drop Selectors Overview #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 start time or the animation’s current time.
6. https://drafts.csswg.org/web-animations/#play-states
   1. Include the following condition into the “paused” state definition:
      • If both start and hold time are resolved and timeline is inactive (or null).
   2. Include the following condition into the “idle” state definition:
      • The current time of animation is unresolved, the timeline is inactive and has pending play state.

Use Cases

1. An animation that is idle until its timeline starts to play

   scroller.style.overflow="none";
   scroll_timeline = new ScrollTimeline({scrollSource: scroller, ...});
   animation = new Animation(new KeyframeEffect(...}], { duration: 2000}), scroll_timeline);
   animation.play();
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // null
   console.log(animation.playState); // idle

2. An animation that is filling backwards until its timeline starts to play.
   • Same as bullet 1.
3. Likewise for the above at the other end of the timeline.
   • Is it playback rate < 0? If so exactly as bullet 1.
4. Set the initial playback position of an animation so that when its timeline starts to play, it picks up from that point.

   scroller.style.overflow="none";
   scroll_timeline = new ScrollTimeline({scrollSource: scroller, ...});
   animation = new Animation(new KeyframeEffect(...}], { duration: 2000}), scroll_timeline);
   animation.currentTime = 100;
   animation.play();
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // 100 
   console.log(animation.playState); // paused
   // make the timeline active
   scroller.style.overflow="scroll";
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // 100 
   console.log(animation.playState); // running

5. Hot-swapping timelines (switch from scroll-based to time-based).

   scroller.style.overflow="scroll";
   scroll_timeline = new ScrollTimeline({scrollSource: scroller, ...});
   animation = new Animation(new KeyframeEffect(...}], { duration: 2000}), scroll_timeline);
   animation.play();
   ...
   scroller.scrollTop = '50px';
   ...
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // 500 or some other number 
   console.log(animation.playState); // running 
   
   animation.timeline = document.timeline;
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // some number based on the new timeline.currentTime
   console.log(animation.playState); // running or finished

6. Timeline becomes newly inactive while the animation is playing.

   scroller.style.overflow="scroll";
   scroll_timeline = new ScrollTimeline({scrollSource: scroller, ...});
   animation = new Animation(new KeyframeEffect(...}], { duration: 2000}), scroll_timeline);
   animation.play();
   ...
   scroller.scrollTop = '50px';
   ...
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // 500 or some other number 
   console.log(animation.playState); // running 
   // Make the timeline inactive
   scroller.style.overflow="none";
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // null
   console.log(animation.playState); // idle 

7. Seek an animation that is not attached to an active timeline and get meaningful values out of it.

   // Continuation of the above
   scroller.style.overflow="none";
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // null
   console.log(animation.playState); // idle 
   animation.currentTime = 1000;
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // 1000
   console.log(animation.playState); // paused

8. Cont. bullet 7 - the timeline becomes active.

   scroller.style.overflow="scroll";
   console.log(animation.startTime); // some number calculated from the current time of 1000.
   console.log(animation.currentTime); // 1000
   console.log(animation.playState); // running

[birtles]

Sorry for my delay in reviewing this. It's looking good but there are a few parts I'm unsure about.

2. https://drafts.csswg.org/scroll-animations-1/#current-time-algorithm - update ScrollTimeline.currentTime calculation as follows:

   • If current scroll offset is less than startScrollOffset, return (0 - epsilon) or -infinity.

   • If current scroll offset is greater than or equal to endScrollOffset, return ( effective time range + epsilon) or +infinity.

   • Consider: do we need explicitly address a case when startScrollOffset equals to endScrollOffset?

I want to avoid returning any epsilon values. That still leaves open the question of what is the current time of a timeline when it is in the new BeforeStart or AfterEnd states.

My intuition here is simply that it should be 0 or effective time range respectively. That can lead to bugs if script fails to check the timeline state, but given that it is the current time that will be used by those animations that are deemed to be active in those states, I think it's the most correct behavior.

3. https://drafts.csswg.org/web-animations-1/#animationtimeline - add timeline state readonly attribute: TimelineState {Inactive, BeforeStart, InRange, AfterEnd}

This table looks good.

Web Animations Spec Changes

For the purpose of this discussion null timeline is handled the same as inactive timeline.

1. https://drafts.csswg.org/web-animations/#responding-to-a-newly-inactive-timeline - drop this section. Instead clarify animation state when responding to inactive timeline as follows:

   • Start time is preserved.
   • Hold time is unresolved.
   • Play state is ‘idle’.

2. Add a section “Responding to a newly active timeline”:

   • If hold_time is resolved, calculate start_time based on the hold_time and timeline current time.

I'm a little unsure about this. It would mean that if we have an animation that is paused, then if the timeline temporarily became inactive, it would become idle. An animation that is running, however, would resume running after the timeline became active again.

By comparison, if we set the timeline to null and then back again, the paused animation would continue being paused. That's because the procedure for setting a timeline only clears the hold time if the start time is set.

(Also, note that we wouldn't specify that "Play state is idle" since play state is a calculated field.)

I suspect the procedure for responding to a newly inactive timeline might need to cancel pending play/pause tasks. Or perhaps those tasks would need to be updated since the play pending task asserts that either start time or hold time is set but that will no longer be the case if we unconditionally clear the hold time. I'm not sure though--perhaps we'll never queue the task in the case when the hold time is cleared. But we should probably decide what the desired behavior is for a play-pending animation whose timeline becomes inactive.

3. https://drafts.csswg.org/web-animations/#playing-an-animation-section - update to handle inactive timelines as follows:
   • If the timeline is inactive and both animation start and current time are unresolved, set start time to zero (or timeline.getInitialCurrentTime())

What is the reason for the "... and both animation start and current time are unresolved" requirement?

4. https://drafts.csswg.org/web-animations/#pausing-an-animation-section - update to handle inactive timelines. Differentiate between states:

   • Start and hold time are unresolved, play state is ‘idle’ (animation.play was not called).
   • Start time is resolved, hold time is unresolved, play state is ‘idle’ (play was called).
   • Start and hold time are resolved, play stay is ‘paused’ (play was called, timeline became inactive, animation.currentTime was set)

I'm afraid I don't quite follow what the proposed change here is.

6. https://drafts.csswg.org/web-animations/#play-states
   1. Include the following condition into the “paused” state definition:
      • If both start and hold time are resolved and timeline is inactive (or null).
   2. Include the following condition into the “idle” state definition:
      • The current time of animation is unresolved, the timeline is inactive and has pending play state.

I'm not sure I follow the first point, since it seems like if the timeline becomes inactive we will clear the hold time so we would no longer be paused in that case anyway.

But it's the second point I'm more concerned about. Typically if we have a pending task, the play state tells you what state the animation will be in when it finishes pending. However, this change would make that no longer true. This relates to the previous question about what should happen if the timeline of a play-pending animation becomes inactive.

Use Cases

1. An animation that is idle until its timeline starts to play

   scroller.style.overflow="none";
   scroll_timeline = new ScrollTimeline({scrollSource: scroller, ...});
   animation = new Animation(new KeyframeEffect(...}], { duration: 2000}), scroll_timeline);
   animation.play();
   console.log(animation.startTime); // 0
   console.log(animation.currentTime); // null
   console.log(animation.playState); // idle

I think it would actually be preferable if the playState were 'running' here--assuming that the animation will be running once scroller becomes available.

The other use cases look good but I didn't go into them in details since my comments above might affect the behavior there.

Thank you for doing all this work. This is definitely getting closer.

Unfortunately, there are a lot of states to consider here. Ultimately we should really draw up a complete state chart of all the possible states and inputs (including the odd states like when a pending-pause is interrupted by a play() etc.) and reason from that, but that's quite a bit of work.