Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / src / web / animations / animation_4.lucb

#==============================================================================================
#
#   animation_4 - Animations::Animation: time conversions, updating, the finished state and
#                 the pending tasks
#
#   DESCRIPTION:
#       Port of Libraries/LibWeb/Animations/Animation.cpp (lines 1062-1621), by region p4a:
#       converting animation times to timeline and origin-relative times, the document for
#       timing, the per-frame update, the associated effect end and effective playback rate,
#       silently setting the current time, updating the finished state (with its finish
#       notification steps), resetting the pending tasks, the pending play and pause tasks,
#       the ready and finished promises, the constructor, initialize, visit_edges and finalize.
#
#       Copyright (c) 2023-2024, Matthew Olsson <mattco@serenityos.org>.
#       Copyright (c) 2025, Jelle Raaijmakers <jelle@ladybird.org>
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

# mark: Time conversions and the per-frame update ===============================================

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1063 Web::Animations::Animation::convert_an_animation_time_to_timeline_time.
# https://www.w3.org/TR/web-animations-1/#animation-time-to-timeline-time
pub func animations_animation_convert_an_animation_time_to_timeline_time(this: AnimationsAnimation*, time: AnimationsTimeValue?) -> AnimationsTimeValue?:
    # 1. If time is unresolved, return time.
    let given = time else return time

    # 2. If time is infinity, return an unresolved time value.
    if math.is_infinite(given.value):
        return none

    # 3. If animation’s playback rate is zero, return an unresolved time value.
    if this.m_playback_rate == 0.0:
        return none

    # 4. If animation’s start time is unresolved, return an unresolved time value.
    let start_time = this.m_start_time else return none

    # 5. Return the result of calculating: time × (1 / playback rate) + start time (where playback rate and start time
    #    are the playback rate and start time of animation, respectively).
    return animations_time_value_add(animations_time_value_mul(given, 1.0 / this.m_playback_rate), start_time)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1087 Web::Animations::Animation::convert_a_timeline_time_to_an_origin_relative_time.
# https://www.w3.org/TR/web-animations-1/#animation-time-to-origin-relative-time
pub func animations_animation_convert_a_timeline_time_to_an_origin_relative_time(this: AnimationsAnimation*, time: AnimationsTimeValue?) -> f64?:
    # 1. Let timeline time be the result of converting time from an animation time to a timeline time.
    let timeline_time = animations_animation_convert_an_animation_time_to_timeline_time(this, time)

    # 2. If timeline time is unresolved, return time.
    if timeline_time == none:
        return none

    # 3. If animation is not associated with a timeline, return an unresolved time value.
    let timeline = this.m_timeline else return none

    # 4. If animation is associated with an inactive timeline, return an unresolved time value.
    if animations_animation_timeline_is_inactive(timeline):
        return none

    # 5. If there is no procedure to convert a timeline time to an origin-relative time for the timeline associated
    #    with animation, return an unresolved time value.
    if not animations_animation_timeline_can_convert_a_timeline_time_to_an_origin_relative_time(timeline):
        return none

    # 6. Return the result of converting timeline time to an origin-relative time using the procedure defined for the
    #    timeline associated with animation.
    return animations_animation_timeline_convert_a_timeline_time_to_an_origin_relative_time(timeline, timeline_time)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1115 Web::Animations::Animation::document_for_timing.
# https://www.w3.org/TR/web-animations-1/#animation-document-for-timing
pub func animations_animation_document_for_timing(this: AnimationsAnimation*) -> DomDocument*?:
    # An animation’s document for timing is the Document with which its timeline is associated. If an animation is not
    # associated with a timeline, or its timeline is not associated with a document, then it has no document for
    # timing.
    let timeline = this.m_timeline else return none
    return animations_animation_timeline_associated_document(timeline)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1125 Web::Animations::Animation::update.
