fix(subtitle): resolve overlay pause/seek update delays with immediate state sync (#153)

* fix(subtitle): resolve overlay pause/seek update delays with immediate state sync

- Add immediate store updates in PlayerOrchestrator during seek/jumpToCue
- Implement UserSeeking state in PlayerSettingsSaver to prevent conflicts
- Ensure subtitle overlay UI responds instantly to user interactions
- Maintain data consistency during user-initiated time changes

* Update src/renderer/src/pages/player/engine/PlayerOrchestrator.ts

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update src/renderer/src/services/PlayerSettingsSaver.ts

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* fix(player): resolve seeking event mismatch causing duplicate subtitle jumps

- Add missing mediaClock.startSeeking() call in PlayerOrchestrator.onSeeking()
- Fix SeekEventCoordinator state inconsistency between start/end seeking events
- Eliminate 'Ignoring seeked without active seeking' warnings in console
- Ensure proper event sequence for both paused and playing states
- All 66 player engine tests pass with TypeScript and lint validation

Resolves issue where users needed to press subtitle buttons twice in paused state.

* refactor(player): Use destroyOnHidden instead of destoryOnClose.

* fix(player): prevent SubtitleSyncStrategy from overriding user subtitle jumps

- Lock subtitle state machine for 2 seconds after user subtitle jump
- Prevent SubtitleSyncStrategy from immediately overriding user selection
- Add automatic unlock mechanism to restore normal subtitle sync behavior
- Ensure 'goToNextSubtitle' respects user intent in paused state
- Fix seeking event coordination in PlayerOrchestrator.onSeeking()

Resolves the core issue where clicking to jump to a subtitle would
be immediately overridden by the subtitle sync strategy, requiring
users to click twice to achieve their intended jump.

* fix(subtitle): eliminate subtitle content flickering during jumps

- Add activeCueIndex to PlayerState and StateUpdater interface
- Sync PlayerOrchestrator's activeCueIndex to store on updates
- Modify useSubtitleEngine to prioritize store's activeCueIndex over time-based calculation
- Ensure SubtitleContent component uses authoritative subtitle index
- Fix initial activeCueIndex synchronization on StateUpdater connection

Resolves flickering where subtitle content would briefly show wrong subtitle
before displaying the correct one during user-initiated subtitle jumps.

* fix(subtitle): eliminate subtitle overlay flickering during jumps

- Add smart tolerance mechanism to useSubtitleOverlay shouldShow calculation
- Display overlay when currentTime is within 2 seconds of subtitle start time
- Handles user jump delays while preserving smooth normal playback behavior
- Fixes flickering issue where overlay would briefly hide during subtitle navigation

Closes final flickering issue in subtitle navigation system.

* fix(subtitle): resolve overlay flickering through index priority and data stabilization

- Add stable subtitle data memoization in useSubtitleOverlay to prevent unnecessary re-renders
- Prioritize currentIndex over time-based checks in shouldShow calculation
- Reorder PlayerOrchestrator lock sequence to ensure SubtitleLockFSM is active during updateContext
- Implement granular dependency tracking for subtitle content changes

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: mkdir700

src/renderer/src/pages/player/components/VideoErrorRecovery.tsx

@@ -166,7 +166,7 @@ function VideoErrorRecovery({
         width={480}
         closable={false}
         maskClosable={false}
-        destroyOnClose
+        destroyOnHidden
       >
         <ModalContent>
           <VideoTitle title={videoTitle}>{videoTitle}</VideoTitle>

src/renderer/src/pages/player/engine/PlayerOrchestrator.ts

@@ -56,6 +56,7 @@ export interface StateUpdater {
   setMuted(muted: boolean): void
   setSeeking?(seeking: boolean): void
   setEnded?(ended: boolean): void
+  setActiveCueIndex?(index: number): void
   updateUIState(updates: { openAutoResumeCountdown?: boolean }): void
 }
 
@@ -203,6 +204,12 @@ export class PlayerOrchestrator {
    */
   connectStateUpdater(updater: StateUpdater): void {
     this.stateUpdater = updater
+
+    // 立即同步当前的 activeCueIndex 到 store
+    if (updater.setActiveCueIndex) {
+      updater.setActiveCueIndex(this.context.activeCueIndex)
+    }
+
     logger.debug('State updater connected')
   }
 
@@ -220,6 +227,11 @@ export class PlayerOrchestrator {
     const prevContext = { ...this.context }
     this.context = { ...this.context, ...updates }
 
+    // 同步 activeCueIndex 到 store（如果有变化）
+    if (updates.activeCueIndex !== undefined && this.stateUpdater?.setActiveCueIndex) {
+      this.stateUpdater.setActiveCueIndex(updates.activeCueIndex)
+    }
+
     if (this.config.enableDebugLogs) {
       const changedFields = Object.keys(updates).filter(
         (key) => prevContext[key as keyof PlaybackContext] !== updates[key as keyof PlaybackContext]
@@ -418,6 +430,18 @@ export class PlayerOrchestrator {
     // 重置播放器状态（清理意图、重置字幕锁定、重载策略）
     this.resetOnUserSeek()
 
+    // 标记用户跳转状态，暂时禁用自动保存
+    import('@renderer/services/PlayerSettingsSaver').then(
+      ({ playerSettingsPersistenceService }) => {
+        playerSettingsPersistenceService.markUserSeeking()
+      }
+    )
+
+    // 立即更新 store 中的 currentTime，确保 UI 组件能立即响应
+    if (this.stateUpdater) {
+      this.stateUpdater.setCurrentTime(to)
+    }
+
     // 执行跳转
     const clampedTime = Math.max(0, Math.min(this.context.duration || Infinity, to))
     this.videoController.seek(clampedTime)
@@ -451,8 +475,33 @@ export class PlayerOrchestrator {
 
     // 重置播放器状态（清理意图、重置字幕锁定、重载策略）
     this.resetOnUserSeek()
-    this.context.currentTime = cue.startTime
-    this.context.activeCueIndex = index
+
+    // 立即锁定字幕状态机，防止 SubtitleSyncStrategy 在 updateContext 时覆盖用户选择
+    this.subtitleLockFSM.lock('user_seek', index)
+
+    this.updateContext({ currentTime: cue.startTime, activeCueIndex: index })
+
+    // 设置定时器，2秒后自动解锁，允许自动同步策略重新生效
+    this.userSeekTaskId = this.clockScheduler.scheduleAfter(
+      2000, // 2秒延迟
+      () => {
+        this.subtitleLockFSM.unlock('user_seek')
+        this.userSeekTaskId = null
+        logger.debug('用户跳转锁定已自动解除')
+      },
+      'user_seek_unlock'
+    )
+    // 标记用户跳转状态，暂时禁用自动保存
+    import('@renderer/services/PlayerSettingsSaver').then(
+      ({ playerSettingsPersistenceService }) => {
+        playerSettingsPersistenceService.markUserSeeking()
+      }
+    )
+
+    // 立即更新 store 中的 currentTime，确保字幕 overlay 能立即响应
+    if (this.stateUpdater) {
+      this.stateUpdater.setCurrentTime(cue.startTime)
+    }
 
     // 执行跳转
     const clampedTime = Math.max(0, Math.min(this.context.duration || Infinity, cue.startTime))
@@ -590,6 +639,7 @@ export class PlayerOrchestrator {
   }
 
   onSeeking(): void {
+    this.mediaClock.startSeeking()
     this.stateUpdater?.setSeeking?.(true)
   }
 
@@ -662,8 +712,6 @@ export class PlayerOrchestrator {
    * 清理未发布的意图、重置字幕锁定状态、重载所有策略
    */
   private resetOnUserSeek(): void {
-    logger.debug('用户跳转，重置播放器状态')
-
     // 清理未发布的意图
     if (this.currentIntents.length > 0) {
       logger.debug(`清理 ${this.currentIntents.length} 个未发布的意图`)
@@ -683,7 +731,7 @@ export class PlayerOrchestrator {
     // 重载策略管理器
     this.strategyManager.reload(currentStrategies)
 
-    logger.debug('播放器状态重置完成')
+    logger.debug('用户跳转，播放器状态重置完成')
   }
 
   private registerBuiltinStrategies(): void {

src/renderer/src/pages/player/engine/intent/IntentStrategyManager.ts

@@ -190,7 +190,6 @@ export class IntentStrategyManager {
     for (const strategy of strategiesToReload) {
       try {
         this.registerStrategy(strategy)
-        logger.debug(`重新挂载策略: ${strategy.name}`)
       } catch (error) {
         logger.error(`重新挂载策略 ${strategy.name} 失败:`, { error })
       }

src/renderer/src/pages/player/hooks/usePlayerEngine.ts

@@ -55,6 +55,10 @@ function getOrCreateGlobalStateUpdater(): StateUpdater {
         // TODO: 如果需要，可以在 player store 中添加 ended 状态
         logger.debug('Ended state updated:', { ended })
       },
+      setActiveCueIndex: (index: number) => {
+        usePlayerStore.getState().setActiveCueIndex(index)
+        logger.debug('Active cue index updated:', { index })
+      },
       // UI状态更新处理
       updateUIState: (updates: { openAutoResumeCountdown?: boolean }) => {
         logger.debug('Processing UI state updates:', { updates })

src/renderer/src/pages/player/hooks/useSubtitleEngine.ts

@@ -19,6 +19,7 @@ interface SubtitleEngine {
 export function useSubtitleEngine(): SubtitleEngine {
   const subtitles = useSubtitles()
   const currentTime = usePlayerStore((s) => s.currentTime)
+  const storeActiveCueIndex = usePlayerStore((s) => s.activeCueIndex)
 
   // 创建时间索引，用于二分查找优化
   const timeIndex = useMemo(() => {
@@ -78,10 +79,15 @@ export function useSubtitleEngine(): SubtitleEngine {
     }
   }, [findIndexByTime, subtitles])
 
-  // 当前字幕和索引
+  // 当前字幕和索引 - 优先使用 PlayerOrchestrator 的 activeCueIndex，回退到基于时间的计算
   const currentIndex = useMemo(() => {
+    // 如果 PlayerOrchestrator 提供了有效的 activeCueIndex，直接使用
+    if (storeActiveCueIndex >= 0 && storeActiveCueIndex < subtitles.length) {
+      return storeActiveCueIndex
+    }
+    // 否则回退到基于时间的计算
     return findIndexByTime(currentTime)
-  }, [findIndexByTime, currentTime])
+  }, [storeActiveCueIndex, subtitles.length, findIndexByTime, currentTime])
 
   const currentSubtitle = useMemo(() => {
     return currentIndex >= 0 ? subtitles[currentIndex] : null

src/renderer/src/pages/player/hooks/useSubtitleOverlay.ts

@@ -55,41 +55,77 @@ export function useSubtitleOverlay(): SubtitleOverlay {
     }
   }, [currentSubtitle, currentIndex])
 
+  // === 缓存当前字幕数据以防止不必要的重新渲染 ===
+  const stableCurrentSubtitle = useMemo(() => {
+    if (!currentSubtitleData) return null
+
+    // 只有当内容实际变化时才返回新对象
+    return {
+      originalText: currentSubtitleData.originalText,
+      translatedText: currentSubtitleData.translatedText,
+      startTime: currentSubtitleData.startTime,
+      endTime: currentSubtitleData.endTime,
+      index: currentSubtitleData.index
+    }
+  }, [
+    currentSubtitleData?.originalText,
+    currentSubtitleData?.translatedText,
+    currentSubtitleData?.startTime,
+    currentSubtitleData?.endTime,
+    currentSubtitleData?.index
+  ])
+
   // === 计算是否应该显示 ===
   const shouldShow = useMemo(() => {
     // 基础条件：显示模式不为 NONE 且有字幕数据
-    if (subtitleOverlayConfig.displayMode === SubtitleDisplayMode.NONE || !currentSubtitleData) {
+    if (subtitleOverlayConfig.displayMode === SubtitleDisplayMode.NONE || !stableCurrentSubtitle) {
       return false
     }
 
-    // 时间边界检查：确保当前播放时间在字幕的时间范围内
+    // 优先检查：如果当前字幕索引与 engine 提供的索引一致，说明这是权威数据，直接显示
+    // 这可以避免用户跳转时因时间不同步导致的闪烁
+    if (currentIndex >= 0 && stableCurrentSubtitle.index === currentIndex) {
+      return true
+    }
+
+    // 正常的时间边界检查：确保当前播放时间在字幕的时间范围内
     const isInTimeRange =
-      currentTime >= currentSubtitleData.startTime && currentTime <= currentSubtitleData.endTime
+      currentTime >= stableCurrentSubtitle.startTime && currentTime <= stableCurrentSubtitle.endTime
+
+    // 如果在时间范围内，直接显示
+    if (isInTimeRange) {
+      return true
+    }
+
+    // 智能容差机制：处理播放时的短暂时间不同步问题
+    // 如果当前时间接近字幕开始时间，也应该显示（防止跳转闪烁）
+    const timeDiffToStart = Math.abs(currentTime - stableCurrentSubtitle.startTime)
+    const isNearStart = timeDiffToStart <= 2.0 // 2秒容差，处理跳转延迟
 
-    return isInTimeRange
-  }, [subtitleOverlayConfig.displayMode, currentSubtitleData, currentTime])
+    return isNearStart
+  }, [subtitleOverlayConfig.displayMode, stableCurrentSubtitle, currentTime, currentIndex])
 
   // === 计算显示文本 ===
   const displayText = useMemo(() => {
-    if (!currentSubtitleData || !shouldShow || !subtitleOverlayConfig) return ''
+    if (!stableCurrentSubtitle || !shouldShow || !subtitleOverlayConfig) return ''
 
     switch (subtitleOverlayConfig.displayMode) {
       case SubtitleDisplayMode.ORIGINAL:
-        return currentSubtitleData.originalText
+        return stableCurrentSubtitle.originalText
 
       case SubtitleDisplayMode.TRANSLATED:
-        return currentSubtitleData.translatedText || currentSubtitleData.originalText
+        return stableCurrentSubtitle.translatedText || stableCurrentSubtitle.originalText
 
       case SubtitleDisplayMode.BILINGUAL:
-        if (currentSubtitleData.translatedText) {
-          return `${currentSubtitleData.originalText}\n${currentSubtitleData.translatedText}`
+        if (stableCurrentSubtitle.translatedText) {
+          return `${stableCurrentSubtitle.originalText}\n${stableCurrentSubtitle.translatedText}`
         }
-        return currentSubtitleData.originalText
+        return stableCurrentSubtitle.originalText
 
       default:
         return ''
     }
-  }, [subtitleOverlayConfig, currentSubtitleData, shouldShow])
+  }, [subtitleOverlayConfig, stableCurrentSubtitle, shouldShow])
 
   // === 配置操作的包装器（添加 PlayerStore 同步） ===
   const setDisplayModeWithSync = useCallback(
@@ -141,7 +177,7 @@ export function useSubtitleOverlay(): SubtitleOverlay {
   )
 
   return {
-    currentSubtitle: currentSubtitleData,
+    currentSubtitle: stableCurrentSubtitle,
     shouldShow,
     displayText,
     setDisplayMode: setDisplayModeWithSync,

src/renderer/src/services/PlayerSettingsLoader.ts

@@ -41,6 +41,7 @@ export class PlayerSettingsService {
       duration: 0,
       paused: true,
       isFullscreen: false,
+      activeCueIndex: -1,
 
       // 从全局设置获取的默认值
       volume: globalSettings.defaultVolume,
@@ -179,6 +180,7 @@ export class PlayerSettingsService {
       duration: 0,
       paused: true,
       isFullscreen: false,
+      activeCueIndex: -1,
 
       // 从数据库恢复的设置
       volume: dbData.volume,

src/renderer/src/services/PlayerSettingsSaver.ts

@@ -38,13 +38,20 @@ export class PlayerSettingsPersistenceService {
   private debounceTimer: NodeJS.Timeout | null = null
   private readonly debounceMs = 1200
 
+  // 用户跳转时暂时禁用自动保存的标志位
+  private isUserSeeking = false
+  private userSeekingTimer: NodeJS.Timeout | null = null
+  private currentVideoId: number | null = null
+
   attach(videoId: number) {
     this.detach()
     if (!videoId || videoId <= 0) {
       logger.warn('attach: 无效 videoId，跳过', { videoId })
       return
     }
 
+    this.currentVideoId = videoId
+
     // 订阅持久化切片变化（手动在回调内比较，避免类型不匹配问题）
     this.unsubscribe = usePlayerStore.subscribe((state, prevState) => {
       const slice = selectPersistedSlice(state)
@@ -77,7 +84,63 @@ export class PlayerSettingsPersistenceService {
       clearTimeout(this.debounceTimer)
       this.debounceTimer = null
     }
+    if (this.debounceCurrentTimeTimer) {
+      clearTimeout(this.debounceCurrentTimeTimer)
+      this.debounceCurrentTimeTimer = null
+    }
+    if (this.userSeekingTimer) {
+      clearTimeout(this.userSeekingTimer)
+      this.userSeekingTimer = null
+    }
     this.lastSaved = null
+    this.isUserSeeking = false
+    this.currentVideoId = null
+  }
+
+  /**
+   * 标记用户正在跳转，暂时禁用 currentTime 的自动保存
+   */
+  markUserSeeking() {
+    this.isUserSeeking = true
+
+    // 取消可能已排队的进度保存任务，避免与用户跳转状态竞争
+    if (this.debounceCurrentTimeTimer) {
+      clearTimeout(this.debounceCurrentTimeTimer)
+      this.debounceCurrentTimeTimer = null
+    }
+
+    // 清除之前的定时器
+    if (this.userSeekingTimer) {
+      clearTimeout(this.userSeekingTimer)
+    }
+
+    // 在略长于 debounceCurrentTimeMs 的时间后恢复自动保存并立即保存一次
+    const resumeAfterMs = this.debounceCurrentTimeMs + 200
+    this.userSeekingTimer = setTimeout(async () => {
+      this.isUserSeeking = false
+      this.userSeekingTimer = null
+
+      // 立即保存一次当前播放进度，确保用户跳转后的位置被记录
+      if (this.currentVideoId) {
+        try {
+          const currentTime = usePlayerStore.getState().currentTime
+          await window.api.db.videoLibrary.updatePlayProgress(this.currentVideoId, currentTime)
+          logger.debug('用户跳转状态已恢复，立即保存当前进度', {
+            videoId: this.currentVideoId,
+            currentTime
+          })
+        } catch (error) {
+          logger.error('用户跳转状态恢复时保存进度失败', {
+            videoId: this.currentVideoId,
+            error
+          })
+        }
+      }
+
+      logger.debug('用户跳转状态已恢复，重新启用进度自动保存')
+    }, resumeAfterMs)
+
+    logger.debug('已标记用户跳转状态，暂时禁用进度自动保存')
   }
 
   private onSliceChanged(videoId: number, slice: PlayerSettings) {
@@ -100,6 +163,12 @@ export class PlayerSettingsPersistenceService {
   }
 
   private onCurrentTimeChanged(videoId: number, currentTime: number) {
+    // 如果用户正在跳转，跳过自动保存
+    if (this.isUserSeeking) {
+      logger.debug('用户正在跳转，跳过进度自动保存', { videoId, currentTime })
+      return
+    }
+
     if (this.debounceCurrentTimeTimer) clearTimeout(this.debounceCurrentTimeTimer)
     this.debounceCurrentTimeTimer = setTimeout(async () => {
       try {