feat(player): 进度条拖动预览改用雪碧图

lib/core/data/models/drama.dart

@@ -17,6 +17,7 @@ class Episode {
     this.locked = false,
     this.likeCount,
     this.commentCount,
+    this.thumbnailsUrl,
   });
 
   final String id;
@@ -32,19 +33,25 @@ class Episode {
   final bool locked;
   final int? likeCount;
   final int? commentCount;
+  final String? thumbnailsUrl;
 
-  Episode withVideoUrl(String url, {int? likeCount, int? commentCount}) =>
-      Episode(
-        id: id,
-        number: number,
-        title: title,
-        isFree: isFree,
-        videoUrl: url,
-        durationSec: durationSec,
-        locked: locked,
-        likeCount: likeCount ?? this.likeCount,
-        commentCount: commentCount ?? this.commentCount,
-      );
+  Episode withVideoUrl(
+    String url, {
+    int? likeCount,
+    int? commentCount,
+    String? thumbnailsUrl,
+  }) => Episode(
+    id: id,
+    number: number,
+    title: title,
+    isFree: isFree,
+    videoUrl: url,
+    durationSec: durationSec,
+    locked: locked,
+    likeCount: likeCount ?? this.likeCount,
+    commentCount: commentCount ?? this.commentCount,
+    thumbnailsUrl: thumbnailsUrl ?? this.thumbnailsUrl,
+  );
 
   factory Episode.fromJson(Map<String, dynamic> json) {
     return Episode(
@@ -57,6 +64,7 @@ class Episode {
       videoUrl: json['playUrl'] as String? ?? '',
       likeCount: _optionalInt(json['likeCount']),
       commentCount: _optionalInt(json['commentCount']),
+      thumbnailsUrl: _optionalString(json['thumbnailsUrl']),
     );
   }
 }
@@ -159,3 +167,8 @@ class Drama {
 }
 
 int? _optionalInt(dynamic value) => value == null ? null : jsonToInt(value);
+
+String? _optionalString(dynamic value) {
+  final text = value is String ? value.trim() : '';
+  return text.isEmpty ? null : text;
+}

lib/core/data/models/play_ticket.dart

@@ -14,6 +14,7 @@ class PlayTicket {
     this.unlockCoin = 0,
     this.previewSeconds = 0,
     this.qualities = const [],
+    this.thumbnailsUrl,
     this.likeCount,
     this.commentCount,
   });
@@ -40,6 +41,7 @@ class PlayTicket {
 
   /// 后端下发的清晰度档位（如 AUTO / 720P / 1080P），HLS 由播放器自动切换。
   final List<String> qualities;
+  final String? thumbnailsUrl;
   final int? likeCount;
   final int? commentCount;
 
@@ -62,6 +64,7 @@ class PlayTicket {
           .whereType<String>()
           .where((quality) => quality.isNotEmpty)
           .toList(),
+      thumbnailsUrl: _optionalString(json['thumbnailsUrl']),
       likeCount: json['likeCount'] == null
           ? null
           : jsonToInt(json['likeCount']),
@@ -71,3 +74,8 @@ class PlayTicket {
     );
   }
 }
+
+String? _optionalString(dynamic value) {
+  final text = value is String ? value.trim() : '';
+  return text.isEmpty ? null : text;
+}

lib/core/data/services/sprite_thumbnail_asset_loader.dart