pub func animations_animation_update(this: AnimationsAnimation*):
    # https://drafts.csswg.org/scroll-animations-1/#event-loop
    # When updating timeline current time, the start time of any attached animation is conditionally updated. For each
    # attached animation, run the procedure for calculating an auto-aligned start time.
    if animations_animation_has_progress_based_timeline(this):
        animations_animation_calculate_auto_aligned_start_time(this)

    # Prevent unnecessary work if the animation is already finished and can't exit the finished state due to timeline
    # changes
    var update = not this.m_is_finished
    if not update:
        let timeline = this.m_timeline else trap("a null timeline: m_timeline->is_monotonically_increasing()")
        update = not animations_animation_timeline_is_monotonically_increasing(timeline)
    if update:
        animations_animation_update_finished_state(this, AnimationsAnimationDidSeek.no, AnimationsAnimationSynchronouslyNotify.yes)

    # Act on the pending play or pause task
    if this.m_pending_play_task == AnimationsAnimationTaskState.scheduled and animations_animation_is_ready(this):
        this.m_pending_play_task = AnimationsAnimationTaskState.none_
        animations_animation_run_pending_play_task(this)

    if this.m_pending_pause_task == AnimationsAnimationTaskState.scheduled and animations_animation_is_ready_to_run_pending_pause_task(this):
        this.m_pending_pause_task = AnimationsAnimationTaskState.none_
        animations_animation_run_pending_pause_task(this)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1150 Web::Animations::Animation::effect_timing_changed.
pub func animations_animation_effect_timing_changed(this: AnimationsAnimation*):
    animations_animation_update_finished_state(this, AnimationsAnimationDidSeek.no, AnimationsAnimationSynchronouslyNotify.yes)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1156 Web::Animations::Animation::associated_effect_end.
# https://www.w3.org/TR/web-animations-1/#associated-effect-end
pub func animations_animation_associated_effect_end(this: AnimationsAnimation*) -> AnimationsTimeValue:
    # The associated effect end of an animation is equal to the end time of the animation’s associated effect. If the
    # animation has no associated effect, the associated effect end is zero.
    if let effect = this.m_effect:
        return animations_animation_effect_end_time(effect)
    return animations_time_value_create_zero(this.m_timeline)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1164 Web::Animations::Animation::effective_playback_rate (private).
# https://www.w3.org/TR/web-animations-1/#effective-playback-rate
func animations_animation_effective_playback_rate(this: AnimationsAnimation*) -> f64:
    # The effective playback rate of an animation is its pending playback rate, if set, otherwise it is the animation’s
    # playback rate.
    if let pending_playback_rate = this.m_pending_playback_rate:
        return pending_playback_rate
    return this.m_playback_rate

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1172 Web::Animations::Animation::apply_any_pending_playback_rate (private).
# https://www.w3.org/TR/web-animations-1/#apply-any-pending-playback-rate
func animations_animation_apply_any_pending_playback_rate(this: AnimationsAnimation*):
    # 1. If animation does not have a pending playback rate, abort these steps.
    let pending_playback_rate = this.m_pending_playback_rate else return

    # 2. Set animation’s playback rate to its pending playback rate.
    this.m_playback_rate = pending_playback_rate

    # 3. Clear animation’s pending playback rate.
    this.m_pending_playback_rate = none

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1186 Web::Animations::Animation::silently_set_current_time (private).
# https://www.w3.org/TR/web-animations-1/#animation-silently-set-the-current-time
func animations_animation_silently_set_current_time(this: AnimationsAnimation*, valid_seek_time: AnimationsTimeValue?) -> !:
    # 1. If seek time is an unresolved time value, then perform the following steps.
    if valid_seek_time == none:
        # 1. If the current time is resolved, then throw a TypeError.
        if animations_animation_current_time(this) != none:
            return try idl_throw_simple(IdlSimpleExceptionType.type_error, .string_view(ak.sv("Cannot change an animation's current time from a resolve value to an unresolved value")))

        # 2. Abort these steps.
        return
    let seek_time = valid_seek_time else trap("unreachable: checked above")

    # 2. Let valid seek time be the result of running the validate a CSSNumberish time procedure with seek time as the input.
    # 3. If valid seek time is false, abort this procedure.
    # AD-HOC: We have already validated in the caller.

    # 4. Set auto align start time to false.
    this.m_auto_align_start_time = false

    # 5. 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,
    var has_active_timeline = false
    if let timeline = this.m_timeline:
        has_active_timeline = not animations_animation_timeline_is_inactive(timeline)
    if this.m_hold_time != none or this.m_start_time == none or not has_active_timeline or this.m_playback_rate == 0.0:
        # Set animation’s hold time to seek time.
        this.m_hold_time = valid_seek_time
    # -> Otherwise,
    else:
        # 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.
        let timeline = this.m_timeline else trap("unreachable: checked above")
        let timeline_time = animations_animation_timeline_current_time(timeline) else trap("VERIFY: Optional::value()")
        this.m_start_time = animations_time_value_sub(timeline_time, animations_time_value_div(seek_time, this.m_playback_rate))

    # 6. If animation has no associated timeline or the associated timeline is inactive, make animation’s start time
    #    unresolved.
    if not has_active_timeline:
        this.m_start_time = none

    # 7. Make animation’s previous current time unresolved.
    this.m_previous_current_time = none

