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/anime.ts
+++ b/static/anime.ts
@@ -1,6 +1,7 @@
 import { parseClassList } from './utils';

 const setDropdownMenuState = (menu: HTMLElement, isOpen: boolean): void => {
+  // data attributes store the class lists to add/remove
  const openClasses = parseClassList(menu.getAttribute('data-dropdown-open-classes'));
  const closedClasses = parseClassList(menu.getAttribute('data-dropdown-closed-classes'));

--- a/static/dedupe.ts
+++ b/static/dedupe.ts
@@ -8,18 +8,19 @@ const dedupe = (): void => {
      return;
    }
    if (seen.has(id)) {
-      item.remove();
+      item.remove(); // duplicate, remove it
    } else {
      seen.add(id);
    }
  });
 };

+// run on DOM ready or immediately if already loaded
 if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', dedupe);
 } else {
  dedupe();
 }

-window.addEventListener('load', dedupe);
+// also run on load as a fallback (e.g. htmx swaps)
 window.addEventListener('load', dedupe);
--- a/static/discover.ts
+++ b/static/discover.ts
@@ -6,6 +6,7 @@ const setActiveDiscoverTab = (clickedTab: Element): void => {
    return;
  }

+  // reset all tabs in group
  const triggers = group.querySelectorAll('[data-tab-trigger]');
  triggers.forEach(tab => {
    const activeClasses = parseClassList(tab.getAttribute('data-tab-active-classes'));
@@ -14,6 +15,7 @@ const setActiveDiscoverTab = (clickedTab: Element): void => {
    tab.classList.add(...inactiveClasses);
  });

+  // mark clicked tab as active
  const activeClasses = parseClassList(clickedTab.getAttribute('data-tab-active-classes'));
  const inactiveClasses = parseClassList(clickedTab.getAttribute('data-tab-inactive-classes'));
  clickedTab.classList.remove(...inactiveClasses);
--- a/static/dropdown.ts
+++ b/static/dropdown.ts
@@ -1,7 +1,7 @@
 class UIDropdown extends HTMLElement {
  isOpen: boolean = false;
  contentEl: HTMLElement | null = null;
-  isClosing: boolean = false;
+  isClosing: boolean = false; // debounce flag

  constructor() {
    super();
@@ -53,7 +53,7 @@ class UIDropdown extends HTMLElement {
    }
    setTimeout(() => {
      this.isClosing = false;
-    }, 100);
+    }, 100); // delay prevents rapid open/close flicker
  }

  handleClickOutside(event: MouseEvent): void {
--- 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;
--- a/static/q.ts
+++ b/static/q.ts
@@ -1,7 +1,16 @@
+/**
+ * querySelector on a container element, scoped to that element.
+ */
 export const q = <T extends Element>(container: HTMLElement, selector: string): T | null =>
  container.querySelector(selector) as T | null;

+/**
+ * querySelector on the document.
+ */
 export const qs = <T extends Element>(selector: string): T | null =>
  document.querySelector(selector) as T | null;

+/**
+ * Get a data attribute value from an element, defaults to empty string.
+ */
 export const dataset = (el: HTMLElement, key: string): string => el.dataset[key] ?? '';
--- a/static/search.ts
+++ b/static/search.ts
@@ -1,5 +1,3 @@
-export {};
-
 type QuickSearchResult = {
  id?: number;
  image?: string;
@@ -7,6 +5,7 @@ type QuickSearchResult = {
  type?: string;
 };

+// singleton flag to prevent double init (e.g. htmx swaps)
 const searchInitializedKey = Symbol('searchInitialized');
 const globalWindow = window as Window & { [searchInitializedKey]?: boolean };

@@ -23,6 +22,7 @@ const isSafeImageUrl = (rawUrl?: string): boolean => {

  try {
    const parsed = new URL(rawUrl, window.location.origin);
+    // block data: URIs and other potentially dangerous protocols
    return parsed.protocol === 'https:' || parsed.protocol === 'http:';
  } catch {
    return false;
@@ -139,6 +139,7 @@ const onSearchInput = (event: Event): void => {
 };

 const onSearchBlur = (): void => {
+  // delay to allow clicking on results before clearing
  window.setTimeout(() => {
    clearSearchResults();
  }, 200);
--- a/static/sort_filter.ts
+++ b/static/sort_filter.ts
@@ -7,6 +7,7 @@ const initSortFilter = (): void => {
    if (form) form.submit();
  };

+  // sync select values to hidden inputs, then submit form
  sortSelect?.addEventListener('change', () => {
    const input = document.getElementById('sort-input') as HTMLInputElement | null;
    if (input) input.value = sortSelect.value;
--- a/static/theme.ts
+++ b/static/theme.ts
@@ -7,7 +7,7 @@ const getSavedTheme = (): Theme => {
  if (raw === 'light' || raw === 'dark') {
    return raw;
  }
-  return 'dark';
+  return 'dark'; // default to dark
 };

 const applyTheme = (theme: Theme): void => {
@@ -25,6 +25,7 @@ const initTheme = (): void => {
  const saved = getSavedTheme();
  applyTheme(saved);

+  // delegated click handler on theme buttons
  document.addEventListener('click', e => {
    const target = e.target as HTMLElement;
    const btn = target.closest('#theme-toggle, #footer-theme-toggle') as HTMLButtonElement | null;
--- a/static/timezone.ts
+++ b/static/timezone.ts
@@ -1,5 +1,6 @@
 export {};

+// JST offset from UTC in minutes (UTC+9)
 const jstOffsetMinutes = 9 * 60;

 type ParsedBroadcast = {
@@ -20,6 +21,7 @@ const parseBroadcastTime = (value: string | null): { hour: number; minute: numbe

  const hour = Number.parseInt(match[1], 10);
  const minute = Number.parseInt(match[2], 10);
+  // validate ranges
  if (
    Number.isNaN(hour) ||
    Number.isNaN(minute) ||
@@ -36,7 +38,7 @@ const parseBroadcastTime = (value: string | null): { hour: number; minute: numbe

 const isJstTimezone = (timezone: string | null): boolean => {
  if (!timezone) {
-    return true;
+    return true; // treat missing timezone as JST (anime default)
  }

  const normalized = timezone.trim().toLowerCase();
@@ -65,6 +67,7 @@ const parseBroadcast = (text: string | null): ParsedBroadcast | null => {
    return null;
  }

+  // matches "Monday at 00:00 (JST)" format
  const match = text.match(/^(.*) at (\d{1,2}):(\d{2}) \(JST\)$/i);
  if (!match) {
    return null;
@@ -86,6 +89,7 @@ const parseBroadcast = (text: string | null): ParsedBroadcast | null => {
 };

 const normalizeDay = (day: string): number | null => {
+  // strip trailing 's' for plural forms, then lookup
  const key = day.trim().toLowerCase().replace(/s$/, '');
  const days: Record<string, number> = {
    mon: 1,
@@ -116,11 +120,11 @@ const normalizeDay = (day: string): number | null => {

 const convertToLocal = (parsed: ParsedBroadcast, localOffsetMinutes: number): string | null => {
  const sourceMinutes = parsed.hour * 60 + parsed.minute;
-  const diff = jstOffsetMinutes - localOffsetMinutes;
+  const diff = jstOffsetMinutes - localOffsetMinutes; // JST ahead of local
  const localTotal = sourceMinutes - diff;

  const dayShift = Math.floor(localTotal / 1440);
-  const normalizedMinutes = ((localTotal % 1440) + 1440) % 1440;
+  const normalizedMinutes = ((localTotal % 1440) + 1440) % 1440; // handle negatives
  const localHour = Math.floor(normalizedMinutes / 60);
  const localMinute = normalizedMinutes % 60;

@@ -129,7 +133,7 @@ const convertToLocal = (parsed: ParsedBroadcast, localOffsetMinutes: number): st
    return null;
  }

-  const localDayIndex = (((sourceDayIndex + dayShift) % 7) + 7) % 7;
+  const localDayIndex = (((sourceDayIndex + dayShift) % 7) + 7) % 7; // proper modulo
  const localDay = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][
    localDayIndex
  ];
@@ -144,6 +148,7 @@ const nextAiringUTC = (parsed: ParsedBroadcast): Date | null => {
    return null;
  }

+  // convert local time to JST to compare against JST now
  const now = new Date();
  const jstNow = new Date(now.getTime() + jstOffsetMinutes * 60 * 1000);

@@ -152,6 +157,7 @@ const nextAiringUTC = (parsed: ParsedBroadcast): Date | null => {
  const targetMinuteOfDay = parsed.hour * 60 + parsed.minute;

  let dayDelta = (targetDay - currentDay + 7) % 7;
+  // if same day but time has passed, schedule for next week
  if (dayDelta === 0 && targetMinuteOfDay <= currentMinuteOfDay) {
    dayDelta = 7;
  }
@@ -161,11 +167,13 @@ const nextAiringUTC = (parsed: ParsedBroadcast): Date | null => {
 };

 const formatRelative = (value: number, unit: Intl.RelativeTimeFormatUnit): string => {
+  // Intl.RelativeTimeFormat not available in all environments
  if (typeof Intl !== 'undefined' && typeof Intl.RelativeTimeFormat === 'function') {
    const formatter = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
    return formatter.format(value, unit);
  }

+  // fallback: "in X minutes/hours/days"
  const suffix = value === 1 ? unit : `${unit}s`;
  return `in ${value} ${suffix}`;
 };
@@ -223,6 +231,7 @@ const updateNode = (node: Element, localOffsetMinutes: number): void => {
  const card = node.closest('[data-notification-content]');
  const nextNode = card ? card.querySelector('[data-next-airing]') : null;

+  // try structured attrs first, fall back to text parsing
  const structured = parseFromStructuredAttrs(node);
  const source = node.getAttribute('data-jst-text');
  const parsed = structured || parseBroadcast(source);
@@ -252,6 +261,7 @@ const updateAll = (): void => {
 };

 const initTimezoneConversion = (): void => {
+  // run on initial load and after htmx swaps (content may change)
  document.addEventListener('DOMContentLoaded', updateAll);
  document.body.addEventListener('htmx:afterSwap', updateAll);
 };
--- a/static/toast.ts
+++ b/static/toast.ts
@@ -5,6 +5,7 @@ interface ToastOptions {
  duration?: number;
 }

+/** Lazily create and return the toast container element. */
 const toastContainer = (): HTMLElement => {
  let container = document.getElementById('toast-container');
  if (!container) {
@@ -16,6 +17,10 @@ const toastContainer = (): HTMLElement => {
  return container;
 };

+/**
+ * Show a toast notification with optional auto-dismiss.
+ * Exposed globally via window.showToast.
+ */
 const showToast = ({ message, duration = 3000 }: ToastOptions): void => {
  const container = toastContainer();
  const template = document.getElementById('toast-template') as HTMLTemplateElement | null;
@@ -36,10 +41,12 @@ const showToast = ({ message, duration = 3000 }: ToastOptions): void => {

  container.appendChild(toast);

+  // trigger entrance animation
  requestAnimationFrame(() => {
    toast.classList.remove('translate-y-2', 'opacity-0');
  });

+  // auto-dismiss with exit animation
  setTimeout(() => {
    toast.classList.add('translate-y-2', 'opacity-0');
    setTimeout(() => toast.remove(), 300);
--- a/static/utils.ts
+++ b/static/utils.ts
@@ -1,3 +1,6 @@
+/**
+ * Parse a space-separated class list string into an array, filtering empty entries.
+ */
 export const parseClassList = (value: string | null): string[] => {
  if (!value) {
    return [];