@@ -0,0 +1,128 @@
+// Author: fruit.com.cn
+
+import 'dart:convert';
+import 'dart:typed_data';
+import 'dart:ui' as ui;
+
+import 'package:dio/dio.dart';
+
+import '../../config/app_config.dart';
+
+const int spriteThumbnailDecodeMaxDimension = 2048;
+
+/// VTT 资源拒绝访问，服务层据此清缓存并重试一次。
+class SpriteThumbnailForbiddenException implements Exception {
+  const SpriteThumbnailForbiddenException();
+}
+
+/// 已解码 sprite 与原图尺寸；cue 坐标会按解码缩放比例映射。
+class SpriteThumbnailDecodedImage {
+  const SpriteThumbnailDecodedImage({
+    required this.image,
+    required this.originalWidth,
+    required this.originalHeight,
+  });
+
+  final ui.Image image;
+  final int originalWidth;
+  final int originalHeight;
+}
+
+/// 可注入的资源加载接口，测试无需真实网络或图片。
+abstract interface class SpriteThumbnailAssetLoader {
+  Future<String?> loadVtt(Uri uri);
+
+  Future<SpriteThumbnailDecodedImage?> loadSprite(Uri uri);
+}
+
+/// 默认通过项目现有 Dio 拉取 VTT 和 sprite 图片。
+class DioSpriteThumbnailAssetLoader implements SpriteThumbnailAssetLoader {
+  DioSpriteThumbnailAssetLoader({Dio? dio})
+    : _dio =
+          dio ??
+          Dio(
+            BaseOptions(
+              connectTimeout: AppConfig.requestTimeout,
+              receiveTimeout: AppConfig.requestTimeout,
+              validateStatus: (_) => true,
+            ),
+          );
+
+  final Dio _dio;
+
+  @override
+  Future<String?> loadVtt(Uri uri) async {
+    final response = await _request(uri);
+    if (response?.statusCode == 403) {
+      throw const SpriteThumbnailForbiddenException();
+    }
+    if (response == null || !_isSuccess(response.statusCode)) return null;
+    final data = response.data;
+    if (data is! List<int>) return null;
+    return utf8.decode(data, allowMalformed: true);
+  }
+
+  @override
+  Future<SpriteThumbnailDecodedImage?> loadSprite(Uri uri) async {
+    final response = await _request(uri);
+    if (response == null || !_isSuccess(response.statusCode)) return null;
+    final data = response.data;
+    if (data is! List<int>) return null;
+    return _decode(Uint8List.fromList(data));
+  }
+
+  Future<Response<List<int>>?> _request(Uri uri) async {
+    try {
+      return await _dio.get<List<int>>(
+        uri.toString(),
+        options: Options(responseType: ResponseType.bytes),
+      );
+    } catch (_) {
+      return null;
+    }
+  }
+
+  bool _isSuccess(int? status) =>
+      status != null && status >= 200 && status < 300;
+
+  Future<SpriteThumbnailDecodedImage?> _decode(Uint8List bytes) async {
+    ui.ImmutableBuffer? buffer;
+    ui.ImageDescriptor? descriptor;
+    ui.Codec? codec;
+    try {
+      buffer = await ui.ImmutableBuffer.fromUint8List(bytes);
+      descriptor = await ui.ImageDescriptor.encoded(buffer);
+      final originalWidth = descriptor.width;
+      final originalHeight = descriptor.height;
+      final target = _targetSize(originalWidth, originalHeight);
+      codec = await descriptor.instantiateCodec(
+        targetWidth: target.$1,
+        targetHeight: target.$2,
+      );
+      final frame = await codec.getNextFrame();
+      return SpriteThumbnailDecodedImage(
+        image: frame.image,
+        originalWidth: originalWidth,
+        originalHeight: originalHeight,
+      );
+    } catch (_) {
+      return null;
+    } finally {
+      codec?.dispose();
+      descriptor?.dispose();
+      buffer?.dispose();
+    }
+  }
+
+  (int?, int?) _targetSize(int width, int height) {
+    final longest = width > height ? width : height;
+    if (longest <= spriteThumbnailDecodeMaxDimension) {
+      return (null, null);
+    }
+    final scale = spriteThumbnailDecodeMaxDimension / longest;
+    return (
+      (width * scale).round().clamp(1, spriteThumbnailDecodeMaxDimension),
+      (height * scale).round().clamp(1, spriteThumbnailDecodeMaxDimension),
+    );
+  }
+}

lib/core/data/services/sprite_thumbnail_axis.dart