# mark: The finished state ======================================================================

## The captures of update_finished_state's finish notification steps: `[this, &realm]`.
struct AnimationsAnimationUpdateFinishedStateNotification:
    var this: AnimationsAnimation*
    var realm: Realm*

## The captures of the finish notification steps' queued dispatch: `[this, finish_event]`.
struct AnimationsAnimationUpdateFinishedStateDispatch:
    var this: AnimationsAnimation*
    var finish_event: AnimationsAnimationPlaybackEvent*

## The finish notification steps' task: dispatch finishEvent at the animation.
func animations_animation_update_finished_state_dispatch(context: void*?):
    let captures = (AnimationsAnimationUpdateFinishedStateDispatch*)(context else trap("no captures"))
    _ = dom_event_target_dispatch_event(captures.this.dom_event_target(), captures.finish_event.dom_event())

## update_finished_state's finish notification steps.
func animations_animation_update_finished_state_notification(context: void*?):
    let captures = (AnimationsAnimationUpdateFinishedStateNotification*)(context else trap("no captures"))
    let this = captures.this
    let realm = captures.realm

    # 1. If animation’s play state is not equal to finished, abort these steps.
    if animations_animation_play_state(this) != BindAnimationPlayState.finished:
        return

    # 2. Resolve animation’s current finished promise object with animation.
    idl_resolve_promise(realm, animations_animation_current_finished_promise(this), bind_platform_object_wrapper(this.bind_platform_object()))
    this.m_is_finished = true

    # 3. Create an AnimationPlaybackEvent, finishEvent.
    # 4. Set finishEvent’s type attribute to finish.
    # 5. Set finishEvent’s currentTime attribute to the current time of animation.
    # 6. Set finishEvent’s timelineTime attribute to the current time of the timeline with which animation is
    #    associated. If animation is not associated with a timeline, or the timeline is inactive, let
    #    timelineTime be null.
    var init = animations_animation_playback_event_init_new()
    let current_time = animations_animation_current_time(this) else trap("VERIFY: Optional::value()")
    init.current_time = animations_nullable_css_numberish_from_css_numberish(animations_time_value_as_css_numberish(current_time, realm))
    if let timeline = this.m_timeline:
        if not animations_animation_timeline_is_inactive(timeline):
            let timeline_time = animations_animation_timeline_current_time(timeline) else trap("VERIFY: Optional::value()")
            init.timeline_time = animations_nullable_css_numberish_from_css_numberish(animations_time_value_as_css_numberish(timeline_time, realm))

    let finish_event = animations_animation_playback_event_create(realm, html_event_names_finish, &init)

    # 7. If animation has a document for timing, then append finishEvent to its document for timing's pending
    #    animation event queue along with its target, animation. For the scheduled event time, use the result
    #    of converting animation’s associated effect end to an origin-relative time.
    if let document_for_timing = animations_animation_document_for_timing(this):
        dom_document_append_pending_animation_event(document_for_timing, DomDocumentPendingAnimationEvent(event = finish_event.dom_event(), animation = this, target = this.dom_event_target(), scheduled_event_time = animations_animation_convert_a_timeline_time_to_an_origin_relative_time(this, animations_animation_associated_effect_end(this))))
    #    Otherwise, queue a task to dispatch finishEvent at animation. The task source for this task is the DOM
    #    manipulation task source.
    else:
        # Manually create a task so its ID can be saved
        let document = html_window_associated_document(as_html_window((gc.Cell*)realm_global_object(realm)))
        let dispatch = new AnimationsAnimationUpdateFinishedStateDispatch(this = this, finish_event = finish_event) else trap("out of memory")
        let task = html_task_create(realm_vm(realm), HtmlTaskSource.dom_manipulation, document, gc.create_function0(gc.cell_heap(this.cell()), ak.Function0[unit](call = animations_animation_update_finished_state_dispatch, context = dispatch)))
        this.m_pending_finish_microtask_id = html_task_id(task)
        html_task_queue_add(html_event_loop_task_queue(html_main_thread_event_loop()), task)

