KVideo/TODO.md

KVideo - Remaining Tasks Checklist

✅ Completed (Core Logic Implementation)

• TypeScript type definitions
• API source configuration and management
• HTTP client with retry logic
• Search API endpoint
• Detail API endpoint
• Player state store (Zustand)
• History state store (Zustand)
• Progress tracking utilities
• Error handling utilities
• Search optimization utilities
• Episode management utilities
• Source switching utilities
• M3U8 ad filtering utilities
• Comprehensive documentation

🎯 Next Steps (UI Implementation)

Phase 1: Setup & Configuration

• Run npm install to install dependencies
• Update lib/api/video-sources.ts with real API endpoints
• Test API sources with health check
• Verify API routes work correctly

Phase 2: Core UI Components

Search Components

• Create components/search/SearchBar.tsx

  • Integrate debounce from lib/utils/search.ts
  • Use search history
  • Implement autocomplete

• Create components/search/VideoGrid.tsx

  • Display search results
  • Show source badges
  • Implement infinite scroll or pagination

• Create components/search/VideoCard.tsx

  • Show video poster, title, year, type
  • Display video metadata
  • Click handler to navigate to player

• Create components/search/SearchFilters.tsx

  • Filter by year, area, type
  • Sort options (relevance, year, name)

Player Components

• Create components/player/VideoPlayer.tsx

  • Initialize HLS.js with createAdFilteringConfig()
  • Integrate Artplayer
  • Connect to usePlayerStore
  • Implement progress saving with createProgressSaver()
  • Handle HLS errors with handleHLSError()
  • Auto-resume from getProgress()
  • Auto-play next episode when enabled

• Create components/player/PlayerControls.tsx

  • Play/pause button
  • Volume control
  • Playback rate selector
  • Fullscreen toggle
  • Progress bar

• Create components/player/EpisodeList.tsx

  • Display episodes with useEpisodes()
  • Highlight current episode
  • Use buildPlayerUrl() for navigation
  • Show watched progress
  • Support episode order toggle

• Create components/player/SourceSwitcher.tsx

  • Button to trigger source test
  • Display testAllSources() results
  • Show speed indicators with colors
  • Handle source selection
  • Use buildSourceSwitchUrl()

History & Extras

• Create components/history/HistoryList.tsx

  • Display useViewingHistory()
  • Show progress bars
  • Resume playback button
  • Delete history item option

• Create components/common/ErrorBoundary.tsx

  • Catch React errors
  • Display user-friendly messages
  • Retry button

• Create components/common/LoadingSpinner.tsx

  • Show during API requests
  • Skeleton loaders for cards

Phase 3: Pages

• Create/Update app/page.tsx (Home/Search page)

  • SearchBar component
  • VideoGrid component
  • SearchFilters component

• Create app/player/page.tsx

  • VideoPlayer component
  • EpisodeList component
  • SourceSwitcher component
  • Parse URL params with parsePlayerParams()

• Create app/history/page.tsx

  • HistoryList component
  • Clear history button

• Create app/settings/page.tsx (Optional)

  • Custom source management
  • Ad pattern configuration
  • Autoplay settings
  • Clear cache options

Phase 4: Integration & Testing

• Connect SearchBar to /api/search
• Connect VideoPlayer to /api/detail
• Test progress save/restore flow
• Test source switching functionality
• Test error recovery mechanisms
• Test episode navigation
• Test history tracking
• Cross-browser testing

Phase 5: Styling (Using Liquid Glass Design System)

• Apply Liquid Glass styles to all components

  • Use rounded-2xl for containers
  • Use rounded-full for avatars/badges/buttons
  • Implement glass effect with backdrop-filter
  • Add smooth animations
  • Ensure dark mode support

• Responsive design

  • Mobile-first approach
  • Breakpoints for tablet/desktop
  • Touch-friendly controls

Phase 6: Enhancements (Optional)

• Add keyboard shortcuts for player
• Implement picture-in-picture mode
• Add subtitle support
• Implement video quality selection
• Add favorites/bookmarks feature
• Implement watch later queue
• Add share functionality
• PWA support (offline mode)
• Add analytics tracking

Phase 7: Deployment

• Configure environment variables
• Set up production build
• Optimize images and assets
• Enable compression
• Configure caching headers
• Deploy to Vercel/Netlify
• Set up monitoring and error tracking
• Performance testing

📝 Example Code Templates

SearchBar Integration

import { debounce } from '@/lib/utils/search';
import { useState } from 'react';

const handleSearch = debounce(async (query: string) => {
  const response = await fetch('/api/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, sources: ['source_1'] }),
  });
  const data = await response.json();
  setResults(data.sources.flatMap(s => s.results));
}, 500);

VideoPlayer Integration

import Hls from 'hls.js';
import { createAdFilteringConfig } from '@/lib/utils/m3u8-filter';
import { usePlayerStore } from '@/lib/store/player-store';
import { createProgressSaver } from '@/lib/utils/progress-tracker';

const { currentVideo } = usePlayerStore();
const saveProgress = createProgressSaver();

useEffect(() => {
  const hls = new Hls(createAdFilteringConfig());
  hls.loadSource(currentVideo.url);
  hls.attachMedia(videoRef.current);
  
  videoRef.current.addEventListener('timeupdate', () => {
    saveProgress(
      currentVideo.id,
      currentVideo.source,
      videoRef.current.currentTime,
      videoRef.current.duration,
      currentVideo.episodeIndex
    );
  });
}, [currentVideo]);

Source Switcher Integration

import { testAllSources, getSpeedIndicator } from '@/lib/utils/source-switcher';
import { getEnabledSources } from '@/lib/api/video-sources';

const handleSwitchSource = async () => {
  const sources = getEnabledSources();
  const results = await testAllSources(videoTitle, sources, currentSource);
  
  results.forEach(result => {
    const indicator = getSpeedIndicator(result.speed);
    // Display with color: indicator.color
  });
};

🎯 Priority Order

1. High Priority (Core Functionality)

   • SearchBar, VideoGrid, VideoCard
   • VideoPlayer with HLS integration
   • Basic EpisodeList
   • Progress tracking

2. Medium Priority (Enhanced UX)

   • SourceSwitcher
   • HistoryList
   • Error handling UI
   • PlayerControls

3. Low Priority (Nice to Have)

   • Settings page
   • Advanced filters
   • PWA features
   • Analytics

📊 Estimated Time

• Phase 1: Setup - 30 minutes
• Phase 2: Components - 8-12 hours
• Phase 3: Pages - 2-4 hours
• Phase 4: Integration - 2-4 hours
• Phase 5: Styling - 4-6 hours
• Phase 6: Enhancements - Variable
• Phase 7: Deployment - 2-3 hours

Total Core Implementation: ~20-30 hours

🔍 Testing Checklist

• Search returns results from multiple sources
• Video plays with ad filtering
• Progress saves and restores correctly
• Source switching tests and switches sources
• Episode navigation works
• History tracks correctly
• Errors recover gracefully
• Works on mobile/tablet/desktop
• Dark mode works
• LocalStorage persists across sessions

---

Current Status: All business logic implemented ✅
Ready for: UI component development

Good luck building the UI! 🚀