📝 Add docstrings to feat/import-subtitle-from-stream

src/main/ipc.ts

@@ -45,16 +45,15 @@ const mediaParserService = new MediaParserService()
 const subtitleExtractorService = new SubtitleExtractorService()
 
 /**
- * Register all IPC handlers used by the main process.
+ * Registers all ipcMain handlers used by the main process.
  *
- * Initializes updater and notification services and wires a comprehensive set of ipcMain.handle
- * handlers exposing application control, system info, theming/language, spell-check, cache and
- * file operations, dictionary lookups, FFmpeg operations, shortcut management, and database DAOs
- * (Files, VideoLibrary, SubtitleLibrary) to renderer processes.
+ * Exposes application control, system information, theming/language, spell-check, cache and file
+ * operations, media tooling (FFmpeg, media parser, subtitle extraction), shortcuts, and database
+ * DAOs to renderer processes via ipcMain handlers.
  *
- * This function has side effects: it registers handlers on ipcMain, may attach an app 'before-quit'
- * listener when requested, and mutates Electron state (e.g., app paths, sessions). Call from the
- * Electron main process once (typically during app initialization).
+ * This function mutates Electron state (registers handlers on ipcMain, may add/remove an app
+ * 'before-quit' listener, and updates sessions/paths) and must be invoked once from the main
+ * process during application initialization.
  */
 export function registerIpc(mainWindow: BrowserWindow, app: Electron.App) {
   const appUpdater = new AppUpdater(mainWindow)
@@ -1132,4 +1131,4 @@ export function registerIpc(mainWindow: BrowserWindow, app: Electron.App) {
   //     throw error
   //   }
   // })
-}
+}

src/renderer/src/pages/player/PlayerPage.tsx

@@ -65,23 +65,15 @@ interface VideoData {
 }
 
 /**
- * Player page component that loads a video by ID from the route and renders the video player UI.
+ * Render the player page for the video identified by the current route and manage its loading,
+ * transcoding session, subtitle detection, and related UI state.
  *
- * This component:
- * - Reads the `id` route parameter and loads the corresponding video record and file from the database.
- * - Constructs a file:// URL as the video source, stores per-page VideoData in local state and synchronizes it to the global per-video session store.
- * - Renders a top navbar with a back button and title, a two-pane Splitter layout with the video surface and controls on the left and a subtitle list on the right, and a settings popover.
- * - Shows a centered loading view while fetching data and an error view with a back button if loading fails or the video is missing.
- * - Cleans up the per-video session state on unmount.
+ * Loads the video record and associated file, determines an appropriate playback source (original
+ * file or HLS from a transcoding session), synchronizes per-video state with global stores,
+ * detects embedded subtitle streams from the original file, and performs cleanup (including
+ * deleting any created transcoding session) when the component unmounts.
  *
- * Side effects:
- * - Performs async data fetches from the VideoLibraryService and the app database.
- * - Updates a global player session store with the loaded VideoData and clears it when the component unmounts.
- *
- * Error handling:
- * - Loading or playback errors set local error state and cause the component to render the error view.
- *
- * Note: This is a React component (returns JSX) and does not accept props; it derives the target video ID from route params.
+ * @returns The React element for the player page for the requested video
  */
 function PlayerPage() {
   const navigate = useNavigate()
@@ -976,4 +968,4 @@ const ProgressBarArea = styled.div`
 
 const BottomBar = styled.div`
   flex: 0 0 auto;
-`
+`

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

@@ -44,6 +44,18 @@ type SubtitleSearchResult = {
   index: number
 }
 
+/**
+ * Render the subtitle list panel with search, virtualized list, and empty-state actions.
+ *
+ * Renders either an empty-state view with import/embedded/AI options and legacy actions when no subtitles are available,
+ * or a searchable, virtualized list of subtitles with time formatting, range-based scrolling state management, and item selection.
+ *
+ * @param emptyDescription - Optional custom description to display in the empty-state header.
+ * @param emptyActions - Optional list of custom action buttons to show in the empty-state legacy actions row.
+ * @param hasEmbeddedSubtitles - When true, show the embedded-subtitle option card in the empty state.
+ * @param onOpenEmbeddedSubtitleSelector - Callback invoked when the embedded-subtitle option's "select" button is clicked.
+ * @returns The subtitle list panel element.
+ */
 function SubtitleListPanel({
   emptyDescription,
   emptyActions,
@@ -823,4 +835,4 @@ const SearchResultsHeader = styled.div`
   border-bottom: 1px solid var(--color-border-soft, rgba(255, 255, 255, 0.04));
   flex-shrink: 0;
   letter-spacing: 0.2px;
-`
+`