## The captures of update_finished_state's queued microtask: `[finish_notification_steps, &realm]`.
struct AnimationsAnimationUpdateFinishedStateMicrotask:
    var finish_notification_steps: gc.Function0[unit]*
    var realm: Realm*

## update_finished_state's queued microtask: run the finish notification steps in a TemporaryExecutionContext.
func animations_animation_update_finished_state_microtask(context: void*?):
    let captures = (AnimationsAnimationUpdateFinishedStateMicrotask*)(context else trap("no captures"))
    var execution_context: HtmlTemporaryExecutionContext = ---
    html_temporary_execution_context_construct_realm(&execution_context, captures.realm)
    defer html_temporary_execution_context_destruct(&execution_context)
    ak.function0_call(&captures.finish_notification_steps.function)

## The predicate of update_finished_state's remove_tasks_matching: `task.id() == id`.
func animations_animation_task_has_id(context: void*?, task: HtmlTask*) -> bool:
    let id = (const (u64?)*)(context else trap("no captures"))
    return *id == html_task_id(task)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1239 Web::Animations::Animation::update_finished_state (private).
# https://www.w3.org/TR/web-animations-1/#update-an-animations-finished-state
func animations_animation_update_finished_state(this: AnimationsAnimation*, did_seek: AnimationsAnimationDidSeek, synchronously_notify: AnimationsAnimationSynchronouslyNotify):
    let realm = bind_platform_object_realm(this.bind_platform_object())

    # 1. Let the unconstrained current time be the result of calculating the current time substituting an unresolved
    #    time value for the hold time if did seek is false. If did seek is true, the unconstrained current time is
    #    equal to the current time.
    #
    # Note: This is required to accommodate timelines that may change direction. Without this definition, a once-
    #       finished animation would remain finished even when its timeline progresses in the opposite direction.
    var unconstrained_current_time: AnimationsTimeValue? = none
    if did_seek == AnimationsAnimationDidSeek.no:
        let saved_hold_time = this.m_hold_time
        this.m_hold_time = none
        unconstrained_current_time = animations_animation_current_time(this)
        this.m_hold_time = saved_hold_time
    else:
        unconstrained_current_time = animations_animation_current_time(this)

    # 2. If all three of the following conditions are true,
    #    - the unconstrained current time is resolved, and
    #    - animation’s start time is resolved, and
    #    - animation does not have a pending play task or a pending pause task,
    if let unconstrained = unconstrained_current_time:
        if this.m_start_time != none and not animations_animation_pending(this):
            # then update animation’s hold time based on the first matching condition for animation from below, if any:
            animations_animation_update_hold_time_when_finished(this, did_seek, unconstrained)

    # 3. Set the previous current time of animation be the result of calculating its current time.
    this.m_previous_current_time = animations_animation_current_time(this)

    # 4. Let current finished state be true if the play state of animation is finished. Otherwise, let it be false.
    let current_finished_state = animations_animation_play_state(this) == BindAnimationPlayState.finished

    # 5. If current finished state is true and the current finished promise is not yet resolved, perform the following
    #    steps:
    if current_finished_state and not this.m_is_finished:
        # 1. Let finish notification steps refer to the following procedure:
        let notification = new AnimationsAnimationUpdateFinishedStateNotification(this = this, realm = realm) else trap("out of memory")
        let finish_notification_steps = gc.create_function0(gc.cell_heap(this.cell()), ak.Function0[unit](call = animations_animation_update_finished_state_notification, context = notification))

        # 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.
        if synchronously_notify == AnimationsAnimationSynchronouslyNotify.yes:
            if this.m_pending_finish_microtask_id != none:
                # [id = move(m_pending_finish_microtask_id)]: the move leaves the member empty.
                var id = this.m_pending_finish_microtask_id
                this.m_pending_finish_microtask_id = none
                html_task_queue_remove_tasks_matching(html_event_loop_task_queue(html_main_thread_event_loop()), ak.Function1[HtmlTask*, bool](call = animations_animation_task_has_id, context = &id))
            ak.function0_call(&finish_notification_steps.function)
        #    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.
        elif this.m_pending_finish_microtask_id == none:
            let document = html_window_associated_document(as_html_window((gc.Cell*)realm_global_object(realm)))

            let microtask = new AnimationsAnimationUpdateFinishedStateMicrotask(finish_notification_steps = finish_notification_steps, realm = realm) else trap("out of memory")
            let task = html_task_create(realm_vm(realm), HtmlTaskSource.dom_manipulation, document, gc.create_function0(gc.cell_heap(this.cell()), ak.Function0[unit](call = animations_animation_update_finished_state_microtask, context = microtask)))

            this.m_pending_finish_microtask_id = html_task_id(task)
            html_task_queue_add(html_event_loop_task_queue(html_main_thread_event_loop()), task)

    # 6. If current finished state is false and animation’s current finished promise is already resolved, set
    #    animation’s current finished promise to a new promise in the relevant Realm of animation.
    if not current_finished_state and this.m_is_finished:
        this.m_current_finished_promise = idl_create_promise(realm)
        this.m_is_finished = false

    animations_animation_invalidate_effect(this)

