feat: add comments and cleanup unused imports across codebase

static/player/progress.ts

@@ -1,6 +1,7 @@
 import { state } from './state';
 import { displayTimeFromAbsolute } from './timeline';
 
+// builds JSON payload for progress API
 const buildPayload = (episode: number, seconds: number) =>
   JSON.stringify({
     mal_id: state.malID,
@@ -8,18 +9,24 @@ const buildPayload = (episode: number, seconds: number) =>
     time_seconds: seconds,
   });
 
+// sends progress via beacon (survives page unload)
 const sendBeacon = (payload: string) => {
   if (!navigator.sendBeacon) return false;
   navigator.sendBeacon('/api/watch-progress', new Blob([payload], { type: 'application/json' }));
   return true;
 };
 
+/**
+ * Saves current progress to backend.
+ * Debounced: skips if within 5s of last save for same episode.
+ */
 export const saveProgress = async (): Promise<void> => {
   if (!state.malID || state.video.currentTime < 1) return;
   const episode = Number.parseInt(state.currentEpisode, 10);
   if (!episode) return;
 
   const safeTime = displayTimeFromAbsolute(state.video.currentTime);
+  // skip if recently saved
   if (
     state.lastSavedProgress.episode === state.currentEpisode &&
     Math.abs(state.lastSavedProgress.seconds - safeTime) < 5
@@ -38,6 +45,7 @@ export const saveProgress = async (): Promise<void> => {
   } catch {}
 };
 
+// schedules periodic save every 30s during playback
 const scheduleProgressSave = (): void => {
   if (state.progressSaveTimer !== undefined) return;
   state.progressSaveTimer = window.setTimeout(() => {
@@ -46,6 +54,10 @@ const scheduleProgressSave = (): void => {
   }, 30000);
 };
 
+/**
+ * Records episode transition (clicked external link to next episode).
+ * Uses beacon for reliability on page unload.
+ */
 export const markEpisodeTransition = (episodeNumber: number): void => {
   if (!state.malID || !episodeNumber) return;
   if (state.progressSaveTimer !== undefined) {
@@ -54,6 +66,7 @@ export const markEpisodeTransition = (episodeNumber: number): void => {
   }
   state.transitionEpisode = episodeNumber;
   const payload = buildPayload(episodeNumber, 0);
+  // beacon falls back to fetch with keepalive
   if (!sendBeacon(payload)) {
     fetch('/api/watch-progress', {
       method: 'POST',
@@ -64,22 +77,29 @@ export const markEpisodeTransition = (episodeNumber: number): void => {
   }
 };
 
+/**
+ * Sets up progress save on timeupdate, pause, mouseup (scrub end), and beforeunload.
+ */
 export const setupProgress = (): void => {
+  // periodic save during playback
   state.video.addEventListener('timeupdate', () => {
     scheduleProgressSave();
   });
 
+  // immediate save on pause
   state.video.addEventListener('pause', () => {
     window.clearTimeout(state.progressSaveTimer);
     state.progressSaveTimer = undefined;
     saveProgress();
   });
 
+  // save after scrubbing
   window.addEventListener('mouseup', () => {
     state.isScrubbing = false;
     saveProgress();
   });
 
+  // save on page close
   window.addEventListener('beforeunload', () => {
     if (state.transitionEpisode !== null || state.completionSent || !state.malID) return;
     const episode = Number.parseInt(state.currentEpisode, 10);