feat: add comments and cleanup unused imports across codebase

2026-05-10 20:00:04 +02:00
parent b152e246ff
commit e48d95cb4e
68 changed files with 560 additions and 88 deletions
--- a/static/player/controls.ts
+++ b/static/player/controls.ts
@@ -7,6 +7,9 @@ export const formatTime = (seconds: number): string => {
  return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
 };

+/**
+ * Shows the controls overlay and schedules auto-hide after 2s if playing.
+ */
 export const showControls = (): void => {
  state.container.classList.add('show-controls');
  window.clearTimeout(state.playerControlsTimeout);
@@ -17,6 +20,7 @@ export const showControls = (): void => {
  }, 2000);
 };

+// seek relative to current position
 export const seekBy = (delta: number): void => {
  if (state.video.duration <= 0) return;
  state.video.currentTime = Math.max(
@@ -34,6 +38,7 @@ export const togglePlayPause = (): void => {
  }
 };

+// toggle mute, restoring previous volume
 export const toggleMute = (): void => {
  if (state.video.muted || state.video.volume === 0) {
    const restored = state.lastKnownVolume > 0 ? state.lastKnownVolume : 1;
@@ -45,6 +50,7 @@ export const toggleMute = (): void => {
  }
 };

+// set volume (0-1), auto-unmute
 export const setVolume = (value: number): void => {
  state.video.volume = Math.max(0, Math.min(1, value));
  state.video.muted = value === 0;
@@ -59,8 +65,9 @@ export const toggleFullscreen = (): void => {
  state.container.requestFullscreen?.();
 };

+// syncs volume slider, underline, and mute icon
 export const syncVolumeUI = (): void => {
-  const { volumeRange, volumeUnderline, iconVolume, iconMuted } = getControls();
+  const { volumeRange, volumeUnderline } = getControls();
  const value = state.video.muted ? 0 : Math.round(state.video.volume * 100);
  if (volumeRange) {
    volumeRange.value = String(value);
@@ -125,6 +132,10 @@ const updateMuteIcons = (isMuted: boolean): void => {
  iconMuted?.classList.toggle('hidden', !isMuted);
 };

+/**
+ * Binds click handlers to player control buttons.
+ * Sets up video event listeners for icon sync.
+ */
 export const setupControls = (): void => {
  const {
    playPause,
@@ -137,6 +148,7 @@ export const setupControls = (): void => {
    skipSegmentBtn,
  } = getControls();

+  // play/pause on button and video click
  playPause?.addEventListener('click', () => {
    togglePlayPause();
    showControls();
@@ -151,11 +163,13 @@ export const setupControls = (): void => {
    showControls();
  });

+  // volume slider
  volumeRange?.addEventListener('input', () => {
    const value = Number(volumeRange.value) / 100;
    setVolume(value);
    showControls();
  });
+  // dragging class for visual feedback
  volumeRange?.addEventListener('pointerdown', () => volumePanel?.classList.add('is-dragging'));
  window.addEventListener('pointerup', () => volumePanel?.classList.remove('is-dragging'));

@@ -167,18 +181,21 @@ export const setupControls = (): void => {
    showControls();
  });

+  // skip intro/outro button
  skipSegmentBtn?.addEventListener('click', () => {
    if (!state.activeSkipSegment) return;
    state.video.currentTime = state.activeSkipSegment.end + 0.01;
    showControls();
  });

+  // fullscreen change handler
  document.addEventListener('fullscreenchange', () => {
    state.isFullscreen = !!document.fullscreenElement;
    state.container.classList.toggle('fullscreen', state.isFullscreen);
    if (state.isFullscreen) showControls();
  });

+  // icon sync on state changes
  state.video.addEventListener('play', () => {
    updatePlayPauseIcons(true);
    showControls();
@@ -189,8 +206,10 @@ export const setupControls = (): void => {
  });
  state.video.addEventListener('volumechange', syncVolumeUI);

+  // mouse move in container shows controls
  state.container.addEventListener('mousemove', showControls);

+  // initial sync
  updatePlayPauseIcons(false);
  syncVolumeUI();
 };
--- a/static/player/episodes/complete.ts
+++ b/static/player/episodes/complete.ts
@@ -1,6 +1,11 @@
 import DOMPurify from 'dompurify';
 import { state } from '../state';

+/**
+ * Marks anime as completed when final episode finishes.
+ * Calls completion API, updates dropdown UI, adds to watchlist.
+ * Retries up to 2 times on failure.
+ */
 export const completeAnime = async (episodeNumber: number): Promise<void> => {
  if (state.completionSent || !state.malID || !episodeNumber) return;
  state.completionSent = true;
@@ -15,6 +20,7 @@ export const completeAnime = async (episodeNumber: number): Promise<void> => {

    if (!res.ok) {
      state.completionSent = false;
+      // retry
      if (state.completionAttempts < 2) {
        state.completionAttempts++;
        setTimeout(() => completeAnime(episodeNumber), 1000);
@@ -22,6 +28,7 @@ export const completeAnime = async (episodeNumber: number): Promise<void> => {
      return;
    }

+    // update dropdown trigger text
    const trigger = document.querySelector('[data-dropdown-trigger]') as HTMLButtonElement | null;
    if (trigger) {
      trigger.textContent = 'Completed ';
@@ -31,6 +38,7 @@ export const completeAnime = async (episodeNumber: number): Promise<void> => {
      trigger.appendChild(caret);
    }

+    // add to watchlist with 'completed' status
    const dropdown = document.getElementById('watch-status-dropdown');
    if (dropdown) {
      const payload = {
@@ -51,6 +59,7 @@ export const completeAnime = async (episodeNumber: number): Promise<void> => {
      })
        .then(async res => {
          if (!res.ok) return;
+          // replace dropdown with HTMX response
          const html = await res.text();
          const wrapper = document.createElement('span');
          wrapper.id = 'watch-status-dropdown';
--- a/static/player/episodes/nav.ts
+++ b/static/player/episodes/nav.ts
@@ -1,22 +1,27 @@
 import { state } from '../state';
 import { SkipSegment } from '../types';
-import { displayTimeFromAbsolute } from '../timeline';
 import { resolveActiveSegments, renderSegments } from '../skip/segments';
 import { updateSubtitleOptions } from '../subtitles';
 import { updateQualityOptions } from '../quality';
 import { updateModeButtons } from '../mode';
-import { updateOverlay, isAutoplayEnabled, updateEpisodeHighlight, switchEpisodeRange } from './ui';
+import { updateOverlay, isAutoplayEnabled, switchEpisodeRange } from './ui';
 import { markEpisodeTransition } from '../progress';

+/**
+ * Handles video end: either marks complete or loads next episode.
+ * Fetches episode data from API, updates player state and URL.
+ */
 export const goToNextEpisode = async (): Promise<void> => {
  const currentEp = Number.parseInt(state.currentEpisode, 10);
  if (!currentEp) return;

+  // final episode: trigger completion flow
  if (state.totalEpisodes > 0 && currentEp >= state.totalEpisodes) {
    import('./complete').then(m => m.completeAnime(currentEp));
    return;
  }

+  // skip if autoplay disabled
  if (!isAutoplayEnabled()) return;

  const nextEp = currentEp + 1;
@@ -25,6 +30,7 @@ export const goToNextEpisode = async (): Promise<void> => {
  try {
    const res = await fetch(`/api/watch/episode/${state.malID}/${nextEp}`);
    if (!res.ok) {
+      // fallback: full page navigation
      sessionStorage.setItem('mal:autoplay-next', 'true');
      const url = new URL(window.location.href);
      url.searchParams.set('ep', String(nextEp));
@@ -34,6 +40,7 @@ export const goToNextEpisode = async (): Promise<void> => {

    const data = await res.json();

+    // update state with new episode data
    state.modeSources = data.mode_sources ?? {};
    state.availableModes = data.available_modes ?? [];

@@ -46,6 +53,7 @@ export const goToNextEpisode = async (): Promise<void> => {
      return;
    }

+    // load new video
    state.video.src = `${state.streamURL}?mode=${encodeURIComponent(fallback)}&token=${encodeURIComponent(state.modeSources[fallback].token)}`;
    state.video.load();
    if (!state.video.paused) state.video.play().catch(() => {});
@@ -56,11 +64,13 @@ export const goToNextEpisode = async (): Promise<void> => {
    state.completionAttempts = 0;
    state.activeSubtitles = [];

+    // update UI
    updateSubtitleOptions();
    updateQualityOptions();
    updateModeButtons();
    updateOverlay(state.currentEpisode, data.episode_title ?? '');

+    // update skip segments
    if (data.segments?.length) {
      state.parsedSegments = data.segments
        .map((s: SkipSegment) => ({ ...s, start: Number(s.start) || 0, end: Number(s.end) || 0 }))
@@ -69,6 +79,7 @@ export const goToNextEpisode = async (): Promise<void> => {
      renderSegments();
    }

+    // highlight new episode in list/grid
    state.episodeList
      ?.querySelectorAll('[data-episode-id]')
      .forEach(el => el.classList.remove('bg-accent/20'));
@@ -84,6 +95,7 @@ export const goToNextEpisode = async (): Promise<void> => {
      newGridEl?.classList.add('bg-accent/20', 'ring-2', 'ring-accent', 'text-accent');
    }

+    // update URL without reload
    const url = new URL(window.location.href);
    url.searchParams.set('ep', String(nextEp));
    history.pushState(null, '', url.toString());
--- a/static/player/episodes/ui.ts
+++ b/static/player/episodes/ui.ts
@@ -1,8 +1,9 @@
 import { state } from '../state';
-import { updateSubtitleOptions } from '../subtitles';
-import { updateQualityOptions } from '../quality';
-import { updateModeButtons } from '../mode';

+/**
+ * Syncs autoplay checkbox with localStorage on init.
+ * Default is enabled (not 'false').
+ */
 export const setupAutoplayButton = (): void => {
  const btn = document.querySelector('[data-autoplay]') as HTMLInputElement | null;
  if (!btn) return;
@@ -12,12 +13,16 @@ export const setupAutoplayButton = (): void => {
 export const isAutoplayEnabled = (): boolean =>
  localStorage.getItem('mal:autoplay-enabled') !== 'false';

+/**
+ * Updates video overlay text (shown briefly on episode change).
+ */
 export const updateOverlay = (episode: string, title: string): void => {
  if (!state.videoOverlay) return;
  const p = state.videoOverlay.querySelector('p');
  p && (p.textContent = title ? `Episode ${episode}, ${title}` : `Episode ${episode}`);
 };

+// helper: get all episode elements from grid and list
 const getEpisodeEls = () => {
  const grid = state.episodeGrid;
  const list = state.episodeList;
@@ -27,19 +32,30 @@ const getEpisodeEls = () => {
  };
 };

+/**
+ * Highlights current episode in grid and list.
+ * Scrolls to episode into view.
+ */
 export const updateEpisodeHighlight = (num: number): void => {
  const { gridEls, listEls } = getEpisodeEls();
+  // clear old highlights
  [...gridEls, ...listEls].forEach(el =>
    el.classList.remove('ring-2', 'ring-accent', 'bg-accent/20', 'text-accent')
  );

+  // apply new highlight
  const gridEl = state.episodeGrid?.querySelector(`[data-episode-id="${num}"]`);
  const listEl = state.episodeList?.querySelector(`[data-episode-id="${num}"]`);
  gridEl?.classList.add('ring-2', 'ring-accent');
  listEl?.classList.add('ring-2', 'ring-accent');
+  // scroll into view
  (gridEl ?? listEl)?.scrollIntoView({ behavior: 'smooth', block: 'center' });
 };

+/**
+ * Switches visible episode range in grid.
+ * Updates dropdown label and hides/shows episode cards.
+ */
 export const switchEpisodeRange = (idx: number): void => {
  const dropdown = state.container.querySelector('[data-episode-dropdown]') as HTMLElement | null;
  if (!dropdown) return;
@@ -50,10 +66,12 @@ export const switchEpisodeRange = (idx: number): void => {
  const start = Number.parseInt(target.dataset.rangeStart ?? '1', 10);
  const end = Number.parseInt(target.dataset.rangeEnd ?? '100', 10);

+  // update label (e.g., "01-100")
  const label = dropdown.querySelector('[data-dropdown-label]') as HTMLElement | null;
  if (label)
    label.textContent = `${String(start).padStart(2, '0')}-${String(end).padStart(2, '0')}`;

+  // show/hide episodes in range
  state.episodeGrid?.querySelectorAll('[data-episode-id]').forEach(el => {
    const n = Number.parseInt((el as HTMLElement).dataset.episodeId ?? '0', 10);
    el.classList.toggle('hidden', n < start || n > end);
--- a/static/player/keyboard.ts
+++ b/static/player/keyboard.ts
@@ -1,10 +1,5 @@
 import { state } from './state';
-import {
-  displayTimeFromAbsolute,
-  absoluteTimeFromDisplay,
-  absoluteTimeFromRatio,
-  getBounds,
-} from './timeline';
+import { absoluteTimeFromRatio, getBounds } from './timeline';
 import {
  showControls,
  toggleMute,
@@ -12,12 +7,16 @@ import {
  toggleFullscreen,
  seekBy,
  setVolume,
-  formatTime,
 } from './controls';

+/**
+ * Sets up keyboard shortcuts for player control.
+ * Ignores input/textarea to allow typing.
+ */
 export const setupKeyboard = (): void => {
  document.addEventListener('keydown', e => {
    const target = e.target as HTMLElement;
+    // ignore when typing in form fields
    if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable)
      return;

@@ -59,6 +58,7 @@ export const setupKeyboard = (): void => {
        showControls();
        break;
      default:
+        // number keys 0-9: jump to 0%-90% of video
        if (/^\d$/.test(e.key)) {
          const b = getBounds();
          if (b.duration > 0) {
--- a/static/player/main.ts
+++ b/static/player/main.ts
@@ -14,7 +14,7 @@ import { markEpisodeTransition, setupProgress } from './progress';
 import { absoluteTimeFromRatio, getBounds, displayTimeFromAbsolute } from './timeline';
 import { formatTime } from './controls';

-let initialized = false;
+let initialized = false; // prevent double init on htmx swaps

 const hidePreviewPopover = (): void => {
  state.previewPopover?.classList.remove('block');
@@ -27,6 +27,7 @@ const showPreviewPopover = (): void => {
  state.previewPopover?.classList.add('block');
 };

+// updates time preview on progress bar hover
 const updatePreviewUI = (ratio: number): void => {
  const progressWrap = state.container.querySelector('[data-progress-wrap]') as HTMLElement | null;
  if (!progressWrap || !state.previewPopover || !state.previewTime) {
@@ -39,6 +40,7 @@ const updatePreviewUI = (ratio: number): void => {
    return;
  }

+  // show time for hovered position
  state.previewTime.textContent = formatTime(Math.max(0, Math.min(b.duration, ratio * b.duration)));

  const barWidth = progressWrap.clientWidth;
@@ -48,6 +50,7 @@ const updatePreviewUI = (ratio: number): void => {
  }

  showPreviewPopover();
+  // clamp to stay within bar bounds
  const popoverWidth = state.previewPopover.offsetWidth || 72;
  state.previewPopover.style.left = `${Math.max(popoverWidth / 2, Math.min(barWidth - popoverWidth / 2, ratio * barWidth))}px`;
 };
@@ -62,6 +65,7 @@ const initPlayer = (): void => {
  const loading = container.querySelector('[data-loading]') as HTMLElement | null;
  const progressWrap = container.querySelector('[data-progress-wrap]') as HTMLElement | null;

+  // build video src from mode, token, and saved quality preference
  const preferredQuality = localStorage.getItem('mal:preferred-quality') || 'best';
  const streamToken = state.modeSources[state.currentMode]?.token;
  if (streamToken) {
@@ -90,10 +94,12 @@ const initPlayer = (): void => {
    resolveActiveSegments();
    renderSegments();

+    // resume from saved position
    const startTime = Number(container.dataset.startTimeSeconds ?? '0');
    if (startTime > 0 && state.video.currentTime <= 0.5 && state.video.duration > startTime) {
      state.video.currentTime = startTime;
    }
+    // resume after mode switch
    if (state.pendingSeekTime !== null) {
      state.video.currentTime = state.pendingSeekTime;
      state.pendingSeekTime = null;
@@ -110,10 +116,12 @@ const initPlayer = (): void => {
  state.video.addEventListener('playing', () => {
    loading && (loading.style.display = 'none');
  });
+  // update progress bar during buffering
  state.video.addEventListener('progress', () => {
    updateTimeline(state.video.currentTime);
  });

+  // main loop: update progress, subtitles, skip buttons
  state.video.addEventListener('timeupdate', () => {
    updateTimeline(state.video.currentTime);
    updateSubtitleRender(displayTimeFromAbsolute(state.video.currentTime));
@@ -124,6 +132,7 @@ const initPlayer = (): void => {
    goToNextEpisode();
  });

+  // click to seek
  progressWrap?.addEventListener('mousedown', e => {
    state.isScrubbing = true;
    const rect = progressWrap.getBoundingClientRect();
@@ -135,6 +144,7 @@ const initPlayer = (): void => {
    showControls();
  });

+  // hover to preview time
  progressWrap?.addEventListener('mousemove', e => {
    const rect = progressWrap.getBoundingClientRect();
    updatePreviewUI(Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width)));
@@ -142,6 +152,7 @@ const initPlayer = (): void => {

  progressWrap?.addEventListener('mouseleave', hidePreviewPopover);

+  // dragging outside progress bar while scrubbing
  window.addEventListener('mousemove', e => {
    if (!state.isScrubbing || !progressWrap) return;
    const rect = progressWrap.getBoundingClientRect();
@@ -152,6 +163,7 @@ const initPlayer = (): void => {
    updateSkipButton(state.video.currentTime);
  });

+  // track episode transitions from external links
  container.addEventListener('click', e => {
    const anchor = (e.target as Node).parentElement?.closest('a[href]');
    if (!(anchor instanceof HTMLAnchorElement)) return;
@@ -170,9 +182,11 @@ const initPlayer = (): void => {
  if (searchInput) {
    searchInput.addEventListener('input', () => {
      clearTimeout(searchDebounce);
+      // debounce to avoid excessive range switches while typing
      searchDebounce = window.setTimeout(() => {
        const val = searchInput.value.replace(/\D/g, '');
        if (!val) {
+          // clear: jump to current episode range
          const cur = Number.parseInt(state.currentEpisode, 10);
          switchEpisodeRange(Math.floor((cur - 1) / 100));
          updateEpisodeHighlight(cur);
@@ -191,6 +205,7 @@ const initPlayer = (): void => {
    });
  }

+  // range buttons (100s of episodes)
  if (dropdown) {
    dropdown.querySelectorAll('.episode-range-btn').forEach(btn => {
      btn.addEventListener('click', () => {
@@ -200,6 +215,7 @@ const initPlayer = (): void => {
    });
  }

+  // initial range for large episode lists
  if (state.episodeGrid && state.totalEpisodes > 100) {
    switchEpisodeRange(Math.floor((Number.parseInt(state.currentEpisode, 10) - 1) / 100));
  }
--- a/static/player/mode.ts
+++ b/static/player/mode.ts
@@ -1,10 +1,10 @@
 import { state } from './state';
-import { displayTimeFromAbsolute, absoluteTimeFromDisplay } from './timeline';
+import { displayTimeFromAbsolute } from './timeline';
 import { showControls } from './controls';
 import { updateSubtitleOptions } from './subtitles';
 import { updateQualityOptions } from './quality';
-import { ModeSource } from './types';

+// builds stream URL with mode, token, and optional quality param
 const streamUrlForMode = (mode: string, quality?: string): string => {
  const src = state.modeSources[mode];
  if (!src?.token) return '';
@@ -13,16 +13,21 @@ const streamUrlForMode = (mode: string, quality?: string): string => {
  return url;
 };

+// switches video src while preserving playback position
 const loadVideo = (url: string): void => {
  if (!url) return;
  const wasPlaying = !state.video.paused;
  const prevTime = displayTimeFromAbsolute(state.video.currentTime);
  state.video.src = url;
  state.video.load();
-  state.pendingSeekTime = prevTime;
+  state.pendingSeekTime = prevTime; // restored in loadedmetadata handler
  if (wasPlaying) state.video.play().catch(() => {});
 };

+/**
+ * Switches between sub/dub mode.
+ * Saves preference to localStorage, reloads video src.
+ */
 export const switchMode = (mode: string): void => {
  if (!state.availableModes.includes(mode) || mode === state.currentMode) return;
  state.currentMode = mode;
@@ -33,6 +38,10 @@ export const switchMode = (mode: string): void => {
  updateModeButtons();
 };

+/**
+ * Updates dub/sub button styling based on current mode.
+ * Disables unavailable modes.
+ */
 export const updateModeButtons = (): void => {
  const dub = state.container.querySelector('[data-mode-dub]') as HTMLButtonElement | null;
  const sub = state.container.querySelector('[data-mode-sub]') as HTMLButtonElement | null;
@@ -51,6 +60,9 @@ export const updateModeButtons = (): void => {
  sub && (sub.disabled = !state.availableModes.includes('sub'));
 };

+/**
+ * Binds click handlers for mode buttons and autoplay toggle.
+ */
 export const setupMode = (): void => {
  const dub = state.container.querySelector('[data-mode-dub]') as HTMLButtonElement | null;
  const sub = state.container.querySelector('[data-mode-sub]') as HTMLButtonElement | null;
--- a/static/player/progress.ts
+++ b/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);
--- a/static/player/quality.ts
+++ b/static/player/quality.ts
@@ -1,6 +1,7 @@
 import { state } from './state';
-import { displayTimeFromAbsolute, absoluteTimeFromDisplay } from './timeline';
+import { displayTimeFromAbsolute } from './timeline';

+// same as mode.ts - could be extracted to shared util
 const streamUrlForMode = (mode: string, quality?: string): string => {
  const src = state.modeSources[mode];
  if (!src?.token) return '';
@@ -19,6 +20,10 @@ const loadVideo = (url: string): void => {
  if (wasPlaying) state.video.play().catch(() => {});
 };

+/**
+ * Switches video quality (resolution).
+ * Persists preference to localStorage.
+ */
 export const switchQuality = (quality: string): void => {
  const url = streamUrlForMode(state.currentMode, quality);
  if (!url) return;
@@ -26,6 +31,10 @@ export const switchQuality = (quality: string): void => {
  loadVideo(url);
 };

+/**
+ * Rebuilds quality dropdown options from current mode's available qualities.
+ * Shows/hides dropdown based on availability.
+ */
 export const updateQualityOptions = (): void => {
  const select = state.container.querySelector('[data-quality-select]') as HTMLSelectElement | null;
  if (!select) return;
@@ -44,13 +53,18 @@ export const updateQualityOptions = (): void => {
    select.appendChild(opt);
  });

+  // restore saved preference
  const preferred = localStorage.getItem('mal:preferred-quality') || 'best';
  select.value = qualities.includes(preferred) ? preferred : 'best';

+  // hide if no quality options
  const wrapper = select.parentElement;
  wrapper?.classList.toggle('hidden', qualities.length === 0);
 };

+/**
+ * Binds quality select change handler.
+ */
 export const setupQuality = (): void => {
  const select = state.container.querySelector('[data-quality-select]') as HTMLSelectElement | null;
  select?.addEventListener('change', e => {
--- a/static/player/state.ts
+++ b/static/player/state.ts
@@ -79,7 +79,12 @@ export const state: PlayerState = {
  videoOverlay: null,
 };

+/**
+ * Initializes player state from DOM data attributes.
+ * Called once on page load or htmx swap.
+ */
 export const initState = (c: HTMLElement): void => {
+  // core elements
  state.container = c;
  state.video = q<HTMLVideoElement>(c, 'video')!;
  state.progress = q<HTMLElement>(c, '[data-progress]');
@@ -91,14 +96,17 @@ export const initState = (c: HTMLElement): void => {
  state.previewTime = q<HTMLElement>(c, '[data-preview-time]');
  state.videoOverlay = q<HTMLElement>(c, '[data-video-overlay]');

+  // data attributes from server
  state.malID = Number.parseInt(dataset(c, 'malId'), 10);
  state.currentEpisode = dataset(c, 'currentEpisode') || '1';
  state.totalEpisodes = Number.parseInt(dataset(c, 'totalEpisodes'), 10);
  state.streamURL = dataset(c, 'streamUrl') || '/watch/proxy/stream';
  state.initialStreamToken = dataset(c, 'streamToken') || '';
+  // from session: previous page set this when autoplay triggered
  state.shouldAutoPlay = sessionStorage.getItem('mal:autoplay-next') === 'true';
  sessionStorage.removeItem('mal:autoplay-next');

+  // global elements (not inside player container)
  state.episodeGrid = qs<HTMLElement>('[data-episode-grid]');
  state.episodeList = qs<HTMLElement>('[data-episode-list]');

@@ -110,9 +118,11 @@ export const initState = (c: HTMLElement): void => {
    }
  };

+  // mode sources = { sub: { token, subtitles, qualities }, dub: { ... } }
  state.modeSources = safeJson(dataset(c, 'modeSources'), {} as Record<string, ModeSource>);
  state.availableModes = safeJson(dataset(c, 'availableModes'), [] as string[]);

+  // resolve initial mode: localStorage > backend default > first available > 'dub'
  const backendInitialMode = dataset(c, 'initialMode') || 'dub';
  const storedMode = localStorage.getItem('player-audio-mode');
  const initialMode =
@@ -122,6 +132,7 @@ export const initState = (c: HTMLElement): void => {
    ? initialMode
    : (fallbackMode ?? state.availableModes[0] ?? 'dub');

+  // parse skip segments from data attribute
  const segments = safeJson(dataset(c, 'segments'), [] as SkipSegment[]);
  state.parsedSegments = segments
    .map(s => ({ ...s, start: Number(s.start) || 0, end: Number(s.end) || 0 }))
--- a/static/player/subtitles/index.ts
+++ b/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]'
--- a/static/player/subtitles/vtt.ts
+++ b/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);
    }
--- a/static/player/timeline.ts
+++ b/static/player/timeline.ts
@@ -1,6 +1,7 @@
 import { TimelineBounds } from './types';
 import { state } from './state';

+// mm:ss formatter
 const formatTime = (seconds: number): string => {
  if (!Number.isFinite(seconds) || seconds < 0) return '00:00';
  const mins = Math.floor(seconds / 60);
@@ -8,12 +9,18 @@ const formatTime = (seconds: number): string => {
  return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
 };

+// cached to avoid recalc on every timeupdate
 let cachedBounds: TimelineBounds = { start: 0, end: 0, duration: 0 };

+/**
+ * Computes timeline bounds from video.
+ * Handles seekable ranges (live streams) and regular duration.
+ */
 export const timelineBounds = (): TimelineBounds => {
  const duration =
    Number.isFinite(state.video.duration) && state.video.duration > 0 ? state.video.duration : 0;
  let start = 0;
+  // check seekable range for live streams
  if (state.video.seekable.length > 0) {
    const seekableStart = state.video.seekable.start(0);
    if (Number.isFinite(seekableStart) && seekableStart > 0) start = seekableStart;
@@ -21,6 +28,7 @@ export const timelineBounds = (): TimelineBounds => {
  if (duration > start) {
    return { start, end: duration, duration: duration - start };
  }
+  // fallback to full seekable range
  if (state.video.seekable.length > 0) {
    const seekableEnd = state.video.seekable.end(state.video.seekable.length - 1);
    if (Number.isFinite(seekableEnd) && seekableEnd > start) {
@@ -36,27 +44,32 @@ export const invalidateBounds = (): void => {

 export const getBounds = (): TimelineBounds => cachedBounds;

+// converts video.currentTime to timeline-relative time (0-based for UI display)
 export const displayTimeFromAbsolute = (absoluteTime: number): number => {
  const b = getBounds();
  if (!Number.isFinite(absoluteTime) || b.duration <= 0) return 0;
  return Math.max(b.start, Math.min(b.end, absoluteTime)) - b.start;
 };

+// converts timeline-relative time back to video time
 export const absoluteTimeFromDisplay = (displayTime: number): number => {
  const b = getBounds();
  if (!Number.isFinite(displayTime) || b.duration <= 0) return 0;
  return b.start + Math.max(0, Math.min(b.duration, displayTime));
 };

+// converts 0-1 ratio to absolute video time
 export const absoluteTimeFromRatio = (ratio: number): number => {
  const b = getBounds();
  if (!Number.isFinite(ratio) || b.duration <= 0) return 0;
  return b.start + Math.max(0, Math.min(1, ratio)) * b.duration;
 };

+// finds the end of the buffered region containing currentTime
 export const getBufferedEnd = (): number => {
  const currentTime = state.video.currentTime;
  let end = 0;
+  // first: find buffered range that contains current time
  for (let i = 0; i < state.video.buffered.length; i++) {
    if (
      state.video.buffered.start(i) <= currentTime &&
@@ -66,6 +79,7 @@ export const getBufferedEnd = (): number => {
      break;
    }
  }
+  // fallback: next buffered range after current time
  if (end === 0) {
    for (let i = 0; i < state.video.buffered.length; i++) {
      if (state.video.buffered.end(i) > currentTime) {
@@ -76,6 +90,10 @@ export const getBufferedEnd = (): number => {
  return end;
 };

+/**
+ * Updates progress bar, scrubber position, and time displays.
+ * Called on timeupdate, progress events, and seek.
+ */
 export const updateTimeline = (currentTime: number): void => {
  const { progress, scrubber, timeDisplay, durationDisplay, buffered } = state;
  const b = getBounds();
@@ -95,6 +113,7 @@ export const updateTimeline = (currentTime: number): void => {
  timeDisplay.textContent = formatTime(displayTimeFromAbsolute(currentTime));
  durationDisplay.textContent = formatTime(b.duration);

+  // buffered region
  const bufferedEnd = getBufferedEnd();
  const bufferedPct = (displayTimeFromAbsolute(bufferedEnd) / b.duration) * 100;
  buffered.style.width = `${bufferedPct}%`;
--- a/static/player/types.ts
+++ b/static/player/types.ts
@@ -1,38 +1,45 @@
+// stream source for a single mode (sub/dub)
 export interface ModeSource {
  token: string;
  subtitles: SubtitleItem[];
  qualities?: string[];
 }

+// subtitle track from backend
 export interface SubtitleItem {
  lang: string;
  token: string;
 }

+// skip segment (intro/outro) from backend data attribute
 export interface SkipSegment {
-  type: string;
+  type: string; // 'op' or 'ed'
  start: number;
  end: number;
 }

+// parsed subtitle cue from VTT
 export interface SubtitleCue {
  start: number;
  end: number;
  text: string;
 }

+// loaded subtitle track for UI
 export interface SubtitleTrack {
  lang: string;
  label: string;
  url: string;
 }

+// validated skip segment within video bounds
 export interface ActiveSegment {
  type: string;
  start: number;
  end: number;
 }

+// timeline range (handles seekable ranges in live streams)
 export interface TimelineBounds {
  start: number;
  end: number;