## update_finished_state's step 2: update the hold time based on the first matching condition, if any.
func animations_animation_update_hold_time_when_finished(this: AnimationsAnimation*, did_seek: AnimationsAnimationDidSeek, unconstrained_current_time: AnimationsTimeValue):
    # -> If playback rate > 0 and unconstrained current time is greater than or equal to associated effect end,
    let associated_effect_end = animations_animation_associated_effect_end(this)
    if this.m_playback_rate > 0.0 and animations_time_value_ge(unconstrained_current_time, associated_effect_end):
        # If did seek is true, let the hold time be the value of unconstrained current time.
        if did_seek == AnimationsAnimationDidSeek.yes:
            this.m_hold_time = unconstrained_current_time
        # If did seek is false, let the hold time be the maximum value of previous current time and associated
        # effect end. If the previous current time is unresolved, let the hold time be associated effect end.
        elif let previous_current_time = this.m_previous_current_time:
            this.m_hold_time = animations_time_value_max(previous_current_time, associated_effect_end)
        else:
            this.m_hold_time = associated_effect_end
    # -> If playback rate < 0 and unconstrained current time is less than or equal to 0,
    elif this.m_playback_rate < 0.0 and unconstrained_current_time.value <= 0.0:
        # If did seek is true, let the hold time be the value of unconstrained current time.
        if did_seek == AnimationsAnimationDidSeek.yes:
            this.m_hold_time = unconstrained_current_time
        # If did seek is false, let the hold time be the minimum value of previous current time and zero. If the
        # previous current time is unresolved, let the hold time be zero.
        elif let previous_current_time = this.m_previous_current_time:
            this.m_hold_time = animations_time_value_min(previous_current_time, animations_time_value_create_zero(this.m_timeline))
        else:
            this.m_hold_time = animations_time_value_create_zero(this.m_timeline)
    # -> If playback rate ≠ 0, and animation is associated with an active timeline,
    elif this.m_playback_rate != 0.0 and animations_animation_has_active_timeline(this):
        # 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.
        if did_seek == AnimationsAnimationDidSeek.yes:
            if let hold_time = this.m_hold_time:
                let timeline = this.m_timeline else trap("unreachable: an active timeline")
                let timeline_time = animations_animation_timeline_current_time(timeline) else trap("VERIFY: Optional::value()")
                this.m_start_time = animations_time_value_sub(timeline_time, animations_time_value_div(hold_time, this.m_playback_rate))

        # 2. Let the hold time be unresolved.
        this.m_hold_time = none

