Implementation Notes

This document provides detailed technical implementation notes for key features and systems within the IINA Bookmarks Plugin, including architectural decisions, code changes, and testing approaches.

Multi-Criteria Bookmark Sorting (Issue #40)

Overview

Successfully implemented comprehensive multi-criteria bookmark sorting across all UI views (overlay, sidebar, window) with up to 3 simultaneous sort criteria and priority-based fallback.

Key Features Implemented

Technical Implementation

Core Files Modified

1. ui/components/FilterComponent.tsx

• Extended FilterState interface with sortCriteria and enableMultiSort
• Added multi-sort UI components with priority management
• Implemented sort criteria add/remove/modify logic
• Added automatic sort preference persistence

2. ui/hooks/useAdvancedBookmarkFilters.ts

• Enhanced applySorting function for multi-criteria support
• Added extractFileName utility for media file name sorting
• Implemented priority-based comparison algorithm
• Added support for new sorting fields (description, tags, mediaFileName)

3. ui/shared.scss

• Comprehensive CSS for multi-sort UI components
• Priority indicators, criterion management controls
• Responsive design for compact sidebar/overlay modes
• Smooth transitions and hover effects

4. src/index.ts

• Added sort preference persistence via IINA preferences
• Implemented SAVE_SORT_PREFERENCES message handling
• Added preference loading/saving methods

5. ui/hooks/usePersistentState.ts

• Added usePersistentSortPreferences hook
• Automatic preference saving when sort settings change

Multi-Criteria Comparison Algorithm

function compareBookmarks(a: Bookmark, b: Bookmark, criteria: SortCriterion[]): number {
  // Sort criteria by priority (lower number = higher priority)
  const sortedCriteria = criteria.sort((a, b) => a.priority - b.priority);
  
  for (const criterion of sortedCriteria) {
    // Apply field-specific comparison
    const result = compareByCriterion(a, b, criterion);
    
    // If comparison !== 0, return result (accounting for direction)
    if (result !== 0) {
      return criterion.direction === 'desc' ? -result : result;
    }
    
    // If comparison === 0, continue to next criterion
  }
  
  // If all criteria result in equality, return 0
  return 0;
}

Field-Specific Comparisons

• Title: localeCompare() for proper Unicode handling
• Timestamp: Numeric comparison
• Description: Case-insensitive localeCompare()
• Tags: Concatenated tags with comma separator, case-insensitive
• Media File Name: Extracted filename, extension removed, case-insensitive
• Creation Date: ISO date parsing to timestamp comparison

UI/UX Implementation

Single-Sort Mode

• Enhanced dropdown with all 6 sorting options
• Direction indicators (↑ Asc, ↓ Desc)
• "⚡ Multi" button to enable multi-criteria mode

Multi-Sort Mode

• Priority-numbered criteria with visual indicators
• Individual field and direction selectors per criterion
• "✕" buttons to remove individual criteria
• "+ Add Sort" button (up to 3 criteria limit)
• "✕" button in header to disable multi-sort mode

Visual Design

• Color-coded priority badges (#4a90e2 blue theme)
• Consistent with existing filter component styling
• Compact variations for sidebar and overlay views
• Smooth hover effects and transitions

Fallback Behavior Implementation (Issue #59)

Overview

Standardized and improved fallback behavior for bookmark titles, eliminating code duplication and providing consistent title extraction across the application.

Implementation Details

Fallback Hierarchy

The system uses a clear hierarchy when determining bookmark titles:

• Metadata Title (Highest Priority)

  • Uses iina.core.status.title when available and meaningful
  • Filters out cases where title is just the filename or "Unknown Media"

• Cleaned Filename (Fallback)

  • Extracts filename from file path
  • Removes file extension
  • Replaces separators (dots, underscores, dashes) with spaces
  • Removes quality indicators (720p, 1080p, 4K, etc.)
  • Removes source indicators (BluRay, DVDRip, WEB-DL, etc.)
  • Removes codec information (x264, x265, H264, etc.)
  • Capitalizes words properly
  • Removes years in parentheses

• "Unknown Media" (Final Fallback)

  • Used when no meaningful title can be extracted

Code Changes

• Removed duplicate code: Eliminated extractMediaTitle() method from BookmarkManager
• Centralized logic: All fallback logic now handled by MetadataDetector.extractTitleFromFilename()
• Improved consistency: Same fallback behavior used throughout the application
• Enhanced cleaning: More sophisticated filename cleaning algorithm

Example Transformations

Filename Cleaning Algorithm

function cleanFilename(filename: string): string {
  return filename
    // Remove file extension
    .replace(/\.[^/.]+$/, '')
    
    // Replace separators with spaces
    .replace(/[._-]/g, ' ')
    
    // Remove quality indicators
    .replace(/\b(720p|1080p|4K|2160p|480p|1440p)\b/gi, '')
    
    // Remove source indicators
    .replace(/\b(BluRay|DVDRip|WEB-DL|WEBRip|HDTV|CAM|TS)\b/gi, '')
    
    // Remove codec information
    .replace(/\b(x264|x265|H264|H265|HEVC|AVC)\b/gi, '')
    
    // Remove years in parentheses
    .replace(/\(?\b(19|20)\d{2}\b\)?/g, '')
    
    // Clean up extra spaces and capitalize
    .replace(/\s+/g, ' ')
    .trim()
    .split(' ')
    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
    .join(' ');
}

Testing Implementation

Multi-Criteria Sorting Tests

Manual Testing Scenarios

• Single-Sort Testing

  • Test each sort option (6 fields × 2 directions = 12 combinations)
  • Verify sort order correctness with diverse bookmark data
  • Test sort persistence across UI reload

• Multi-Sort Testing

  • Create bookmarks with identical primary sort values
  • Verify secondary/tertiary sort criteria work correctly
  • Test all priority combinations (1-3 criteria)

• UI/UX Testing

  • Test add/remove criteria functionality
  • Verify compact mode in sidebar/overlay
  • Test smooth transitions and hover effects
  • Validate responsive behavior

• Integration Testing

  • Test sorting combined with search filters
  • Test sorting combined with tag filters
  • Test sorting combined with date range filters
  • Verify preference persistence across plugin reload

Performance Testing

• Test with large bookmark datasets (100+ bookmarks)
• Verify sorting performance with complex multi-criteria
• Test UI responsiveness during sort operations

Fallback Behavior Tests

Test Suite: tests/fallback-behavior.test.ts

• Comprehensive test suite validates core functionality
• Edge cases handled properly (empty strings, special characters)
• Performance requirements met (less than 100ms response time)
• Caching mechanisms validated

Performance Considerations

Optimization Strategies

• Debounced Operations

  • Sort operations debounced to prevent excessive processing
  • UI updates optimized to minimize reflow

• Caching Mechanisms

  • Filename extraction results cached
  • Sort comparison results memoized for repeated operations

• Memory Management

  • Efficient data structures for sort criteria storage
  • Garbage collection optimized through proper cleanup

• Responsive Design

  • Non-blocking sort operations
  • Progressive enhancement for large datasets

Performance Metrics

Future Enhancement Opportunities

Planned Improvements

• Advanced Sorting

  • Drag-and-drop priority reordering
  • Custom sort orders and templates
  • Sort performance indicators
  • Additional sort fields (duration, file size, path depth)

• Enhanced Testing

  • Automated UI testing with Playwright
  • Performance benchmarking suite
  • Cross-browser compatibility testing

• Code Quality

  • TypeScript strict mode compliance
  • ESLint and Prettier integration
  • Automated code review workflows

Technical Debt

• Refactoring Opportunities: Consolidate similar comparison functions
• Type Safety: Enhance TypeScript definitions for sort criteria
• Documentation: Auto-generate API documentation from code comments

Debugging and Troubleshooting

Debug Mode

Enable comprehensive logging for development:

// Enable debug logging for all bookmark operations
localStorage.setItem('bookmark-debug', 'true');

// Enable specific debug categories
localStorage.setItem('bookmark-sort-debug', 'true');
localStorage.setItem('bookmark-filter-debug', 'true');
localStorage.setItem('bookmark-persistence-debug', 'true');

Common Development Issues