Implement CSS animation play state (#665) (#670)

Author: wieslawsoltes

docs/validation/css-animation-play-state-665-242.md

@@ -0,0 +1,55 @@
+# CSS animation play-state source validation
+
+Issue #665 adds bounded `animation-play-state` behavior to WebScene's existing
+single-animation opacity, `rotate()`, and compatible foreground-filter keyframe
+runtime under #242. The first longhand list item and first shorthand animation
+accept `running` or `paused`. `animationPlayState`, the kebab-case CSSOM name,
+`getPropertyValue("animation-play-state")`, shorthand serialization, mutation,
+and clearing expose the retained value without an ABI or AppScene change.
+
+## Held timeline contract
+
+Play state remains outside keyframe identity. A running-to-paused mutation stores
+one bounded host timestamp on the node's existing animation runtime. Opacity,
+rotation, and filter tracks sample that held timestamp, so positive delay remains
+in its fill-aware before phase and negative delay immediately exposes its active
+or terminal sample. No timer or background clock advances the hold.
+
+On resume, unchanged active track origins move forward once by the elapsed held
+host duration. Their effective progress therefore continues from the held sample
+without rebuilding keyframes or restarting the animation. If supported keyframe
+identity changes while paused, changed tracks retain the established restart
+behavior while unchanged active tracks preserve their held progress.
+
+A terminal sample reached while paused remains held and cannot dispatch
+`animationend`; resume performs the existing finite completion path. The shared
+end latch still dispatches at most once. Completed fill remains settled. Removal,
+node detach, document replacement, navigation, and engine teardown discard the
+node-owned hold with the established animation runtime lifecycle.
+
+## Scheduling and bounds
+
+- Paused keyframes are excluded from `has_active_animations()`, including delay
+  and active phases. A play-state mutation can publish its held sample once, but
+  does not sustain host-frame demand.
+- Resume uses the existing visibility and paint-area gates. Opacity, rotation,
+  and filters remain paint-only and do not add selector, cascade, layout, scene
+  node, queue, or per-frame allocation work.
+- The runtime still configures one animation and the first coordinated-list item.
+  Existing duration, iteration, keyframe-stop, and filter-list bounds remain.
+- Zero-duration/zero-count behavior, multiple animations, translate/scale,
+  pseudo-elements, additional animation events, and Web Animations playback APIs
+  remain deferred.
+
+## Evidence
+
+- `test_animation_play_state_holds_and_resumes_host_time` covers shorthand and
+  longhand metadata, CSSOM mutation/clear, positive and negative delay, reverse
+  opacity/rotation/filter samples, hold stability, resumed continuity, terminal
+  fill, exactly-once `animationend`, detach, and settled frame demand.
+- `tests/WebPlatformSubset/contracts/css-animation-play-state.html` is a bounded
+  WPT-aligned browser contract for the same observable boundaries. Its dedicated
+  profile selects only that contract.
+- Under the fast implementation policy, only `git diff --check` is executed.
+  Native, browser, package, idle, and unchanged Code OSS acceptance remain
+  unexecuted.

experiments/WebScene.NativeEngine.Probe/native/webscene_css_decoration_values.h

@@ -187,6 +187,11 @@ bool apply_decoration_value(dom_node& node,const std::string& name,const std::st
             decision.semantic_slice =
                 "first animation; none, forwards, backwards, both";
             return true;
+        } else if (name == "animation-play-state") {
+            node.style.mutable_animations().animation_play_state_value = value;
+            decision.classification = "partially-supported";
+            decision.semantic_slice = "first animation; running, paused";
+            return true;
         } else if (property_mask(name) == inline_border
             && is_inline(inline_border)) {
             return true;

experiments/WebScene.NativeEngine.Probe/native/webscene_css_specified_coverage.h

@@ -44,6 +44,7 @@ inline constexpr auto specified_property_samples = std::to_array<specified_prope
     {"animation-delay","100ms"},{"animation-timing-function","ease-in-out"},{"animation-iteration-count","infinite"},
     {"animation-direction","alternate-reverse"},
     {"animation-fill-mode","both"},
+    {"animation-play-state","paused"},
     {"box-shadow","1px 2px 3px 4px rgba(0,0,0,.5)"},
     {"background","#123456"},{"background-color","rgba(1,2,3,.5)"},
     {"background-image","linear-gradient(90deg, red, blue)"},{"background-repeat","no-repeat"},

experiments/WebScene.NativeEngine.Probe/native/webscene_css_transitions.h

@@ -256,6 +256,7 @@ inline void apply_animation_shorthand(node_style& style, const std::string& valu
         auto iterations = std::string("1");
         auto direction = std::string("normal");
         auto fill_mode = std::string("none");
+        auto play_state = std::string("running");
         auto saw_time = false;
         const auto first = split_css_component_list(value, ',');
         for (const auto& token : split_value_tokens(
@@ -278,9 +279,10 @@ inline void apply_animation_shorthand(node_style& style, const std::string& valu
             } else if (lower == "normal" || lower == "reverse"
                 || lower == "alternate" || lower == "alternate-reverse") {
                 direction = lower;
+            } else if (lower == "running" || lower == "paused") {
+                play_state = lower;
             } else if (lower != "none"
-                && lower != "backwards"
-                && lower != "running" && lower != "paused") {
+                && lower != "backwards") {
                 name = token;
             }
         }
@@ -292,6 +294,7 @@ inline void apply_animation_shorthand(node_style& style, const std::string& valu
         animations.animation_iteration_count_value = iterations;
         animations.animation_direction_value = direction;
         animations.animation_fill_mode_value = fill_mode;
+        animations.animation_play_state_value = play_state;
     }
 
 inline void configure_keyframes(node_style& style,
@@ -305,6 +308,13 @@ inline void configure_keyframes(node_style& style,
         animations.rotation_keyframe_animation_signature.clear();
         animations.filter_keyframes.clear();
         animations.filter_keyframe_animation_signature.clear();
+        const auto play_states = split_css_component_list(
+            animations.animation_play_state_value, ',');
+        const auto play_state = play_states.empty()
+            ? std::string("running") : ascii_lower(trim_value(play_states.front()));
+        animations.keyframe_play_state = play_state == "paused"
+            ? node_style::animation_data::play_kind::paused
+            : node_style::animation_data::play_kind::running;
         if (animations.animation_name_value == "none") return;
         const auto names = split_css_component_list(animations.animation_name_value, ',');
         if (names.empty()) return;

experiments/WebScene.NativeEngine.Probe/native/webscene_native_dom.h

@@ -211,6 +211,10 @@ struct node_style final {
             backwards,
             both
         };
+        enum class play_kind : uint8_t {
+            running,
+            paused
+        };
         std::string transition_property_value{"all"};
         std::string transition_duration_value{"0s"};
         std::string transition_delay_value{"0s"};
@@ -229,6 +233,7 @@ struct node_style final {
         std::string animation_iteration_count_value{"1"};
         std::string animation_direction_value{"normal"};
         std::string animation_fill_mode_value{"none"};
+        std::string animation_play_state_value{"running"};
         std::string opacity_keyframe_animation_signature;
         std::vector<opacity_keyframe> opacity_keyframes;
         std::string rotation_keyframe_animation_signature;
@@ -240,6 +245,7 @@ struct node_style final {
         float opacity_keyframe_iterations{1};
         direction_kind keyframe_direction{direction_kind::normal};
         fill_kind keyframe_fill_mode{fill_kind::none};
+        play_kind keyframe_play_state{play_kind::running};
         float opacity_keyframe_x1{0.25F};
         float opacity_keyframe_y1{0.1F};
         float opacity_keyframe_x2{0.25F};
@@ -1530,6 +1536,8 @@ struct dom_node final {
         bool filter_keyframe_animation_filled{false};
         node_style::animation_data::fill_kind keyframe_fill_mode{
             node_style::animation_data::fill_kind::none};
+        bool keyframe_animation_paused{false};
+        double keyframe_animation_paused_at_ms{0};
         bool keyframe_animation_end_event_sent{false};
         uint32_t painted_foreground_rgba{0};
         uint32_t color_animation_from_rgba{0};

experiments/WebScene.NativeEngine.Probe/native/webscene_native_dom_animations.inc

@@ -259,6 +259,16 @@ void native_document::update_style_animations(dom_node& node)
             != node.style.animations().filter_keyframe_animation_signature;
     const auto fill_mode_changed = animation.keyframe_fill_mode
         != node.style.animations().keyframe_fill_mode;
+    const auto has_configured_keyframes =
+        !node.style.animations().opacity_keyframe_animation_signature.empty()
+        || !node.style.animations().rotation_keyframe_animation_signature.empty()
+        || !node.style.animations().filter_keyframe_animation_signature.empty();
+    const auto desired_keyframe_pause = has_configured_keyframes
+        && node.style.animations().keyframe_play_state
+            == node_style::animation_data::play_kind::paused;
+    const auto was_keyframe_paused = animation.keyframe_animation_paused;
+    const auto previous_pause_timestamp =
+        animation.keyframe_animation_paused_at_ms;
     animation.keyframe_fill_mode = node.style.animations().keyframe_fill_mode;
     if (opacity_keyframe_changed || rotation_keyframe_changed
         || filter_keyframe_changed) {
@@ -366,6 +376,32 @@ void native_document::update_style_animations(dom_node& node)
                 animation.filter_keyframe_animation_valid;
         }
     }
+    const auto keyframe_identity_changed = opacity_keyframe_changed
+        || rotation_keyframe_changed || filter_keyframe_changed;
+    if (was_keyframe_paused
+        && (!desired_keyframe_pause || keyframe_identity_changed)) {
+        const auto held_duration = std::max(
+            0.0, animation_frame_timestamp_ms_ - previous_pause_timestamp);
+        if (!opacity_keyframe_changed
+            && animation.opacity_keyframe_animation_active) {
+            animation.opacity_keyframe_animation_started_ms += held_duration;
+        }
+        if (!rotation_keyframe_changed
+            && animation.rotation_keyframe_animation_active) {
+            animation.rotation_keyframe_animation_started_ms += held_duration;
+        }
+        if (!filter_keyframe_changed
+            && animation.filter_keyframe_animation_active) {
+            animation.filter_keyframe_animation_started_ms += held_duration;
+        }
+    }
+    animation.keyframe_animation_paused = desired_keyframe_pause;
+    if (desired_keyframe_pause
+        && (!was_keyframe_paused || keyframe_identity_changed)) {
+        animation.keyframe_animation_paused_at_ms = animation_frame_timestamp_ms_;
+    } else if (!has_configured_keyframes) {
+        animation.keyframe_animation_paused_at_ms = 0;
+    }
 
     if (animation.opacity_animation_active && node.style.animations().transition_property_value == "none") {
         transition_events_.push_back({node.id,"transitioncancel","opacity",
@@ -1052,6 +1088,9 @@ bool native_document::advance_animations() noexcept
         }
 
         auto keyframe_animation_completed = false;
+        const auto keyframe_timestamp_ms = animation.keyframe_animation_paused
+            ? animation.keyframe_animation_paused_at_ms
+            : animation_frame_timestamp_ms_;
         if (animation.opacity_keyframe_animation_active) {
             const auto sample_opacity = [&](float cycle_progress) {
                 const auto& stops = node.style.animations().opacity_keyframes;
@@ -1084,7 +1123,7 @@ bool native_document::advance_animations() noexcept
                 }
             };
             const auto elapsed_ms = static_cast<float>(
-                animation_frame_timestamp_ms_
+                keyframe_timestamp_ms
                 - animation.opacity_keyframe_animation_started_ms
                 - node.style.animations().opacity_keyframe_delay_ms);
             if (elapsed_ms < 0) {
@@ -1110,8 +1149,10 @@ bool native_document::advance_animations() noexcept
                     } else {
                         animation.painted_opacity = node.style.opacity;
                     }
-                    animation.opacity_keyframe_animation_active = false;
-                    keyframe_animation_completed = true;
+                    if (!animation.keyframe_animation_paused) {
+                        animation.opacity_keyframe_animation_active = false;
+                        keyframe_animation_completed = true;
+                    }
                     advanced = advanced || keyframe_paint_visible;
                 } else {
                     sample_opacity(active_keyframe_progress(
@@ -1154,7 +1195,7 @@ bool native_document::advance_animations() noexcept
                 }
             };
             const auto elapsed_ms = static_cast<float>(
-                animation_frame_timestamp_ms_
+                keyframe_timestamp_ms
                 - animation.rotation_keyframe_animation_started_ms
                 - node.style.animations().opacity_keyframe_delay_ms);
             if (elapsed_ms < 0) {
@@ -1184,8 +1225,10 @@ bool native_document::advance_animations() noexcept
                             node.style.transform_rotate_degrees;
                         animation.rotation_keyframe_animation_filled = false;
                     }
-                    animation.rotation_keyframe_animation_active = false;
-                    keyframe_animation_completed = true;
+                    if (!animation.keyframe_animation_paused) {
+                        animation.rotation_keyframe_animation_active = false;
+                        keyframe_animation_completed = true;
+                    }
                     advanced = advanced || keyframe_paint_visible;
                 } else {
                     sample_rotation(active_keyframe_progress(
@@ -1242,7 +1285,7 @@ bool native_document::advance_animations() noexcept
                 }
             };
             const auto elapsed_ms = static_cast<float>(
-                animation_frame_timestamp_ms_
+                keyframe_timestamp_ms
                 - animation.filter_keyframe_animation_started_ms
                 - node.style.animations().opacity_keyframe_delay_ms);
             if (elapsed_ms < 0) {
@@ -1272,8 +1315,10 @@ bool native_document::advance_animations() noexcept
                             animation.filter_keyframe_underlying;
                         animation.filter_keyframe_animation_filled = false;
                     }
-                    animation.filter_keyframe_animation_active = false;
-                    keyframe_animation_completed = true;
+                    if (!animation.keyframe_animation_paused) {
+                        animation.filter_keyframe_animation_active = false;
+                        keyframe_animation_completed = true;
+                    }
                     advanced = advanced || keyframe_paint_visible;
                 } else {
                     sample_filter(active_keyframe_progress(
@@ -1344,7 +1389,8 @@ bool native_document::has_active_animations() const noexcept
             || animation->rotation_keyframe_animation_active
             || animation->filter_keyframe_animation_active;
         return transition_active
-            || (keyframe_active && intersects_visible_paint_area(*node));
+            || (keyframe_active && !animation->keyframe_animation_paused
+                && intersects_visible_paint_area(*node));
     });
     active_animation_demand_cache_valid_ = true;
     return active_animation_demand_cache_;

experiments/WebScene.NativeEngine.Probe/native/webscene_v8_runtime_style.inc

@@ -290,6 +290,8 @@
             node.style.mutable_animations().animation_direction_value = "normal";
         } else if (name == "animationFillMode" || name == "animation-fill-mode") {
             node.style.mutable_animations().animation_fill_mode_value = "none";
+        } else if (name == "animationPlayState" || name == "animation-play-state") {
+            node.style.mutable_animations().animation_play_state_value = "running";
         } else if (name == "animation" || name == "animationName"
             || name == "animation-name" || name == "animationDuration"
             || name == "animation-duration" || name == "animationDelay"
@@ -304,6 +306,7 @@
             animations.animation_iteration_count_value = "1";
             animations.animation_direction_value = "normal";
             animations.animation_fill_mode_value = "none";
+            animations.animation_play_state_value = "running";
         } else if (name == "opacity") {
             node.style.opacity = 1;
             node.style.inline_property_mask &= ~inline_opacity;
@@ -1437,6 +1440,8 @@
                 value = node->style.animations().transition_timing_function_value;
             } else if (name == "animation-fill-mode") {
                 value = node->style.animations().animation_fill_mode_value;
+            } else if (name == "animation-play-state") {
+                value = node->style.animations().animation_play_state_value;
             } else if (name == "opacity") {
                 value = serialize_css_number(node->painted_opacity_value());
             } else if (name == "color") {
@@ -2046,7 +2051,8 @@
                 + node->style.animations().animation_delay_value + " "
                 + node->style.animations().animation_iteration_count_value + " "
                 + node->style.animations().animation_direction_value + " "
-                + node->style.animations().animation_fill_mode_value;
+                + node->style.animations().animation_fill_mode_value + " "
+                + node->style.animations().animation_play_state_value;
         } else if (name == "animationName" || name == "animation-name") {
             value = node->style.animations().animation_name_value;
         } else if (name == "animationDuration" || name == "animation-duration") {
@@ -2063,6 +2069,8 @@
             value = node->style.animations().animation_direction_value;
         } else if (name == "animationFillMode" || name == "animation-fill-mode") {
             value = node->style.animations().animation_fill_mode_value;
+        } else if (name == "animationPlayState" || name == "animation-play-state") {
+            value = node->style.animations().animation_play_state_value;
         } else if (name == "zIndex") {
             value = node->style.z_index_auto
                 ? "auto" : std::to_string(node->style.z_index);
@@ -2576,6 +2584,8 @@
             node->style.mutable_animations().animation_direction_value = value;
         } else if (name == "animationFillMode") {
             node->style.mutable_animations().animation_fill_mode_value = value;
+        } else if (name == "animationPlayState") {
+            node->style.mutable_animations().animation_play_state_value = value;
         } else if (name == "opacity") {
             node->style.opacity = raw_value->IsNullOrUndefined()
                 ? 1.0F