## Whether the animation is associated with a timeline that is not inactive.
func animations_animation_has_active_timeline(this: AnimationsAnimation*) -> bool:
    let timeline = this.m_timeline else return false
    return not animations_animation_timeline_is_inactive(timeline)

# mark: Pending tasks ===========================================================================

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1401 Web::Animations::Animation::reset_an_animations_pending_tasks (private).
# https://www.w3.org/TR/web-animations-1/#animation-reset-an-animations-pending-tasks
func animations_animation_reset_an_animations_pending_tasks(this: AnimationsAnimation*):
    let realm = bind_platform_object_realm(this.bind_platform_object())

    # 1. If animation does not have a pending play task or a pending pause task, abort this procedure.
    if not animations_animation_pending(this):
        return

    # 2. If animation has a pending play task, cancel that task.
    this.m_pending_play_task = AnimationsAnimationTaskState.none_

    # 3. If animation has a pending pause task, cancel that task.
    this.m_pending_pause_task = AnimationsAnimationTaskState.none_

    # 4. Apply any pending playback rate on animation.
    animations_animation_apply_any_pending_playback_rate(this)

    # 5. Reject animation’s current ready promise with a DOMException named "AbortError".
    let dom_exception = idl_abort_error_create(realm, ak.utf16_string_from_str("Animation was cancelled"))
    idl_reject_promise(realm, animations_animation_current_ready_promise(this), bind_platform_object_wrapper(dom_exception.bind_platform_object()))

    # 6. Set the [[PromiseIsHandled]] internal slot of animation’s current ready promise to true.
    idl_mark_promise_as_handled(animations_animation_current_ready_promise(this))

    # 7. Let animation’s current ready promise be the result of creating a new resolved Promise object with value
    #    animation in the relevant Realm of animation.
    this.m_current_ready_promise = idl_create_resolved_promise(realm, bind_platform_object_wrapper(this.bind_platform_object()))

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1431 Web::Animations::Animation::is_ready (private).
# https://drafts.csswg.org/web-animations-2/#ready
func animations_animation_is_ready(this: AnimationsAnimation*) -> bool:
    # An animation is ready at the first moment where all of the following conditions are true:

    # FIXME: - the user agent has completed any setup required to begin the playback of each inclusive descendant of
    #          the animation’s associated effect including rendering the first frame of any keyframe effect or
    #          executing any custom effects associated with an animation effect

    # - the animation is associated with a timeline that is not inactive.
    if not animations_animation_has_active_timeline(this):
        return false

    # - the animation’s hold time or start time is resolved.
    if this.m_hold_time == none and this.m_start_time == none:
        return false

    return true

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1451 Web::Animations::Animation::run_pending_play_task (private).
# Step 12 of https://www.w3.org/TR/web-animations-1/#playing-an-animation-section
func animations_animation_run_pending_play_task(this: AnimationsAnimation*):
    # 1. Assert that at least one of animation’s start time or hold time is resolved.
    assert(this.m_start_time != none or this.m_hold_time != none)

    # 2. Let ready time be the time value of the timeline associated with animation at the moment when animation became
    #    ready.
    # FIXME: We can get a more accurate time here if we record the actual instant we became ready rather than waiting
    #        to try and run this task
    let timeline = this.m_timeline else trap("a null timeline: m_timeline->current_time()")
    let ready_time = animations_animation_timeline_current_time(timeline) else trap("VERIFY: Optional::value()")

    # 3. Perform the steps corresponding to the first matching condition below, if any:

    # -> If animation’s hold time is resolved,
    if let hold_time = this.m_hold_time:
        # 1. Apply any pending playback rate on animation.
        animations_animation_apply_any_pending_playback_rate(this)

        # 2. Let new start time be the result of evaluating ready time - hold time / playback rate for animation. If
        #    the playback rate is zero, let new start time be simply ready time.
        let new_start_time = animations_time_value_sub(ready_time, animations_time_value_div(hold_time, this.m_playback_rate)) if this.m_playback_rate != 0.0 else ready_time

        # 3. Set the start time of animation to new start time.
        this.m_start_time = new_start_time

        # 4. If animation’s playback rate is not 0, make animation’s hold time unresolved.
        if this.m_playback_rate != 0.0:
            this.m_hold_time = none
    # -> If animation’s start time is resolved and animation has a pending playback rate,
    elif this.m_start_time != none and this.m_pending_playback_rate != none:
        let start_time = this.m_start_time else trap("unreachable: checked above")
        # 1. Let current time to match be the result of evaluating (ready time - start time) × playback rate for
        #    animation.
        let current_time_to_match = animations_time_value_mul(animations_time_value_sub(ready_time, start_time), this.m_playback_rate)

        # 2. Apply any pending playback rate on animation.
        animations_animation_apply_any_pending_playback_rate(this)

        # 3. If animation’s playback rate is zero, let animation’s hold time be current time to match.
        if this.m_playback_rate == 0.0:
            this.m_hold_time = current_time_to_match

        # 4. Let new start time be the result of evaluating ready time - current time to match / playback rate for
        #    animation. If the playback rate is zero, let new start time be simply ready time.
        let new_start_time = animations_time_value_sub(ready_time, animations_time_value_div(current_time_to_match, this.m_playback_rate)) if this.m_playback_rate != 0.0 else ready_time

        # 5. Set the start time of animation to new start time.
        this.m_start_time = new_start_time

    # 4. Resolve animation’s current ready promise with animation.
    idl_resolve_promise(bind_platform_object_realm(this.bind_platform_object()), animations_animation_current_ready_promise(this), bind_platform_object_wrapper(this.bind_platform_object()))

    # 5. 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.
    animations_animation_update_finished_state(this, AnimationsAnimationDidSeek.no, AnimationsAnimationSynchronouslyNotify.no)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1509 Web::Animations::Animation::is_ready_to_run_pending_pause_task (private).
