feat: add comments and cleanup unused imports across codebase

static/player/subtitles/index.ts

@@ -2,8 +2,10 @@ import { SubtitleCue, SubtitleTrack } from '../types';
 import { state } from '../state';
 import { parseVtt } from './vtt';
 
+// proxy subtitle URL through backend (avoids CORS)
 const proxyUrl = (token: string) => `/watch/proxy/subtitle?token=${encodeURIComponent(token)}`;
 
+// builds subtitle track list from current mode's source
 const subtitlesForMode = (): SubtitleTrack[] => {
   const src = state.modeSources[state.currentMode];
   if (!src?.subtitles) return [];
@@ -24,6 +26,7 @@ const hideSubtitleText = (): void => {
   el.classList.add('hidden');
 };
 
+// fetches and parses VTT from proxy URL
 const loadSubtitle = async (url: string): Promise<SubtitleCue[]> => {
   try {
     const res = await fetch(url);
@@ -34,6 +37,10 @@ const loadSubtitle = async (url: string): Promise<SubtitleCue[]> => {
   }
 };
 
+/**
+ * Rebuilds subtitle dropdown from current mode's available tracks.
+ * Shows/hides dropdown based on availability.
+ */
 export const updateSubtitleOptions = (): void => {
   const select = state.container.querySelector(
     '[data-subtitle-select]'
@@ -61,6 +68,10 @@ export const updateSubtitleOptions = (): void => {
   hideSubtitleText();
 };
 
+/**
+ * Updates subtitle text display based on current video time.
+ * Finds active cue and shows/hides overlay.
+ */
 export const updateSubtitleRender = (time: number): void => {
   const el = state.container.querySelector('[data-subtitle-text]') as HTMLElement | null;
   if (!el) return;
@@ -69,6 +80,7 @@ export const updateSubtitleRender = (time: number): void => {
     return;
   }
 
+  // find cue containing current time
   const cue = state.activeSubtitles.find(c => time >= c.start && time <= c.end);
   if (!cue) {
     hideSubtitleText();
@@ -79,6 +91,10 @@ export const updateSubtitleRender = (time: number): void => {
   el.classList.remove('hidden');
 };
 
+/**
+ * Binds subtitle select change handler.
+ * Loads and parses selected VTT track.
+ */
 export const setupSubtitles = (): void => {
   const select = state.container.querySelector(
     '[data-subtitle-select]'

static/player/subtitles/vtt.ts

@@ -1,3 +1,4 @@
+// parses VTT timestamp (mm:ss.ms or hh:mm:ss.ms) to seconds
 export const parseVttTime = (raw: string): number => {
   const parts = raw.trim().split(':');
   if (parts.length < 2) return 0;
@@ -7,15 +8,18 @@ export const parseVttTime = (raw: string): number => {
   return Number(hourPart) * 3600 + Number(minPart) * 60 + Number(secPart.replace(',', '.'));
 };
 
+// parses a single VTT cue: timestamp line + text lines
 export const parseVttCue = (line: string, lines: string[], i: number) => {
   if (!line.includes('-->')) return null;
   const [startRaw, endRaw] = line.split('-->');
   const payload: string[] = [];
   let j = i + 1;
+  // collect text until blank line
   while (j < lines.length && lines[j].trim() !== '') {
     payload.push(lines[j]);
     j++;
   }
+  // strip tags, join lines
   const text = payload
     .join('\n')
     .replace(/<[^>]+>/g, '')
@@ -24,17 +28,23 @@ export const parseVttCue = (line: string, lines: string[], i: number) => {
   return { start: parseVttTime(startRaw), end: parseVttTime(endRaw), text };
 };
 
+/**
+ * Parses full VTT file into cue array.
+ * Handles both compact (timestamp on separate line) and standard formats.
+ */
 export const parseVtt = (text: string) => {
   const lines = text.replace(/\r/g, '').split('\n');
   const cues = [];
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i].trim();
     if (!line) continue;
+    // compact: cue id on line i, timestamp on i+1
     if (i + 1 < lines.length && !line.includes('-->') && lines[i + 1].includes('-->')) {
       const cue = parseVttCue(lines[i + 1].trim(), lines, i + 1);
       if (cue) cues.push(cue);
       i++;
     } else if (line.includes('-->')) {
+      // standard: timestamp on same line
       const cue = parseVttCue(line, lines, i);
       if (cue) cues.push(cue);
     }