[video_player_web] Fix blank first frame on iOS. (flutter#9025)

Fixes [First Frame of Video Once VideoPlayer Controller doesn't show in iOS Safari/Chrome](flutter/flutter#139107)

This PR fixes the blank first frame issue by adding a `_videoElement.load()` call at the end of the `initialize` function. This call forces the browser to load media in preparation for playback (https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/load).

Additionally, this PR removes `loadedmetadata` event listener, as the `canplay` event is now reliably emitted across all platforms. Keeping `loadedmetadata` listener could result in marking the video controller as initialized before the first frame is actually rendered. This causes the loader to disappear too early, leaving a blank space where the video should be until the browser displays the first frame. Relying on `canplay` ensures the first frame is ready before we proceed.

> [!NOTE]
> It turns out that this issue is iOS-specific and was reported not only in Flutter, but in some other packages and tools:
> 1) [video-react/First frame not shown as the poster on iOS Safari](video-react/video-react#328)
> 2) [WordPress/gutenberg/Video Block: First frame not shown as the poster on iOS Safari — Fix: Use Fragment URL](WordPress/gutenberg#51995)

> [!TIP]
> As a temporary workaround until this PR is merged, users can append the `#t=0.001` fragment to the asset or URL `src` to force the browser to load the first frame (e.g., `assets/butterfly.mp4#t=0.001`, `https://flutter.github.io/assets-for-api-docs/assets/videos/butterfly.mp4#t=0.001`).

The following repository was used for issue reproduction and testing: https://github.com/ksokolovskyi/video_player_blank_frame_bug

| Before | After |
| :---: | :---: |
| https://video-player-blank-frame-bug.web.app | https://video-player-blank-frame-fix.web.app |
| <video src="https://github.com/user-attachments/assets/4077fcc4-10cf-4dbd-8c59-2fd824b4e4c4" /> | <video src="https://github.com/user-attachments/assets/2951af36-1569-4a5c-90dd-1d52a5d1e7f2" /> |

## Pre-Review Checklist

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: ksokolovskyi

packages/video_player/video_player_web/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.3.5
+
+* Fixes blank first frame on iOS.
+
 ## 2.3.4
 
 * Adjusts the code to the new platform interface.

packages/video_player/video_player_web/example/integration_test/video_player_test.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 import 'dart:async';
+import 'dart:js_interop';
+import 'dart:js_interop_unsafe';
 
 import 'package:flutter_test/flutter_test.dart';
 import 'package:integration_test/integration_test.dart';
@@ -27,6 +29,18 @@ void main() {
         ..playsInline = false;
     });
 
+    testWidgets('initialize() calls load', (WidgetTester _) async {
+      bool loadCalled = false;
+
+      video['load'] = () {
+        loadCalled = true;
+      }.toJS;
+
+      VideoPlayer(videoElement: video).initialize();
+
+      expect(loadCalled, isTrue);
+    });
+
     testWidgets('fixes critical video element config', (WidgetTester _) async {
       VideoPlayer(videoElement: video).initialize();
 
@@ -130,6 +144,11 @@ void main() {
         );
       });
 
+      tearDown(() {
+        streamController.close();
+        player.dispose();
+      });
+
       testWidgets('buffering dispatches only when it changes',
           (WidgetTester tester) async {
         // Take all the "buffering" events that we see during the next few seconds
@@ -222,8 +241,7 @@ void main() {
         expect(events[0].eventType, VideoEventType.initialized);
       });
 
-      // Issue: https://github.com/flutter/flutter/issues/137023
-      testWidgets('loadedmetadata dispatches initialized',
+      testWidgets('loadedmetadata does not dispatch initialized',
           (WidgetTester tester) async {
         video.dispatchEvent(web.Event('loadedmetadata'));
         video.dispatchEvent(web.Event('loadedmetadata'));
@@ -235,8 +253,22 @@ void main() {
 
         final List<VideoEvent> events = await stream;
 
-        expect(events, hasLength(1));
-        expect(events[0].eventType, VideoEventType.initialized);
+        expect(events, isEmpty);
+      });
+
+      testWidgets('loadeddata does not dispatch initialized',
+          (WidgetTester tester) async {
+        video.dispatchEvent(web.Event('loadeddata'));
+        video.dispatchEvent(web.Event('loadeddata'));
+
+        final Future<List<VideoEvent>> stream = timedStream
+            .where((VideoEvent event) =>
+                event.eventType == VideoEventType.initialized)
+            .toList();
+
+        final List<VideoEvent> events = await stream;
+
+        expect(events, isEmpty);
       });
 
       // Issue: https://github.com/flutter/flutter/issues/105649

packages/video_player/video_player_web/lib/src/video_player.dart

@@ -77,8 +77,6 @@ class VideoPlayer {
       ..playsInline = true;
 
     _videoElement.onCanPlay.listen(_onVideoElementInitialization);
-    // Needed for Safari iOS 17, which may not send `canplay`.
-    _videoElement.onLoadedMetadata.listen(_onVideoElementInitialization);
 
     _videoElement.onCanPlayThrough.listen((dynamic _) {
       setBuffering(false);
@@ -131,6 +129,10 @@ class VideoPlayer {
     if (src != null) {
       _videoElement.src = src;
     }
+
+    // Explicitly triggers media loading in preparation for playback. Needed on
+    // iOS to ensure the first frame becomes visible before playback begins.
+    _videoElement.load();
   }
 
   /// Attempts to play the video.

packages/video_player/video_player_web/pubspec.yaml

@@ -2,7 +2,7 @@ name: video_player_web
 description: Web platform implementation of video_player.
 repository: https://github.com/flutter/packages/tree/main/packages/video_player/video_player_web
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+video_player%22
-version: 2.3.4
+version: 2.3.5
 
 environment:
   sdk: ^3.4.0