func animations_animation_is_ready_to_run_pending_pause_task(this: AnimationsAnimation*) -> bool:
    # NB: Step 10 of the procedure to "pause an animation" requires us to schedule the pending pause task to run when
    #     the following conditions are true:

    # https://www.w3.org/TR/web-animations-1/#pause-an-animation
    # https://drafts.csswg.org/web-animations-2/#pausing-an-animation-section
    # FIXME: - the user agent has performed any processing necessary to suspend the playback of animation’s associated
    #       effect, if any.

    # - the animation is associated with a timeline that is not inactive.
    if not animations_animation_has_active_timeline(this):
        return false

    # - the animation has a resolved hold time or start time.
    if this.m_hold_time == none and this.m_start_time == none:
        return false

    return true

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1531 Web::Animations::Animation::run_pending_pause_task (private).
# Step 10 of https://www.w3.org/TR/web-animations-1/#pause-an-animation
func animations_animation_run_pending_pause_task(this: AnimationsAnimation*):
    # 1. Let ready time be the time value of the timeline associated with animation at the moment when the user agent
    #    completed processing necessary to suspend playback of animation’s associated effect.
    # FIXME: We can get a more accurate time here if we record the actual instant the above is true rather than waiting
    #        for this task to run
    let timeline = this.m_timeline else trap("a null timeline: m_timeline->current_time()")
    let ready_time = animations_animation_timeline_current_time(timeline) else trap("VERIFY: Optional::value()")

    # 2. 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 has a pending play
    #       task. In either case we want to preserve the hold time as we enter the paused state.
    if let start_time = this.m_start_time:
        if this.m_hold_time == none:
            this.m_hold_time = animations_time_value_mul(animations_time_value_sub(ready_time, start_time), this.m_playback_rate)

    # 3. Apply any pending playback rate on animation.
    animations_animation_apply_any_pending_playback_rate(this)

    # 4. Make animation’s start time unresolved.
    this.m_start_time = none

    # 5. Resolve animation’s current ready promise with animation.
    idl_resolve_promise(bind_platform_object_realm(this.bind_platform_object()), animations_animation_current_ready_promise(this), bind_platform_object_wrapper(this.bind_platform_object()))

    # 6. 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.
    animations_animation_update_finished_state(this, AnimationsAnimationDidSeek.no, AnimationsAnimationSynchronouslyNotify.no)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1560 Web::Animations::Animation::current_ready_promise (private).
