Global filters, unit tests and UI enhancements

.gitignore

@@ -1,5 +1,12 @@
 game_library.db
 
+# Copilot documentation
+.copilot-docs/
+
+# OpenSpec workflow and GitHub configs
+.github/
+openspec/
+
 # Docker
 data/
 .empty/
@@ -219,4 +226,7 @@ marimo/_lsp/
 __marimo__/
 
 # Streamlit
-.streamlit/secrets.toml
+.streamlit/secrets.toml
+
+# Claude code
+.claude/

CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **Predefined query filters system**: 18 quick filters organized in 4 categories for better library organization:
+  - **Gameplay** (5 filters): Unplayed, Played, Started, Well-Played, Heavily-Played
+  - **Ratings** (7 filters): Highly-Rated, Well-Rated, Below-Average, Unrated, Hidden Gems, Critic Favorites, Community Favorites
+  - **Dates** (5 filters): Recently Added, Older Library, Recent Releases, Recently Updated, Classics
+  - **Content** (2 filters): NSFW, Safe
+- **Global filter persistence**: Filters always apply across all pages (Library, Discover, Collections, Random) and persist via localStorage
+- **Random page**: New `/random` endpoint with full page displaying configurable number of random games (default 12, max 50) with filter support
+- **Reusable filter components**: Component-based architecture with `_filter_bar.html`, `filters.css`, and `filters.js` for consistent UX
+- **Performance optimizations**:
+  - Database indexes on frequently filtered columns (playtime_hours, total_rating, added_at, release_date, nsfw, last_modified)
+  - Discover page: reduced from 5+ queries to 1 UNION ALL query
+  - IGDB popularity data: 24-hour caching system to reduce API calls
+- **Comprehensive test suite**: 69 tests covering:
+  - Filter definitions and SQL generation (26 unit tests)
+  - Filter combinations and edge cases (26 integration tests)
+  - Empty library handling (7 tests)
+  - Performance with 10,000 games (6 tests)
+  - Recently Updated filter edge cases (4 tests)
+- **Documentation**: Complete technical documentation in `.copilot-docs/` covering filter system architecture, SQL reference, and database schema
+
+### Changed
+- **Filter behavior**: Removed "Apply filters globally" checkbox—filters are now always global for simpler UX
+- **Filter application**: Auto-apply with 300ms debounce using event delegation for better reliability
+- **Random page**: Converted from redirect to full HTML page with game grid and filter integration
+- **Filter bar**: Custom dropdowns with dark theme styling and count badges
+- **Custom dropdowns**: Replaced native select elements with styled dropdowns for consistent dark theme
+
+### Fixed
+- Filter state persistence across page navigations
+- Event listeners for dynamically loaded filter checkboxes using event delegation
+- Recently Updated filter now works for all stores (uses `last_modified` field instead of Epic-specific `game_update_at`)
+
+### Technical Details
+- **New files**:
+  - `web/utils/filters.py`: Filter definitions (PREDEFINED_QUERIES, QUERY_DISPLAY_NAMES, QUERY_CATEGORIES, QUERY_DESCRIPTIONS)
+  - `web/templates/_filter_bar.html`: Reusable filter bar component
+  - `web/templates/random.html`: Random games page with grid layout
+  - `web/static/css/filters.css`: Filter-specific styles
+  - `web/static/js/filters.js`: Filter management with global state
+  - `tests/test_predefined_filters.py`: Unit tests (26)
+  - `tests/test_predefined_filters_integration.py`: Integration tests (26)
+  - `tests/test_empty_library.py`: Empty library tests (7)
+  - `tests/test_large_library_performance.py`: Performance tests (6)
+  - `tests/test_recently_updated_edge_case.py`: Edge case tests (4)
+  - `.copilot-docs/filter-system.md`: Filter system architecture
+  - `.copilot-docs/filter-sql-reference.md`: SQL conditions reference
+  - `.copilot-docs/database-schema.md`: Database schema documentation
+- **Modified routes**: `library.py`, `discover.py`, `collections.py`, `settings.py` to support `queries` parameter
+- **Database**: Added `popularity_cache` table and `ensure_predefined_query_indexes()` in `database.py`

README.md

@@ -42,6 +42,21 @@ All your games from every store, displayed in one place. Smart deduplication ens
 - **Flexible sorting** — Sort by name, rating, playtime, or release date
 - **Store indicators** — See at a glance which platforms you own each game on
 
+### Smart Filters
+
+Quickly find games that match your mood with 18 predefined filters organized into categories:
+
+- **Gameplay Filters** — Unplayed, Played, Started, Well-Played (5+ hours), Heavily-Played (20+ hours)
+- **Rating Filters** — Highly-Rated (90+), Well-Rated (75+), Below-Average (<70), Unrated, Hidden Gems, Critic Favorites, Community Favorites
+- **Date Filters** — Recently Added (30 days), Older Library (180+ days), Recent Releases (90 days), Recently Updated, Classics (pre-2000)
+- **Content Filters** — NSFW, Safe
+
+**Features:**
+- **Result count badges** — See how many games match each filter before applying it
+- **Global Filters Mode** — Enable "Apply filters globally" to keep your selected filters active across all pages (Library, Discover, Collections, Random)
+- **Keyboard navigation** — Use arrow keys to navigate filters, Esc to close dropdowns, Enter/Space to toggle filters
+- **Accessibility** — Full ARIA label support and screen reader compatibility
+
 ### Rich Game Details
 
 Every game is enriched with metadata from IGDB (Internet Game Database), giving you consistent information across all stores.
@@ -65,7 +80,7 @@ Find your next game to play with curated discovery sections based on your actual
 - **Highly rated** — Games scoring 90+ ratings
 - **Hidden gems** — Quality games that deserve more attention
 - **Most played** — Your games ranked by playtime
-- **Random pick** — Can't decide? Let Backlogia choose for you
+- **Random pick** — Can't decide? Let Backlogia surprise you with one game. Works with global filters to respect your preferences
 
 ### Custom Collections