@@ -0,0 +1,461 @@
+// Author: fruit.com.cn
+
+import 'dart:collection';
+import 'dart:ui' as ui;
+
+import 'package:flutter/foundation.dart';
+
+import '../../config/app_config.dart';
+import 'sprite_thumbnail_asset_loader.dart';
+
+const Duration spriteVttCacheTtl = Duration(minutes: 10);
+const int spriteImageCacheCapacity = 2;
+
+/// 单个 VTT cue 对应的 sprite 裁剪区域。
+class SpriteThumbnailCue {
+  const SpriteThumbnailCue({
+    required this.start,
+    required this.end,
+    required this.spriteFile,
+    required this.sourceRect,
+  });
+
+  final Duration start;
+  final Duration end;
+  final String spriteFile;
+  final ui.Rect sourceRect;
+}
+
+/// 已解析的 VTT 时间轴。
+class SpriteThumbnailAxis {
+  const SpriteThumbnailAxis({required this.vttUrl, required this.cues});
+
+  final String vttUrl;
+  final List<SpriteThumbnailCue> cues;
+
+  factory SpriteThumbnailAxis.empty(String vttUrl) =>
+      SpriteThumbnailAxis(vttUrl: vttUrl, cues: const []);
+
+  Uri resolveSpriteUri(String spriteFile) =>
+      Uri.parse(vttUrl).resolve(spriteFile);
+}
+
+/// 可直接交给 RawImage.sourceRect 的裁剪帧。
+class SpriteThumbnailFrame {
+  const SpriteThumbnailFrame({
+    required this.image,
+    required this.sourceRect,
+    required this.spriteUrl,
+    required this.cue,
+  });
+
+  final ui.Image image;
+  final ui.Rect sourceRect;
+  final String spriteUrl;
+  final SpriteThumbnailCue cue;
+}
+
+/// 预览卡片当前应展示的回退阶段。
+enum ScrubPreviewStage { sprite, waitingForAxis, localFrame, cover }
+
+/// 预览回退链的纯判定函数。
+ScrubPreviewStage decideScrubPreviewStage({
+  required bool hasThumbnailsUrl,
+  required bool hasSpriteFrame,
+  required bool hasAxis,
+  required bool hasLocalFrame,
+}) {
+  if (hasSpriteFrame) return ScrubPreviewStage.sprite;
+  if (hasThumbnailsUrl && !hasAxis) {
+    return ScrubPreviewStage.waitingForAxis;
+  }
+  if (hasLocalFrame) return ScrubPreviewStage.localFrame;
+  return ScrubPreviewStage.cover;
+}
+
+/// 解析 WebVTT；任意异常都收敛为空轴。
+SpriteThumbnailAxis parseSpriteThumbnailVtt(
+  String source, {
+  required String vttUrl,
+}) {
+  final cues = <SpriteThumbnailCue>[];
+  try {
+    for (final block
+        in source.replaceAll('\r\n', '\n').split(RegExp(r'\n\s*\n'))) {
+      final cue = _parseCueBlock(block);
+      if (cue != null) cues.add(cue);
+    }
+  } catch (_) {
+    return SpriteThumbnailAxis.empty(vttUrl);
+  }
+  cues.sort((left, right) => left.start.compareTo(right.start));
+  return SpriteThumbnailAxis(vttUrl: vttUrl, cues: cues);
+}
+
+/// 按 position 二分选择 cue；边界外选择最近 cue。
+SpriteThumbnailCue? selectSpriteThumbnailCue(
+  List<SpriteThumbnailCue> cues,
+  Duration position,
+) {
+  if (cues.isEmpty) return null;
+  var low = 0;
+  var high = cues.length;
+  while (low < high) {
+    final middle = (low + high) >> 1;
+    if (cues[middle].start <= position) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  if (low == 0) return cues.first;
+  final previous = cues[low - 1];
+  if (low == cues.length || position <= previous.end) return previous;
+  final next = cues[low];
+  final previousDistance = position - previous.end;
+  final nextDistance = next.start - position;
+  return previousDistance <= nextDistance ? previous : next;
+}
+
+/// 只读缓存接口，便于 widget 测试注入。
+abstract interface class SpriteThumbnailAxisSource implements Listenable {
+  SpriteThumbnailFrame? cachedFrameAt(String? thumbnailsUrl, Duration position);
+
+  bool hasAxis(String? thumbnailsUrl);
+}
+
+/// VTT 时间轴、cue 二分与 sprite ui.Image LRU 缓存。
+class SpriteThumbnailAxisService extends ChangeNotifier
+    implements SpriteThumbnailAxisSource {
+  SpriteThumbnailAxisService({
+    SpriteThumbnailAssetLoader? loader,
+    this.cacheTtl = spriteVttCacheTtl,
+    DateTime Function()? now,
+  }) : _loader = loader ?? DioSpriteThumbnailAssetLoader(),
+       _now = now ?? DateTime.now;
+
+  final SpriteThumbnailAssetLoader _loader;
+  final Duration cacheTtl;
+  final DateTime Function() _now;
+  final Map<String, _CachedAxis> _axisCache = {};
+  final Map<String, Future<SpriteThumbnailAxis>> _axisRequests = {};
+  final LinkedHashMap<String, _CachedSprite> _spriteCache = LinkedHashMap();
+  final Map<String, Future<_CachedSprite?>> _spriteRequests = {};
+  final Set<String> _failedSprites = {};
+  String? _activeAxisUrl;
+  int _axisGeneration = 0;
+  bool _disposed = false;
+
+  @visibleForTesting
+  int get spriteCacheSize => _spriteCache.length;
+
+  @visibleForTesting
+  List<String> get spriteCacheKeys => _spriteCache.keys.toList();
+
+  /// 播放器就绪时预取当前 cue 与相邻 sprite，拖动帧不触发网络或解码。
+  Future<void> prepareAt(String? thumbnailsUrl, Duration position) async {
+    final url = _normalizeUrl(thumbnailsUrl);
+    if (_disposed || url == null) return;
+    _activateAxis(url);
+    final axis = await _loadAxis(url);
+    if (_disposed || _activeAxisUrl != url) return;
+    for (final cue in _prefetchCues(axis, position)) {
+      await _ensureSprite(axis, cue);
+    }
+  }
+
+  @override
+  bool hasAxis(String? thumbnailsUrl) {
+    final url = _normalizeUrl(thumbnailsUrl);
+    if (url == null || url != _activeAxisUrl) return false;
+    return _readAxis(url) != null;
+  }
+
+  @override
+  SpriteThumbnailFrame? cachedFrameAt(
+    String? thumbnailsUrl,
+    Duration position,
+  ) {
+    final url = _normalizeUrl(thumbnailsUrl);
+    if (url == null || url != _activeAxisUrl) return null;
+    final axis = _readAxis(url);
+    if (axis == null) return null;
+    final cue = selectSpriteThumbnailCue(axis.cues, position);
+    if (cue == null) return null;
+    final cached = _readSprite(cue.spriteFile);
+    if (cached == null) return null;
+    final sourceRect = _scaledSourceRect(cached, cue.sourceRect);
+    if (sourceRect == null) return null;
+    return SpriteThumbnailFrame(
+      image: cached.decoded.image,
+      sourceRect: sourceRect,
+      spriteUrl: axis.resolveSpriteUri(cue.spriteFile).toString(),
+      cue: cue,
+    );
+  }
+
+  /// 页面销毁时释放全部 VTT 与 ui.Image 内存。
+  @override
+  void dispose() {
+    if (_disposed) return;
+    _disposed = true;
+    _clearAll();
+    super.dispose();
+  }
+
+  void _activateAxis(String url) {
+    if (_activeAxisUrl == url) return;
+    _activeAxisUrl = url;
+    _axisGeneration++;
+    _clearSprites();
+  }
+
+  Future<SpriteThumbnailAxis> _loadAxis(String url) {
+    final cached = _readAxis(url);
+    if (cached != null) return Future.value(cached);
+    final existing = _axisRequests[url];
+    if (existing != null) return existing;
+    final request = _fetchAxis(url);
+    _axisRequests[url] = request;
+    return request.whenComplete(() {
+      _axisRequests.remove(url);
+    });
+  }
+
+  Future<SpriteThumbnailAxis> _fetchAxis(String url) async {
+    for (var attempt = 0; attempt < 2; attempt++) {
+      try {
+        final text = await _loader.loadVtt(Uri.parse(url));
+        final axis = text == null
+            ? SpriteThumbnailAxis.empty(url)
+            : parseSpriteThumbnailVtt(text, vttUrl: url);
+        if (_disposed) return SpriteThumbnailAxis.empty(url);
+        _cacheAxis(axis);
+        notifyListeners();
+        return axis;
+      } on SpriteThumbnailForbiddenException {
+        if (_disposed) return SpriteThumbnailAxis.empty(url);
+        _axisCache.remove(url);
+        if (_activeAxisUrl == url) _clearSprites();
+      } catch (_) {
+        break;
+      }
+    }
+    final empty = SpriteThumbnailAxis.empty(url);
+    if (_disposed) return empty;
+    _cacheAxis(empty);
+    notifyListeners();
+    return empty;
+  }
+
+  void _cacheAxis(SpriteThumbnailAxis axis) {
+    _axisCache[axis.vttUrl] = _CachedAxis(
+      axis: axis,
+      expiresAt: _now().add(cacheTtl),
+    );
+  }
+
+  SpriteThumbnailAxis? _readAxis(String url) {
+    final cached = _axisCache[url];
+    if (cached == null) return null;
+    if (cached.expiresAt.isAfter(_now())) return cached.axis;
+    _axisCache.remove(url);
+    return null;
+  }
+
+  List<SpriteThumbnailCue> _prefetchCues(
+    SpriteThumbnailAxis axis,
+    Duration position,
+  ) {
+    final current = selectSpriteThumbnailCue(axis.cues, position);
+    if (current == null) return const [];
+    final index = axis.cues.indexOf(current);
+    final candidates = <SpriteThumbnailCue>[current];
+    for (final direction in const [1, -1]) {
+      for (var step = 1; step < axis.cues.length; step++) {
+        final neighborIndex = index + direction * step;
+        if (neighborIndex < 0 || neighborIndex >= axis.cues.length) break;
+        final neighbor = axis.cues[neighborIndex];
+        if (neighbor.spriteFile != current.spriteFile) {
+          candidates.add(neighbor);
+          break;
+        }
+      }
+      if (candidates.length > 1) break;
+    }
+    return candidates;
+  }
+
+  Future<_CachedSprite?> _ensureSprite(
+    SpriteThumbnailAxis axis,
+    SpriteThumbnailCue cue,
+  ) {
+    final cached = _readSprite(cue.spriteFile);
+    if (cached != null) return Future.value(cached);
+    if (_failedSprites.contains(cue.spriteFile)) return Future.value();
+    final existing = _spriteRequests[cue.spriteFile];
+    if (existing != null) return existing;
+    final generation = _axisGeneration;
+    final request = _loadSprite(axis, cue, generation);
+    _spriteRequests[cue.spriteFile] = request;
+    return request.whenComplete(() {
+      _spriteRequests.remove(cue.spriteFile);
+    });
+  }
+
+  Future<_CachedSprite?> _loadSprite(
+    SpriteThumbnailAxis axis,
+    SpriteThumbnailCue cue,
+    int generation,
+  ) async {
+    SpriteThumbnailDecodedImage? decoded;
+    try {
+      decoded = await _loader.loadSprite(axis.resolveSpriteUri(cue.spriteFile));
+    } catch (_) {
+      decoded = null;
+    }
+    if (decoded == null) {
+      _failedSprites.add(cue.spriteFile);
+      if (!_disposed) notifyListeners();
+      return null;
+    }
+    if (_disposed || generation != _axisGeneration) {
+      decoded.image.dispose();
+      return null;
+    }
+    final cached = _CachedSprite(decoded);
+    _putSprite(cue.spriteFile, cached);
+    notifyListeners();
+    return cached;
+  }
+
+  _CachedSprite? _readSprite(String key) {
+    final value = _spriteCache.remove(key);
+    if (value == null) return null;
+    _spriteCache[key] = value;
+    return value;
+  }
+
+  void _putSprite(String key, _CachedSprite value) {
+    _spriteCache.remove(key)?.decoded.image.dispose();
+    _spriteCache[key] = value;
+    while (_spriteCache.length > spriteImageCacheCapacity) {
+      final oldest = _spriteCache.remove(_spriteCache.keys.first);
+      oldest?.decoded.image.dispose();
+    }
+  }
+
+  ui.Rect? _scaledSourceRect(_CachedSprite cached, ui.Rect source) {
+    final scaleX = cached.decoded.image.width / cached.decoded.originalWidth;
+    final scaleY = cached.decoded.image.height / cached.decoded.originalHeight;
+    final scaled =
+        ui.Rect.fromLTWH(
+          source.left * scaleX,
+          source.top * scaleY,
+          source.width * scaleX,
+          source.height * scaleY,
+        ).intersect(
+          ui.Rect.fromLTWH(
+            0,
+            0,
+            cached.decoded.image.width.toDouble(),
+            cached.decoded.image.height.toDouble(),
+          ),
+        );
+    return scaled.isEmpty ? null : scaled;
+  }
+
+  void _clearSprites() {
+    for (final cached in _spriteCache.values) {
+      cached.decoded.image.dispose();
+    }
+    _spriteCache.clear();
+    _spriteRequests.clear();
+    _failedSprites.clear();
+  }
+
+  void _clearAll() {
+    _axisGeneration++;
+    _activeAxisUrl = null;
+    _axisCache.clear();
+    _axisRequests.clear();
+    _clearSprites();
+  }
+
+  String? _normalizeUrl(String? url) {
+    final trimmed = url?.trim() ?? '';
+    if (trimmed.isEmpty) return null;
+    return AppConfig.mediaUrl(trimmed);
+  }
+}
+
+final RegExp _timingPattern = RegExp(
+  r'^(\d{2,}:\d{2}:\d{2}\.\d{3})\s*-->\s*(\d{2,}:\d{2}:\d{2}\.\d{3})',
+);
+final RegExp _cueLinkPattern = RegExp(r'^(\S+?)#xywh=(.+)$');
+final RegExp _xywhPattern = RegExp(r'^(\d+),(\d+),(\d+),(\d+)$');
+
+SpriteThumbnailCue? _parseCueBlock(String block) {
+  final lines = block
+      .split('\n')
+      .map((line) => line.trim())
+      .where((line) => line.isNotEmpty)
+      .toList();
+  final timingIndex = lines.indexWhere(_timingPattern.hasMatch);
+  if (timingIndex < 0 || timingIndex + 1 >= lines.length) return null;
+  final timing = _timingPattern.firstMatch(lines[timingIndex]);
+  if (timing == null) return null;
+  final link = _cueLinkPattern.firstMatch(lines[timingIndex + 1]);
+  if (link == null) return null;
+  final start = _parseTimestamp(timing.group(1)!);
+  final end = _parseTimestamp(timing.group(2)!);
+  if (start == null || end == null || end <= start) return null;
+  final segments = Uri.tryParse(link.group(1)!)?.pathSegments;
+  final file = segments == null || segments.isEmpty ? null : segments.last;
+  final xywh = _xywhPattern.firstMatch(link.group(2)!);
+  if (file == null || file.isEmpty || xywh == null) return null;
+  final rect = ui.Rect.fromLTWH(
+    double.parse(xywh.group(1)!),
+    double.parse(xywh.group(2)!),
+    double.parse(xywh.group(3)!),
+    double.parse(xywh.group(4)!),
+  );
+  if (rect.isEmpty) return null;
+  return SpriteThumbnailCue(
+    start: start,
+    end: end,
+    spriteFile: file,
+    sourceRect: rect,
+  );
+}
+
+Duration? _parseTimestamp(String value) {
+  final parts = value.split(':');
+  if (parts.length != 3) return null;
+  final secondsParts = parts[2].split('.');
+  if (secondsParts.length != 2) return null;
+  final hours = int.tryParse(parts[0]);
+  final minutes = int.tryParse(parts[1]);
+  final seconds = int.tryParse(secondsParts[0]);
+  final milliseconds = int.tryParse(secondsParts[1]);
+  if ([hours, minutes, seconds, milliseconds].contains(null)) return null;
+  return Duration(
+    hours: hours!,
+    minutes: minutes!,
+    seconds: seconds!,
+    milliseconds: milliseconds!,
+  );
+}
+
+class _CachedAxis {
+  const _CachedAxis({required this.axis, required this.expiresAt});
+
+  final SpriteThumbnailAxis axis;
+  final DateTime expiresAt;
+}
+
+class _CachedSprite {
+  const _CachedSprite(this.decoded);
+
+  final SpriteThumbnailDecodedImage decoded;
+}

lib/pages/player/player_logic.dart

@@ -149,6 +149,7 @@ class PlayerLogic extends ChangeNotifier {
   Episode displayEpisode(Drama drama, Episode fallback) {
     final number = pickedEpisode[drama.id];
     if (number == null) return fallback;
+    if (fallback.number == number) return fallback;
     for (final episode in drama.episodes) {
       if (episode.number == number) return episode;
     }
@@ -438,6 +439,7 @@ class PlayerLogic extends ChangeNotifier {
           ticket.playUrl,
           likeCount: ticket.likeCount,
           commentCount: ticket.commentCount,
+          thumbnailsUrl: ticket.thumbnailsUrl,
         );
         return true;
       }

lib/pages/player/player_view.dart

@@ -14,6 +14,7 @@ import '../../core/data/services/download_controller.dart';
 import '../../core/data/services/interaction_controller.dart';
 import '../../core/data/services/playback_position_cache.dart';
 import '../../core/data/services/playback_session.dart';
+import '../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../core/data/services/playback_thumbnail_service.dart';
 import '../../core/data/services/video_player_port.dart';
 import '../../core/data/services/wallet_controller.dart';
@@ -106,6 +107,7 @@ class _PlayerPageState extends State<PlayerPage>
     with WidgetsBindingObserver, RouteAware {
   late final PlayerLogic logic;
   late final PlaybackThumbnailService _thumbnailService;
+  late final SpriteThumbnailAxisService _spriteAxisService;
   PageRoute<dynamic>? _subscribedRoute;
   bool _chromeVisible = true;
   double _playbackSpeed = 1.0;
@@ -131,6 +133,7 @@ class _PlayerPageState extends State<PlayerPage>
     _thumbnailService = PlaybackThumbnailService(
       sourceResolver: _resolveThumbnailSource,
     );
+    _spriteAxisService = SpriteThumbnailAxisService();
     WidgetsBinding.instance.addObserver(this);
     logic.start(
       factory: context.read<PlayerFactory>(),
@@ -247,6 +250,7 @@ class _PlayerPageState extends State<PlayerPage>
   void dispose() {
     WidgetsBinding.instance.removeObserver(this);
     appRouteObserver.unsubscribe(this);
+    _spriteAxisService.dispose();
     _thumbnailService.dispose();
     logic.dispose();
     super.dispose();
@@ -422,9 +426,12 @@ class _PlayerPageState extends State<PlayerPage>
     final l10n = AppLocalizations.of(context)!;
     final entry = logic.queue.entryAt(index);
     final drama = entry.drama;
-    final episode = widget.homeMode
-        ? logic.displayEpisode(drama, entry.episode)
+    final sessionEpisode = index >= 0 && index < logic.sessionEpisodes.length
+        ? logic.sessionEpisodes[index]
         : entry.episode;
+    final episode = widget.homeMode
+        ? logic.displayEpisode(drama, sessionEpisode)
+        : sessionEpisode;
     final selected = index == logic.session.currentIndex;
     // Selection changes before the prepared slot is promoted. Use its controller
     // throughout the handoff instead of briefly falling back to a placeholder.
@@ -435,6 +442,14 @@ class _PlayerPageState extends State<PlayerPage>
     final ready = videoPort?.controller.value.isInitialized ?? false;
     final theater = logic.pip || logic.pipPreparing;
     final locked = logic.session.isLocked || episode.locked;
+    if (selected && ready) {
+      unawaited(
+        _spriteAxisService.prepareAt(
+          episode.thumbnailsUrl,
+          videoPort!.controller.value.position,
+        ),
+      );
+    }
 
     return Stack(
       fit: StackFit.expand,
@@ -606,6 +621,7 @@ class _PlayerPageState extends State<PlayerPage>
                 ? (position) => logic.seekTo(context, videoPort!, position)
                 : null,
             thumbnailService: _thumbnailService,
+            spriteAxisService: _spriteAxisService,
           )
         else
           PlayerPlaybackOverlay(
@@ -629,6 +645,7 @@ class _PlayerPageState extends State<PlayerPage>
               totalEpisodes: logic.visibleIndices.length,
               boosting: _boosting,
               thumbnailService: _thumbnailService,
+              spriteAxisService: _spriteAxisService,
             ),
             actions: PlayerOverlayActions(
               onBack: widget.embedded

lib/pages/player/widgets/home_feed_overlay.dart

@@ -8,6 +8,7 @@ import 'package:video_player/video_player.dart';
 
 import '../../../core/data/models/drama.dart';
 import '../../../core/data/services/playback_thumbnail_service.dart';
+import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../core/formatting/count_format.dart';
 import '../../../core/formatting/localized_content.dart';
 import '../../../core/theme/app_colors.dart';
@@ -63,6 +64,7 @@ class HomeFeedOverlay extends StatefulWidget {
     this.onScrubStart,
     this.onSeek,
     this.thumbnailService,
+    this.spriteAxisService,
   });
 
   final AppLocalizations l10n;
@@ -91,6 +93,7 @@ class HomeFeedOverlay extends StatefulWidget {
   final VoidCallback? onScrubStart;
   final ValueChanged<Duration>? onSeek;
   final PlaybackThumbnailService? thumbnailService;
+  final SpriteThumbnailAxisService? spriteAxisService;
 
   @override
   State<HomeFeedOverlay> createState() => _HomeFeedOverlayState();
@@ -405,6 +408,8 @@ class _HomeFeedOverlayState extends State<HomeFeedOverlay> {
                 onScrubStart: widget.onScrubStart,
                 onSeek: widget.onSeek,
                 thumbnailService: widget.thumbnailService,
+                spriteAxisService: widget.spriteAxisService,
+                thumbnailsUrl: widget.episode.thumbnailsUrl,
                 episodeId: widget.episode.id,
                 posterUrl: widget.drama.posterUrl,
               ),

lib/pages/player/widgets/home_feed_overlay_parts.dart

@@ -18,6 +18,8 @@ class _FeedProgressBar extends StatefulWidget {
     this.onScrubStart,
     this.onSeek,
     this.thumbnailService,
+    this.spriteAxisService,
+    this.thumbnailsUrl,
     required this.episodeId,
     required this.posterUrl,
   });
@@ -29,6 +31,8 @@ class _FeedProgressBar extends StatefulWidget {
   final VoidCallback? onScrubStart;
   final ValueChanged<Duration>? onSeek;
   final PlaybackThumbnailService? thumbnailService;
+  final SpriteThumbnailAxisService? spriteAxisService;
+  final String? thumbnailsUrl;
   final String episodeId;
   final String posterUrl;
 
@@ -148,6 +152,8 @@ class _FeedProgressBarState extends State<_FeedProgressBar> {
                   bottom: widget.hitHeight + 8,
                   child: ScrubPreviewCard(
                     service: widget.thumbnailService!,
+                    spriteAxisService: widget.spriteAxisService,
+                    thumbnailsUrl: widget.thumbnailsUrl,
                     episodeId: widget.episodeId,
                     posterUrl: widget.posterUrl,
                     position: previewPosition,

lib/pages/player/widgets/player_overlay.dart

@@ -266,6 +266,8 @@ class PlayerPlaybackOverlay extends StatelessWidget {
         compact: true,
         locked: data.locked,
         thumbnailService: data.thumbnailService,
+        spriteAxisService: data.spriteAxisService,
+        thumbnailsUrl: data.episode.thumbnailsUrl,
         episodeId: data.episode.id,
         posterUrl: data.drama.posterUrl,
         inactiveTrackColor: Colors.white24,

lib/pages/player/widgets/player_overlay_models.dart

@@ -5,6 +5,7 @@ import 'package:video_player/video_player.dart';
 
 import '../../../core/data/models/drama.dart';
 import '../../../core/data/services/playback_thumbnail_service.dart';
+import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../l10n/app_localizations.dart';
 
 /// 播放浮层展示数据。
@@ -26,6 +27,7 @@ class PlayerOverlayData {
     required this.boosting,
     required this.locked,
     this.thumbnailService,
+    this.spriteAxisService,
     this.authorNote = '',
   });
 
@@ -73,6 +75,7 @@ class PlayerOverlayData {
 
   /// 拖动进度时按当前集和时间点取帧。
   final PlaybackThumbnailService? thumbnailService;
+  final SpriteThumbnailAxisService? spriteAxisService;
 
   /// 作者声明；没有后端字段时为空。
   final String authorNote;

lib/pages/player/widgets/scrub_preview_card.dart

@@ -2,10 +2,12 @@
 
 import 'dart:async';
 import 'dart:typed_data';
+import 'dart:ui' as ui;
 
 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';
 
@@ -36,9 +38,13 @@ class ScrubPreviewCard extends StatefulWidget {
     required this.posterUrl,
     required this.position,
     required this.duration,
+    this.spriteAxisService,
+    this.thumbnailsUrl,
   });
 
   final PlaybackThumbnailService service;
+  final SpriteThumbnailAxisSource? spriteAxisService;
+  final String? thumbnailsUrl;
   final String episodeId;
   final String posterUrl;
   final Duration position;
@@ -49,50 +55,109 @@ class ScrubPreviewCard extends StatefulWidget {
 }
 
 class _ScrubPreviewCardState extends State<ScrubPreviewCard> {
-  ByteData? _frame;
+  ByteData? _fallbackFrame;
   int _requestSerial = 0;
   int? _requestedBucket;
+  String? _requestedEpisodeId;
 
   @override
   void initState() {
     super.initState();
-    _requestFrame();
+    widget.spriteAxisService?.addListener(_handleSpriteAxisChanged);
+    _syncFallbackSource();
   }
 
   @override
   void didUpdateWidget(covariant ScrubPreviewCard oldWidget) {
     super.didUpdateWidget(oldWidget);
-    final bucket = playbackThumbnailBucket(widget.position);
+    if (oldWidget.spriteAxisService != widget.spriteAxisService) {
+      oldWidget.spriteAxisService?.removeListener(_handleSpriteAxisChanged);
+      widget.spriteAxisService?.addListener(_handleSpriteAxisChanged);
+    }
     if (oldWidget.service != widget.service ||
         oldWidget.episodeId != widget.episodeId ||
-        _requestedBucket != bucket) {
-      _frame = null;
-      _requestFrame();
-    } else {
-      // 同 bucket 内继续拖动时不重复取帧，但会重置 120ms 预取停顿计时。
+        oldWidget.thumbnailsUrl != widget.thumbnailsUrl) {
+      _resetFallback();
+      _syncFallbackSource();
+      return;
+    }
+    if (_requestedBucket != playbackThumbnailBucket(widget.position)) {
+      _fallbackFrame = null;
+      _syncFallbackSource();
+    } else if (_fallbackFrame != null || _shouldUseLocalFallback()) {
       unawaited(widget.service.thumbnail(widget.episodeId, widget.position));
     }
   }
 
   @override
   void dispose() {
+    widget.spriteAxisService?.removeListener(_handleSpriteAxisChanged);
     _requestSerial++;
+    widget.service.cancelPending();
     super.dispose();
   }
 
-  void _requestFrame() {
+  void _handleSpriteAxisChanged() {
+    if (!mounted) return;
+    if (_spriteFrame != null) {
+      widget.service.cancelPending();
+    }
+    setState(() {});
+    _syncFallbackSource();
+  }
+
+  SpriteThumbnailFrame? get _spriteFrame => widget.spriteAxisService
+      ?.cachedFrameAt(widget.thumbnailsUrl, widget.position);
+
+  bool _shouldUseLocalFallback() {
+    if (_spriteFrame != null) return false;
+    final url = widget.thumbnailsUrl?.trim() ?? '';
+    if (url.isEmpty || widget.spriteAxisService == null) return true;
+    return widget.spriteAxisService!.hasAxis(widget.thumbnailsUrl);
+  }
+
+  void _syncFallbackSource() {
+    if (_spriteFrame != null) {
+      widget.service.cancelPending();
+      return;
+    }
+    if (!_shouldUseLocalFallback()) return;
+    _requestFallbackFrame();
+  }
+
+  void _requestFallbackFrame() {
     final bucket = playbackThumbnailBucket(widget.position);
+    if (_requestedBucket == bucket &&
+        _requestedEpisodeId == widget.episodeId &&
+        (_fallbackFrame != null || _requestSerial > 0)) {
+      return;
+    }
     _requestedBucket = bucket;
+    _requestedEpisodeId = widget.episodeId;
     final serial = ++_requestSerial;
-    final future = widget.service.thumbnail(widget.episodeId, widget.position);
-    future.then((frame) {
-      if (!mounted || serial != _requestSerial) return;
-      setState(() => _frame = frame);
+    widget.service.thumbnail(widget.episodeId, widget.position).then((frame) {
+      if (!mounted || serial != _requestSerial || _spriteFrame != null) return;
+      setState(() => _fallbackFrame = frame);
     });
   }
 
+  void _resetFallback() {
+    widget.service.cancelPending();
+    _fallbackFrame = null;
+    _requestedBucket = null;
+    _requestedEpisodeId = null;
+    _requestSerial++;
+  }
+
   @override
   Widget build(BuildContext context) {
+    final spriteFrame = _spriteFrame;
+    final stage = decideScrubPreviewStage(
+      hasThumbnailsUrl: (widget.thumbnailsUrl?.trim().isNotEmpty ?? false),
+      hasSpriteFrame: spriteFrame != null,
+      hasAxis: widget.spriteAxisService?.hasAxis(widget.thumbnailsUrl) ?? false,
+      hasLocalFrame: _fallbackFrame != null,
+    );
     return Container(
       key: const Key('scrub-preview-card'),
       width: scrubPreviewWidth,
@@ -135,11 +200,18 @@ class _ScrubPreviewCardState extends State<ScrubPreviewCard> {
                     fit: BoxFit.cover,
                     fallbackColor: AppColors.bar,
                   ),
-                  if (_frame case final frame?)
+                  if (stage == ScrubPreviewStage.sprite && spriteFrame != null)
+                    SpriteCropPreview(
+                      key: const Key('scrub-preview-sprite'),
+                      image: spriteFrame.image,
+                      sourceRect: spriteFrame.sourceRect,
+                    ),
+                  if (stage == ScrubPreviewStage.localFrame &&
+                      _fallbackFrame != null)
                     Image.memory(
-                      frame.buffer.asUint8List(
-                        frame.offsetInBytes,
-                        frame.lengthInBytes,
+                      _fallbackFrame!.buffer.asUint8List(
+                        _fallbackFrame!.offsetInBytes,
+                        _fallbackFrame!.lengthInBytes,
                       ),
                       key: const Key('scrub-preview-frame'),
                       fit: BoxFit.cover,
@@ -157,6 +229,61 @@ class _ScrubPreviewCardState extends State<ScrubPreviewCard> {
   }
 }
 
+/// 对已解码 sprite 做 sourceRect 裁剪，不触发再次解码。
+class SpriteCropPreview extends StatelessWidget {
+  const SpriteCropPreview({
+    super.key,
+    required this.image,
+    required this.sourceRect,
+  });
+
+  final ui.Image image;
+  final ui.Rect sourceRect;
+
+  @override
+  Widget build(BuildContext context) => CustomPaint(
+    painter: _SpriteCropPainter(image: image, sourceRect: sourceRect),
+  );
+}
+
+class _SpriteCropPainter extends CustomPainter {
+  const _SpriteCropPainter({required this.image, required this.sourceRect});
+
+  final ui.Image image;
+  final ui.Rect sourceRect;
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    final fitted = applyBoxFit(BoxFit.cover, sourceRect.size, size);
+    final sourceOffset = Alignment.center.inscribe(
+      fitted.source,
+      Offset.zero & sourceRect.size,
+    );
+    final source = Rect.fromLTWH(
+      sourceRect.left + sourceOffset.left,
+      sourceRect.top + sourceOffset.top,
+      fitted.source.width,
+      fitted.source.height,
+    );
+    final destination = Alignment.center.inscribe(
+      fitted.destination,
+      Offset.zero & size,
+    );
+    canvas.drawImageRect(
+      image,
+      source,
+      destination,
+      Paint()
+        ..filterQuality = FilterQuality.low
+        ..isAntiAlias = false,
+    );
+  }
+
+  @override
+  bool shouldRepaint(covariant _SpriteCropPainter oldDelegate) =>
+      oldDelegate.image != image || oldDelegate.sourceRect != sourceRect;
+}
+
 String _format(Duration value) {
   final minutes = value.inMinutes.remainder(60).toString().padLeft(2, '0');
   final seconds = value.inSeconds.remainder(60).toString().padLeft(2, '0');

lib/pages/player/widgets/seek_progress_bar.dart

@@ -7,6 +7,7 @@ import 'package:flutter/material.dart';
 import 'package:video_player/video_player.dart';
 
 import '../../../core/data/services/playback_thumbnail_service.dart';
+import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../core/theme/app_colors.dart';
 import 'loading_progress_track.dart';
 import 'scrub_preview_card.dart';
@@ -35,8 +36,10 @@ class SeekProgressBar extends StatefulWidget {
     this.inactiveTrackColor = AppColors.border,
     this.locked = false,
     this.thumbnailService,
+    this.spriteAxisService,
     this.episodeId,
     this.posterUrl = '',
+    this.thumbnailsUrl,
   });
 
   final ValueListenable<VideoPlayerValue>? valueListenable;
@@ -48,8 +51,10 @@ class SeekProgressBar extends StatefulWidget {
   final Color inactiveTrackColor;
   final bool locked;
   final PlaybackThumbnailService? thumbnailService;
+  final SpriteThumbnailAxisService? spriteAxisService;
   final String? episodeId;
   final String posterUrl;
+  final String? thumbnailsUrl;
 
   @override
   State<SeekProgressBar> createState() => _SeekProgressBarState();
@@ -299,6 +304,8 @@ class _SeekProgressBarState extends State<SeekProgressBar> {
                 bottom: trackAreaHeight + 8,
                 child: ScrubPreviewCard(
                   service: widget.thumbnailService!,
+                  spriteAxisService: widget.spriteAxisService,
+                  thumbnailsUrl: widget.thumbnailsUrl,
                   episodeId: widget.episodeId!,
                   posterUrl: widget.posterUrl,
                   position: previewPosition,