func animations_animation_current_ready_promise(this: AnimationsAnimation*) -> JsPromiseCapability*:
    if this.m_current_ready_promise == none:
        # The current ready promise is initially a resolved Promise created using the procedure to create a new
        # resolved Promise with the animation itself as its value and created in the relevant Realm of the animation.
        this.m_current_ready_promise = idl_create_resolved_promise(bind_platform_object_realm(this.bind_platform_object()), bind_platform_object_wrapper(this.bind_platform_object()))

    return this.m_current_ready_promise else trap("unreachable: set above")

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1571 Web::Animations::Animation::current_finished_promise (private).
func animations_animation_current_finished_promise(this: AnimationsAnimation*) -> JsPromiseCapability*:
    if this.m_current_finished_promise == none:
        # The current finished promise is initially a pending Promise object.
        this.m_current_finished_promise = idl_create_promise(bind_platform_object_realm(this.bind_platform_object()))

    return this.m_current_finished_promise else trap("unreachable: set above")

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1581 Web::Animations::Animation::invalidate_effect (private).
func animations_animation_invalidate_effect(this: AnimationsAnimation*):
    let effect = this.m_effect else return

    if let target = animations_animation_effect_target(effect):
        dom_document_set_needs_animated_style_update(dom_node_document(target.dom_node()))

# mark: Construction and edges ==================================================================

## Animation's `static unsigned int next_animation_list_order` (in its constructor).
var animations_animation_next_animation_list_order: u32 = 0

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1591 Web::Animations::Animation::Animation (protected).
pub func animations_animation_construct(this: AnimationsAnimation*, realm: Realm*):
    # The C++ default member initializers.
    this.m_playback_rate = 1.0
    this.m_replace_state = BindAnimationReplaceState.active
    this.m_pending_play_task = AnimationsAnimationTaskState.none_
    this.m_pending_pause_task = AnimationsAnimationTaskState.none_

    dom_event_target_construct(this.dom_event_target(), realm)
    this.m_global_animation_list_order = animations_animation_next_animation_list_order
    animations_animation_next_animation_list_order +%= 1

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1597 Web::Animations::Animation::initialize (override).
pub func animations_animation_initialize_impl(base: JsCell*, realm: Realm*):
    web_set_prototype_for_interface(base, realm, BindInterfaceName.animation)
    dom_event_target_initialize_impl(base, realm)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1603 Web::Animations::Animation::visit_edges (override).
pub func animations_animation_visit_edges_impl(base: gc.Cell*, visitor: gc.CellVisitor*):
    let this = (AnimationsAnimation*)base
    dom_event_target_visit_edges_impl(base, visitor)
    gc.cell_visitor_visit_t(visitor, this.m_effect)
    gc.cell_visitor_visit_t(visitor, this.m_timeline)
    gc.cell_visitor_visit_t(visitor, this.m_current_ready_promise)
    gc.cell_visitor_visit_t(visitor, this.m_current_finished_promise)
    if let owning_element = this.m_owning_element:
        dom_abstract_element_visit(&owning_element, visitor)

## Ported from Libraries/LibWeb/Animations/Animation.cpp:1614 Web::Animations::Animation::finalize (override).
pub func animations_animation_finalize_impl(base: gc.Cell*):
    let this = (AnimationsAnimation*)base
    gc.cell_finalize_impl(base)
    if let timeline = this.m_timeline:
        animations_animation_timeline_disassociate_with_animation(timeline, this)