fix(player): 使用雪碧图预热首帧兜底

lib/pages/player/widgets/home_feed_overlay.dart

@@ -217,7 +217,6 @@ class _HomeFeedOverlayState extends State<HomeFeedOverlay> {
               spriteAxisService: widget.spriteAxisService,
               thumbnailsUrl: widget.episode.thumbnailsUrl,
               episodeId: widget.episode.id,
-              posterUrl: widget.drama.posterUrl,
               onScrubStart: _startScrub,
               onScrubEnd: _endScrub,
               onSeek: widget.onSeek,

lib/pages/player/widgets/home_feed_overlay_parts.dart

@@ -23,7 +23,6 @@ class _FeedProgressBar extends StatefulWidget {
     this.spriteAxisService,
     this.thumbnailsUrl,
     this.episodeId,
-    this.posterUrl = '',
     this.onScrubStart,
     this.onScrubEnd,
     this.onSeek,
@@ -38,7 +37,6 @@ class _FeedProgressBar extends StatefulWidget {
   final SpriteThumbnailAxisSource? spriteAxisService;
   final String? thumbnailsUrl;
   final String? episodeId;
-  final String posterUrl;
   final VoidCallback? onScrubStart;
   final VoidCallback? onScrubEnd;
   final ValueChanged<Duration>? onSeek;
@@ -166,7 +164,6 @@ class _FeedProgressBarState extends State<_FeedProgressBar> {
                       spriteAxisService: widget.spriteAxisService,
                       thumbnailsUrl: widget.thumbnailsUrl,
                       episodeId: widget.episodeId!,
-                      posterUrl: widget.posterUrl,
                       position: previewPosition,
                       duration: video!.duration,
                     ),

lib/pages/player/widgets/player_opening_frame.dart

@@ -1,199 +1,97 @@
 // Author: fruit.com.cn
 
 import 'dart:async';
-import 'dart:ui' as ui;
 
 import 'package:flutter/material.dart';
 
-import '../../../core/config/app_config.dart';
-import '../../../core/data/services/sprite_thumbnail_asset_loader.dart';
 import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../core/theme/app_colors.dart';
-import '../../../core/widgets/remote_image.dart';
 import 'scrub_preview_card.dart';
 
-/// 封面立即可见，雪碧图首帧解码完成后再覆盖封面。
+/// 当前集雪碧图首帧在视频纹理未就绪时占位；空地址交还纯黑底。
 Widget? playerOpeningFrame(
   String? thumbnailsUrl, {
-  String? posterUrl,
+  required SpriteThumbnailAxisSource spriteSource,
   BoxFit fit = BoxFit.cover,
 }) {
   final url = thumbnailsUrl?.trim() ?? '';
-  final poster = posterUrl?.trim() ?? '';
-  if (url.isEmpty && poster.isEmpty) return null;
+  if (url.isEmpty) return null;
   return PlayerOpeningFrame(
-    thumbnailsUrl: url.isEmpty ? null : url,
-    posterUrl: poster.isEmpty ? null : poster,
+    thumbnailsUrl: url,
+    spriteSource: spriteSource,
     fit: fit,
   );
 }
 
-/// 视频解码前依次使用封面和雪碧图首帧，最终由父层黑色兜底。
+/// 与视频共用全屏父约束和 BoxFit，切换时保持相同可见区域。
 class PlayerOpeningFrame extends StatefulWidget {
   const PlayerOpeningFrame({
     super.key,
-    this.thumbnailsUrl,
-    this.posterUrl,
+    required this.thumbnailsUrl,
+    required this.spriteSource,
     this.fit = BoxFit.cover,
-    this.loader,
-    this.cache,
   });
 
-  final String? thumbnailsUrl;
-  final String? posterUrl;
+  /// 当前视频雪碧图 WebVTT 地址。
+  final String thumbnailsUrl;
+
+  /// 进度条拖动预览共用的雪碧图时间轴与解码缓存。
+  final SpriteThumbnailAxisSource spriteSource;
+
+  /// 必须与同页视频层使用相同适配规则。
   final BoxFit fit;
-  final SpriteThumbnailAssetLoader? loader;
-  final OpeningFrameCache? cache;
 
   @override
   State<PlayerOpeningFrame> createState() => _PlayerOpeningFrameState();
 }
 
 class _PlayerOpeningFrameState extends State<PlayerOpeningFrame> {
-  SpriteThumbnailFrame? _frame;
-  int _serial = 0;
-
   @override
   void initState() {
     super.initState();
-    unawaited(_load());
+    widget.spriteSource.addListener(_handleSpriteChanged);
+    unawaited(
+      widget.spriteSource.prepareAt(widget.thumbnailsUrl, Duration.zero),
+    );
   }
 
   @override
   void didUpdateWidget(covariant PlayerOpeningFrame oldWidget) {
     super.didUpdateWidget(oldWidget);
+    if (oldWidget.spriteSource != widget.spriteSource) {
+      oldWidget.spriteSource.removeListener(_handleSpriteChanged);
+      widget.spriteSource.addListener(_handleSpriteChanged);
+    }
     if (oldWidget.thumbnailsUrl != widget.thumbnailsUrl) {
-      _frame = null;
-      unawaited(_load());
+      unawaited(
+        widget.spriteSource.prepareAt(widget.thumbnailsUrl, Duration.zero),
+      );
     }
-  }
-
-  Future<void> _load() async {
-    final serial = ++_serial;
-    final thumbnailsUrl = widget.thumbnailsUrl;
-    if (thumbnailsUrl == null) return;
-    final frame = await (widget.cache ?? OpeningFrameCache.shared).load(
-      thumbnailsUrl,
-      loader: widget.loader,
-    );
-    if (!mounted || serial != _serial) return;
-    setState(() => _frame = frame);
   }
 
   @override
-  Widget build(BuildContext context) {
-    final frame = _frame;
-    final posterUrl = widget.posterUrl;
-    return Stack(
-      fit: StackFit.expand,
-      children: [
-        const ColoredBox(color: AppColors.mediaBlack),
-        if (posterUrl != null)
-          RemoteImage(
-            posterUrl,
-            key: const Key('player-opening-poster'),
-            fit: widget.fit,
-            fallbackColor: AppColors.mediaBlack,
-          ),
-        if (frame != null)
-          SpriteCropPreview(
-            key: const Key('player-opening-sprite'),
-            image: frame.image,
-            sourceRect: frame.sourceRect,
-            fit: widget.fit,
-          ),
-      ],
-    );
-  }
-}
-
-/// 相邻页共用的雪碧图首帧缓存，避免每页重复拉 VTT。
-class OpeningFrameCache {
-  OpeningFrameCache({this.capacity = 6});
-
-  static final OpeningFrameCache shared = OpeningFrameCache();
-
-  final int capacity;
-  final Map<String, SpriteThumbnailFrame> _frames = {};
-  final Map<String, Future<SpriteThumbnailFrame?>> _loads = {};
-
-  /// 取 [thumbnailsUrl] 对应的第一帧；失败返回 null。
-  Future<SpriteThumbnailFrame?> load(
-    String? thumbnailsUrl, {
-    SpriteThumbnailAssetLoader? loader,
-  }) {
-    final url = _normalize(thumbnailsUrl);
-    if (url == null) return Future<SpriteThumbnailFrame?>.value();
-    final cached = _frames[url];
-    if (cached != null) return Future.value(cached);
-    return _loads.putIfAbsent(url, () => _fetch(url, loader));
-  }
-
-  Future<SpriteThumbnailFrame?> _fetch(
-    String url,
-    SpriteThumbnailAssetLoader? loader,
-  ) async {
-    try {
-      final asset = loader ?? DioSpriteThumbnailAssetLoader();
-      final text = await asset.loadVtt(Uri.parse(url));
-      if (text == null || text.isEmpty) return null;
-      final axis = parseSpriteThumbnailVtt(text, vttUrl: url);
-      final cue = axis.cues.isEmpty ? null : axis.cues.first;
-      if (cue == null) return null;
-      final decoded = await asset.loadSprite(
-        axis.resolveSpriteUri(cue.spriteFile),
-      );
-      if (decoded == null) return null;
-      final frame = SpriteThumbnailFrame(
-        image: decoded.image,
-        sourceRect: _scaledRect(decoded, cue.sourceRect),
-        spriteUrl: axis.resolveSpriteUri(cue.spriteFile).toString(),
-        cue: cue,
-      );
-      _store(url, frame);
-      return frame;
-    } catch (_) {
-      return null;
-    } finally {
-      _loads.remove(url);
-    }
-  }
-
-  void _store(String url, SpriteThumbnailFrame frame) {
-    _frames.remove(url);
-    _frames[url] = frame;
-    while (_frames.length > capacity) {
-      final oldest = _frames.keys.first;
-      _frames.remove(oldest)?.image.dispose();
-    }
-  }
-
-  ui.Rect _scaledRect(SpriteThumbnailDecodedImage decoded, ui.Rect source) {
-    if (decoded.originalWidth <= 0 || decoded.originalHeight <= 0) {
-      return source;
-    }
-    final scaleX = decoded.image.width / decoded.originalWidth;
-    final scaleY = decoded.image.height / decoded.originalHeight;
-    return ui.Rect.fromLTWH(
-      source.left * scaleX,
-      source.top * scaleY,
-      source.width * scaleX,
-      source.height * scaleY,
-    );
-  }
-
-  String? _normalize(String? raw) {
-    final value = AppConfig.mediaUrl(raw?.trim() ?? '');
-    if (value.isEmpty) return null;
-    return value;
-  }
-
-  /// 测试收尾时清空缓存。
-  void clear() {
-    for (final frame in _frames.values) {
-      frame.image.dispose();
-    }
-    _frames.clear();
-    _loads.clear();
+  void dispose() {
+    widget.spriteSource.removeListener(_handleSpriteChanged);
+    super.dispose();
   }
+
+  void _handleSpriteChanged() {
+    if (mounted) setState(() {});
+  }
+
+  @override
+  Widget build(BuildContext context) => Stack(
+    fit: StackFit.expand,
+    children: [
+      const ColoredBox(color: AppColors.mediaBlack),
+      if (widget.spriteSource.cachedFrameAt(widget.thumbnailsUrl, Duration.zero)
+          case final frame?)
+        SpriteCropPreview(
+          key: const Key('player-opening-sprite'),
+          image: frame.image,
+          sourceRect: frame.sourceRect,
+          fit: widget.fit,
+        ),
+    ],
+  );
 }

lib/pages/player/widgets/player_overlay.dart

@@ -303,7 +303,6 @@ class PlayerPlaybackOverlay extends StatelessWidget {
         spriteAxisService: data.spriteAxisService,
         thumbnailsUrl: data.episode.thumbnailsUrl,
         episodeId: data.episode.id,
-        posterUrl: data.drama.posterUrl,
         inactiveTrackColor: AppColors.inactiveTrack,
         onScrubStart: actions.onScrubStart,
         onScrubEnd: actions.onScrubEnd,

lib/pages/player/widgets/player_video_surface.dart

@@ -18,6 +18,7 @@ class PlayerVideoSurface extends StatefulWidget {
     required this.theater,
     this.handoff,
     this.openingFrame,
+    this.openingFrameReady = false,
     this.holdOpeningUntilFirstFrame = false,
     this.preparedFrameAvailable = false,
   });
@@ -28,6 +29,9 @@ class PlayerVideoSurface extends StatefulWidget {
   /// 解码出第一帧之前垫上的视频首帧，没有则为空。
   final Widget? openingFrame;
 
+  /// 当前集雪碧图 t=0 是否已在共享缓存中可用。
+  final bool openingFrameReady;
+
   /// 播放中的新片源在位置首次前进前继续显示封面，避免混入未出帧纹理。
   final bool holdOpeningUntilFirstFrame;
 
@@ -73,10 +77,10 @@ class _PlayerVideoSurfaceState extends State<PlayerVideoSurface> {
     final controller = widget.controller;
     final handoff = _liveHandoff(controller);
     final firstFrameSeen = _trackFrameState(controller, value);
-    final firstFrameReady =
-        widget.preparedFrameAvailable || firstFrameSeen;
+    final firstFrameReady = widget.preparedFrameAvailable || firstFrameSeen;
     final textureReady = _shouldReveal(value, handoff != null);
-    final reveal = textureReady &&
+    final reveal =
+        textureReady &&
         (!widget.holdOpeningUntilFirstFrame ||
             widget.preparedFrameAvailable ||
             firstFrameReady ||
@@ -86,13 +90,7 @@ class _PlayerVideoSurfaceState extends State<PlayerVideoSurface> {
     final showOpening =
         widget.openingFrame != null && handoff == null && !reveal;
     _logStateChange(value);
-    _logLayerState(
-      value,
-      handoff,
-      reveal,
-      firstFrameReady,
-      showOpening,
-    );
+    _logLayerState(value, handoff, reveal, firstFrameReady, showOpening);
     return Stack(
       fit: StackFit.expand,
       children: [
@@ -203,10 +201,20 @@ class _PlayerVideoSurfaceState extends State<PlayerVideoSurface> {
         : !firstFrameReady && widget.holdOpeningUntilFirstFrame
         ? 'awaiting-first-frame'
         : 'reveal';
+    final fallback = handoff != null
+        ? 'handoff'
+        : showOpening
+        ? widget.openingFrameReady
+              ? 'thumbnails-first-frame'
+              : 'black'
+        : reveal
+        ? 'video'
+        : 'black';
     final signature =
         'warm=${widget.preparedFrameAvailable ? 1 : 0} '
         'frame=${firstFrameReady ? 1 : 0} '
-        'cover=${showOpening ? 1 : 0} '
+        'thumbnails=${widget.openingFrameReady ? 'ready' : 'pending'} '
+        'fallback=$fallback '
         'video=${reveal ? 1 : 0} handoff=${handoff == null ? 0 : 1} '
         'init=${value?.isInitialized == true ? 1 : 0} '
         'playing=${value?.isPlaying == true ? 1 : 0} '

lib/pages/player/widgets/scrub_preview_card.dart

@@ -9,7 +9,6 @@ import 'package:flutter/material.dart';
 import '../../../core/data/services/playback_thumbnail_service.dart';
 import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../core/theme/app_colors.dart';
-import '../../../core/widgets/remote_image.dart';
 
 const double scrubPreviewWidth = 96;
 const double scrubPreviewSafeMargin = 12;
@@ -36,7 +35,6 @@ class ScrubPreviewCard extends StatefulWidget {
     super.key,
     required this.service,
     required this.episodeId,
-    required this.posterUrl,
     required this.position,
     required this.duration,
     this.spriteAxisService,
@@ -47,7 +45,6 @@ class ScrubPreviewCard extends StatefulWidget {
   final SpriteThumbnailAxisSource? spriteAxisService;
   final String? thumbnailsUrl;
   final String episodeId;
-  final String posterUrl;
   final Duration position;
   final Duration duration;
 
@@ -207,11 +204,9 @@ class _ScrubPreviewCardState extends State<ScrubPreviewCard> {
               child: Stack(
                 fit: StackFit.expand,
                 children: [
-                  RemoteImage(
-                    widget.posterUrl,
-                    key: const Key('scrub-preview-poster'),
-                    fit: BoxFit.cover,
-                    fallbackColor: AppColors.bar,
+                  const ColoredBox(
+                    key: Key('scrub-preview-background'),
+                    color: AppColors.bar,
                   ),
                   if (stage == ScrubPreviewStage.sprite && spriteFrame != null)
                     SpriteCropPreview(
@@ -265,11 +260,7 @@ class SpriteCropPreview extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) => CustomPaint(
-    painter: _SpriteCropPainter(
-      image: image,
-      sourceRect: sourceRect,
-      fit: fit,
-    ),
+    painter: _SpriteCropPainter(image: image, sourceRect: sourceRect, fit: fit),
   );
 }
 

lib/pages/player/widgets/seek_progress_bar.dart

@@ -41,7 +41,6 @@ class SeekProgressBar extends StatefulWidget {
     this.thumbnailService,
     this.spriteAxisService,
     this.episodeId,
-    this.posterUrl = '',
     this.thumbnailsUrl,
   });
 
@@ -57,7 +56,6 @@ class SeekProgressBar extends StatefulWidget {
   final PlaybackThumbnailService? thumbnailService;
   final SpriteThumbnailAxisService? spriteAxisService;
   final String? episodeId;
-  final String posterUrl;
   final String? thumbnailsUrl;
 
   @override
@@ -351,7 +349,6 @@ class _SeekProgressBarState extends State<SeekProgressBar> {
                   spriteAxisService: widget.spriteAxisService,
                   thumbnailsUrl: widget.thumbnailsUrl,
                   episodeId: widget.episodeId!,
-                  posterUrl: widget.posterUrl,
                   position: previewPosition,
                   duration: video.duration,
                 ),