feat(player/subtitle): comprehensive subtitle overlay improvements (#226)

* refactor(player): extract subtitle overlay logic into separate hooks and utilities

* refactor(player): enhance subtitle styling and introduce content width hook

- Updated SubtitleContent component to use fixed line-height and color values.
- Modified text handling in OriginalTextLine and TranslatedTextLine for better word wrapping and alignment.
- Added useContentWidth hook to manage dynamic width styling for subtitles, improving layout consistency.
- Adjusted SubtitleOverlay to utilize new width styles for better responsiveness in non-mask mode.

* refactor(player): improve drag bounds calculation for mask mode

- Enhanced the calculateDragBounds function to ensure that subtitle components remain fully within the mask area by calculating absolute dimensions based on the mask viewport.
- Introduced logic to prevent overflow of the right and bottom edges of the mask, improving the overall layout and user experience in mask mode.

* refactor(subtitle-overlay): show resize handle only on hover in mask mode

- Change resize handle visibility condition to require both mask mode and hover state
- Reduce visual clutter by hiding resize handle when not actively interacting

* fix(player/subtitle): correct token rendering and selection logic

- Render non-clickable tokens as plain spans instead of WordToken components
- Only apply selection/hover states to clickable tokens
- Simplify WordToken styling by removing conditional clickable styles
- Improve performance by reducing unnecessary component rendering

* refactor(subtitle-overlay): centralize selected text state management

- Move selected text state from UI hook to player store for global access
- Add setSelectedText action in player store to update selected text
- Remove local selectedText state from SubtitleOverlayUI hook
- Enhance text selection logic with additional logging for debugging
- Clear selected text on mouse leave and outside click events
- Maintain backward compatibility with existing onTextSelection callback

* fix(player/subtitle): resolve toast display conflicts and coordinate transform issues

- Fix toast disappearing issue: add toast type differentiation to prevent mask-onboarding logic from interfering with copy success toast
- Fix syntax errors: incomplete variable declaration and undefined variable references in coordinateTransform.ts
- Clean up logging: remove duplicate logger.debug calls and unused variable references

* fix(player/subtitle): remove unused heightLimit variable to resolve TypeScript error

* fix(player/subtitle): type resize handle events for div

- update `onMouseDown` and `onDoubleClick` to use `React.MouseEvent<HTMLDivElement>`
- improve type safety by matching the actual element

* refactor(player/subtitle): remove duplicate useSubtitleOverlay calls and redundant onTextSelection forwarding

- Remove duplicate useSubtitleOverlay hook call in SubtitleOverlay.tsx
- Remove unnecessary handleTextSelection callback and onTextSelection prop forwarding
- Remove onTextSelection parameter from SubtitleContent interface and implementation
- Simplify text selection state management by using only internal setSelectedText calls
- Update dependency arrays in useCallback and useEffect hooks
- Improve performance by reducing redundant store subscriptions

* refactor(player): remove unused mode change handling in mask viewport hook

- remove onModeChange callback from UseMaskViewportOptions
- remove onModeChange parameter from hook implementation
- eliminate previousMaskModeRef and mode change effect
- clean up unused dependencies in hook implementation

* fix(player/subtitle): clear selected text on subtitle change

- Add useEffect to clear selected text when subtitle index changes
- Prevent stale text selection when new subtitle appears

* fix(player/subtitle): use correct height limit constant in normal mode

- replace MAX_OVERLAY_WIDTH_PERCENT with MAX_OVERLAY_HEIGHT_PERCENT_NORMAL_MODE for heightLimit
- ensure subtitle overlay height is properly limited to 40% in normal mode

* fix(player/subtitle): update drag bounds when overlay size changes

Add updateLatestSize function to useSubtitleDrag hook to ensure latestSizeRef is updated when overlay size changes. This fixes incorrect bottom boundary detection during drag operations after overlay height changes.

- Add updateLatestSize callback in useSubtitleDrag hook
- Use updateLatestSizeFromDrag in SubtitleOverlay component
- Ensure drag boundary calculations use current overlay dimensions

Fixes issue where overlay bottom boundary detection was incorrect after height changes, as drag calculations were using stale size references.

* chore(test): remove SubtitleDictionaryLookup.test.tsx

- remove SubtitleDictionaryLookup.test.tsx
- this test file is no longer needed

Author: mkdir700

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

@@ -0,0 +1,96 @@
+/**
+ * SubtitleResizeHandle Component
+ *
+ * 独立的调整尺寸句柄组件：
+ * - 只在遮罩模式下渲染
+ * - 包含 Tooltip
+ * - 处理鼠标事件
+ * - 包含样式定义
+ * - 支持主题变量适配
+ */
+
+import { ANIMATION_DURATION, EASING } from '@renderer/infrastructure/styles/theme'
+import { Tooltip } from 'antd'
+import React, { memo } from 'react'
+import { useTranslation } from 'react-i18next'
+import styled from 'styled-components'
+
+export interface SubtitleResizeHandleProps {
+  /** 句柄是否可见 */
+  visible: boolean
+  /** 鼠标按下事件处理 */
+  onMouseDown: (event: React.MouseEvent<HTMLDivElement>) => void
+  /** 双击事件处理 */
+  onDoubleClick: (event: React.MouseEvent<HTMLDivElement>) => void
+  /** 自定义 className */
+  className?: string
+  /** 测试 ID */
+  testId?: string
+}
+
+/**
+ * 调整尺寸句柄组件
+ */
+export const SubtitleResizeHandle = memo(function SubtitleResizeHandle({
+  visible,
+  onMouseDown,
+  onDoubleClick,
+  className,
+  testId = 'subtitle-resize-handle'
+}: SubtitleResizeHandleProps) {
+  const { t } = useTranslation()
+
+  if (!visible) {
+    return null
+  }
+
+  return (
+    <Tooltip
+      title={t('settings.playback.subtitle.overlay.resizeHandle.tooltip')}
+      placement="top"
+      mouseEnterDelay={0.5}
+      mouseLeaveDelay={0}
+    >
+      <ResizeHandle
+        className={className}
+        $visible={visible}
+        onMouseDown={onMouseDown}
+        onDoubleClick={onDoubleClick}
+        data-testid={testId}
+      />
+    </Tooltip>
+  )
+})
+
+export default SubtitleResizeHandle
+
+// === 样式组件 ===
+
+const ResizeHandle = styled.div<{ $visible: boolean }>`
+  position: absolute;
+  bottom: -4px;
+  right: -4px;
+  width: 12px;
+  height: 12px;
+
+  /* 使用主题变量支持主题切换 */
+  background: var(--ant-color-primary, rgba(102, 126, 234, 0.8));
+  border: 2px solid var(--ant-color-white, rgba(255, 255, 255, 0.9));
+  border-radius: 50%;
+  cursor: nw-resize;
+
+  opacity: ${(props) => (props.$visible ? 1 : 0)};
+  transition: all ${ANIMATION_DURATION.MEDIUM} ${EASING.STANDARD};
+
+  &:hover {
+    background: var(--ant-color-primary-hover, var(--ant-color-primary));
+    transform: scale(1.2);
+
+    /* 使用主题变量 */
+    box-shadow: var(--ant-box-shadow-secondary, 0 2px 8px rgba(102, 126, 234, 0.4));
+  }
+
+  &:active {
+    transform: scale(1.1);
+  }
+`

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

@@ -0,0 +1,79 @@
+/**
+ * SubtitleToast Component
+ *
+ * 独立的 Toast 通知组件：
+ * - 接收 visible 和 message props
+ * - 包含样式组件定义
+ * - 支持自动隐藏逻辑
+ * - 使用主题变量适配深色/浅色模式
+ */
+
+import {
+  ANIMATION_DURATION,
+  BORDER_RADIUS,
+  EASING,
+  FONT_SIZES,
+  FONT_WEIGHTS,
+  GLASS_EFFECT,
+  SHADOWS,
+  SPACING,
+  Z_INDEX
+} from '@renderer/infrastructure/styles/theme'
+import { memo } from 'react'
+import styled from 'styled-components'
+
+export interface SubtitleToastProps {
+  /** Toast 是否可见 */
+  visible: boolean
+  /** Toast 消息内容 */
+  message: string
+  /** 自动隐藏延迟时间（毫秒），0 表示不自动隐藏 */
+  autoHideDelay?: number
+  /** onAutoHide?: () => void - 可选的自动隐藏回调 */
+}
+
+/**
+ * Toast 通知组件
+ */
+export const SubtitleToast = memo(function SubtitleToast({ visible, message }: SubtitleToastProps) {
+  if (!visible || !message) {
+    return null
+  }
+
+  return (
+    <ToastContainer $visible={visible} role="status" aria-live="polite" aria-atomic="true">
+      <ToastContent>{message}</ToastContent>
+    </ToastContainer>
+  )
+})
+
+export default SubtitleToast
+
+// === 样式组件 ===
+
+const ToastContainer = styled.div<{ $visible: boolean }>`
+  position: absolute;
+  top: -40px;
+  left: 50%;
+  transform: translateX(-50%);
+  opacity: ${(props) => (props.$visible ? 1 : 0)};
+  visibility: ${(props) => (props.$visible ? 'visible' : 'hidden')};
+  transition: opacity ${ANIMATION_DURATION.SLOW} ${EASING.APPLE};
+  z-index: ${Z_INDEX.MODAL};
+  pointer-events: none;
+`
+
+const ToastContent = styled.div`
+  /* 使用 CSS 变量支持主题切换 */
+  background: var(--ant-color-bg-elevated, rgba(0, 0, 0, ${GLASS_EFFECT.BACKGROUND_ALPHA.LIGHT}));
+  color: var(--ant-color-text, #ffffff);
+  padding: ${SPACING.XS}px ${SPACING.MD}px;
+  border-radius: ${BORDER_RADIUS.SM}px;
+  font-size: ${FONT_SIZES.SM}px;
+  font-weight: ${FONT_WEIGHTS.MEDIUM};
+  white-space: nowrap;
+  backdrop-filter: blur(${GLASS_EFFECT.BLUR_STRENGTH.SUBTLE}px);
+  border: 1px solid
+    var(--ant-color-border, rgba(255, 255, 255, ${GLASS_EFFECT.BORDER_ALPHA.SUBTLE}));
+  box-shadow: var(--ant-box-shadow-secondary, ${SHADOWS.SM});
+`

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

@@ -11,6 +11,8 @@ export { default as SettingsPopover } from './SettingsPopover'
 export { default as SubtitleContent } from './SubtitleContent'
 export { default as SubtitleListPanel } from './SubtitleListPanel'
 export { default as SubtitleOverlay } from './SubtitleOverlay'
+export { default as SubtitleResizeHandle } from './SubtitleResizeHandle'
+export { default as SubtitleToast } from './SubtitleToast'
 export { default as SubtitleTrackSelector } from './SubtitleTrackSelector'
 export { default as VideoErrorRecovery } from './VideoErrorRecovery'
 export { default as VideoSurface } from './VideoSurface'

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

@@ -1,4 +1,9 @@
+export { useContainerBounds } from './useContainerBounds'
+export { useContentWidth } from './useContentWidth'
+export { useMaskViewport } from './useMaskViewport'
 export { usePlayerEngine } from './usePlayerEngine'
+export { useSubtitleDrag } from './useSubtitleDrag'
 export { useSubtitleEngine } from './useSubtitleEngine'
 export { useSubtitleOverlay } from './useSubtitleOverlay'
 export { useSubtitleOverlayUI } from './useSubtitleOverlayUI'
+export { useSubtitleResize } from './useSubtitleResize'

src/renderer/src/pages/player/components/index.ts

@@ -0,0 +1,165 @@
+/**
+ * useContainerBounds Hook
+ *
+ * 管理容器尺寸变化和冲突检测：
+ * - 容器边界更新
+ * - ResizeObserver 监听
+ * - 冲突区域检测
+ * - 智能避让逻辑
+ */
+
+import { SubtitleDisplayMode } from '@types'
+import { useCallback, useEffect } from 'react'
+
+export interface ConflictArea {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface UseContainerBoundsOptions {
+  containerRef?: React.RefObject<HTMLElement | null>
+  displayMode: SubtitleDisplayMode
+  currentConfig?: { isInitialized?: boolean }
+  updateContainerBounds: (bounds: { width: number; height: number }) => void
+  adaptToContainerResize: (bounds: { width: number; height: number }) => void
+  avoidCollision: (conflicts: ConflictArea[]) => void
+}
+
+export function useContainerBounds({
+  containerRef,
+  displayMode,
+  currentConfig,
+  updateContainerBounds,
+  adaptToContainerResize,
+  avoidCollision
+}: UseContainerBoundsOptions) {
+  // === 容器边界更新 ===
+  useEffect(() => {
+    let resizeTimer: NodeJS.Timeout
+
+    const updateBounds = (isInitial = false) => {
+      const container =
+        containerRef?.current || document.querySelector('[data-testid="video-surface"]')
+      if (container) {
+        const rect = container.getBoundingClientRect()
+        const newBounds = { width: rect.width, height: rect.height }
+
+        if (isInitial || !currentConfig?.isInitialized) {
+          // 初始化时使用 updateContainerBounds
+          updateContainerBounds(newBounds)
+        } else {
+          // 容器尺寸变化时使用智能适应
+          adaptToContainerResize(newBounds)
+        }
+      }
+    }
+
+    const handleResize = () => {
+      // 防抖处理，避免频繁重新计算
+      clearTimeout(resizeTimer)
+      resizeTimer = setTimeout(() => updateBounds(false), 150)
+    }
+
+    // 初始化
+    updateBounds(true)
+
+    // 监听窗口尺寸变化
+    window.addEventListener('resize', handleResize)
+
+    // 监听全屏模式变化（可能导致容器尺寸变化）
+    let observer: ResizeObserver | null = null
+
+    if (typeof ResizeObserver !== 'undefined') {
+      observer = new ResizeObserver((entries) => {
+        for (const entry of entries) {
+          if (
+            entry.target ===
+            (containerRef?.current || document.querySelector('[data-testid="video-surface"]'))
+          ) {
+            handleResize()
+          }
+        }
+      })
+
+      const container =
+        containerRef?.current || document.querySelector('[data-testid="video-surface"]')
+      if (container) {
+        observer.observe(container)
+      }
+    }
+
+    return () => {
+      clearTimeout(resizeTimer)
+      window.removeEventListener('resize', handleResize)
+      if (observer && typeof observer.disconnect === 'function') {
+        observer.disconnect()
+      }
+    }
+  }, [containerRef, updateContainerBounds, adaptToContainerResize, currentConfig?.isInitialized])
+
+  // === 冲突区域检测 ===
+  const detectConflictAreas = useCallback((): ConflictArea[] => {
+    const conflictSelectors = [
+      '[data-testid="controller-panel"]',
+      '[data-testid="transport-bar"]',
+      '[aria-label="transport-bar"]',
+      '.progress-section',
+      '.controller-panel'
+    ]
+
+    const conflictAreas: ConflictArea[] = []
+    const container =
+      containerRef?.current || document.querySelector('[data-testid="video-surface"]')
+
+    if (!container) return conflictAreas
+
+    const containerRect = container.getBoundingClientRect()
+
+    conflictSelectors.forEach((selector) => {
+      const element = document.querySelector(selector) as HTMLElement
+      if (element && element.offsetParent) {
+        // 确保元素可见
+        const rect = element.getBoundingClientRect()
+
+        // 转换为相对于容器的百分比坐标
+        const relativeArea = {
+          x: ((rect.left - containerRect.left) / containerRect.width) * 100,
+          y: ((rect.top - containerRect.top) / containerRect.height) * 100,
+          width: (rect.width / containerRect.width) * 100,
+          height: (rect.height / containerRect.height) * 100
+        }
+
+        // 只关注可能与字幕区域重叠的元素
+        if (relativeArea.y > 50) {
+          // 只检测下半部分
+          conflictAreas.push(relativeArea)
+        }
+      }
+    })
+
+    return conflictAreas
+  }, [containerRef])
+
+  // === 智能冲突检测 ===
+  useEffect(() => {
+    // 定期检测冲突区域（UI 元素可能动态显示/隐藏）
+    const conflictCheckTimer = setInterval(() => {
+      if (displayMode !== SubtitleDisplayMode.NONE) {
+        const conflicts = detectConflictAreas()
+        if (conflicts.length > 0) {
+          avoidCollision(conflicts)
+        }
+      }
+    }, 2000) // 每 2 秒检测一次
+
+    return () => {
+      clearInterval(conflictCheckTimer)
+    }
+  }, [detectConflictAreas, displayMode, avoidCollision])
+
+  return {
+    detectConflictAreas
+  }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * useContentWidth Hook
+ *
+ * 采用 YouTube 风格的字幕宽度控制方案：
+ * - 使用 CSS 的 max-content (fit-content) 让内容自然决定宽度
+ * - 通过 max-width 限制最大宽度为 95%
+ * - 完全由 CSS 处理，无需 JavaScript 计算
+ *
+ * 优势：
+ * - ✅ 零 JavaScript 计算开销
+ * - ✅ 无渲染闪烁
+ * - ✅ 单行内容：容器宽度 = 内容宽度
+ * - ✅ 多行内容：容器宽度 = 95%（自动换行）
+ */
+
+export interface UseContentWidthOptions {
+  /** 容器最大宽度百分比 */
+  maxContainerWidthPercent?: number
+}
+
+export const useContentWidth = ({ maxContainerWidthPercent = 95 }: UseContentWidthOptions) => {
+  // 返回固定的 CSS 宽度策略
+  // width: max-content 让容器完全根据内容宽度扩展（不提前换行）
+  // max-width: 95% 限制最大宽度
+  // 当内容超过 max-width 时，容器会被限制，内容自然换行
+  const widthStyle = 'max-content'
+  const maxWidthStyle = `${maxContainerWidthPercent}%`
+
+  return {
+    widthStyle,
+    maxWidthStyle
+  }
+}