- Enhances `playSongs` in `PlayerViewModel` to validate song accessibility using `ContentResolver` before playback, preventing crashes from missing files.
- Adds a toast notification for cases where no valid songs are found in the playback request.
- Gracefully handles filtered songs by adjusting the starting track if the original selection is inaccessible.
- Updates `ShimmerBox` to use `MaterialTheme` color schemes (`surfaceContainerHigh`/`Highest`) for better support across light and dark modes.
- Optimizes `ShimmerBox` animation duration and adds labels to the `rememberInfiniteTransition` for improved debugging.

- **Player & Navigation**:
    - Adds a new setting to toggle whether tapping the blurred background closes the player sheet, providing more control for power users.
    - Introduces a configurable "Album Art Quality" setting (Low to Original resolution) for the full player view to balance performance and visual fidelity.
    - Implements an observer to automatically hide the "Undo Dismiss" bar when playback transitions to a different song.
- **Library & Data**:
    - Refines artist song count logic in `MusicRepositoryImpl` to dynamically calculate real counts based on cross-references, ensuring accurate UI reporting.
    - Simplifies the initial setup flow by removing the "All Files Access" permission page for Android 11+.
- **UI & Components**:
    - **Stats Screen**: Improves the bar chart by adding horizontal scrolling and minimum widths when displaying numerous entries, preventing text truncation.
    - **Brick Breaker**: Updates game logic to handle container resizing without resetting game progress.
    - **Album Carousel**: Integrates the new album art quality preference into the image loading and prefetching logic.
    - **Settings**: Adds an "Experimental Settings" section for visual quality tweaks and developer options.
- **Miscellaneous**:
    - Adds a new "Special Thanks" contributor to the About screen.
    - Introduces `rounded_touch_app_24.xml` vector drawable for the new background-tap setting.

- **Player & Navigation**:
    - Adds a new setting to toggle whether tapping the blurred background closes the player sheet, providing more control for power users.
    - Introduces a configurable "Album Art Quality" setting (Low to Original resolution) for the full player view to balance performance and visual fidelity.
    - Implements an observer to automatically hide the "Undo Dismiss" bar when playback transitions to a different song.
- **Library & Data**:
    - Refines artist song count logic in `MusicRepositoryImpl` to dynamically calculate real counts based on cross-references, ensuring accurate UI reporting.
    - Simplifies the initial setup flow by removing the "All Files Access" permission page for Android 11+.
- **UI & Components**:
    - **Stats Screen**: Improves the bar chart by adding horizontal scrolling and minimum widths when displaying numerous entries, preventing text truncation.
    - **Brick Breaker**: Updates game logic to handle container resizing without resetting game progress.
    - **Album Carousel**: Integrates the new album art quality preference into the image loading and prefetching logic.
    - **Settings**: Adds an "Experimental Settings" section for visual quality tweaks and developer options.
- **Miscellaneous**:
    - Adds a new "Special Thanks" contributor to the About screen.
    - Introduces `rounded_touch_app_24.xml` vector drawable for the new background-tap setting.

- **Library & Data Persistence**:
    - Implements a new genre mapping system in `RealSongRepository` that queries `MediaStore.Audio.Genres` to correctly associate songs with their genres.
    - Updates `SyncWorker` to use `Timber` for more consistent and structured logging during MediaStore synchronization phases.
    - Refines the `SyncWorker` deletion logic to batch process missing files, improving performance and avoiding SQLite variable limits.
- **UI & UX Improvements**:
    - Adjusts placeholder box sizes in `FullPlayerContent` for a more balanced layout during playback loading states.
    - Updates `IMPLE_BETA_5.2.md` with a comprehensive implementation plan for upcoming features, including AI-generated playlists and specialized state holders.
- **Dependencies**:
    - Updates `material3` to `1.5.0-alpha12` in `libs.versions.toml`.
- **Bug Fixes**:
    - Fixes an issue in `RealSongRepository` where genre metadata was previously ignored due to complexity; now normalized and mapped via `AUDIO_ID` cross-references.

- Renames `RealSongRepository` to `MediaStoreSongRepository` to better reflect its responsibility of fetching music data from the Android MediaStore.
- Updates the `AppModule` dependency injection to provide the renamed repository for the `SongRepository` interface.
- Updates internal log tags within the repository to match the new class name.

… data consistency and support directory filtering.

- **Sync & Data Management**:
    - Updates `SyncWorker` to implement robust directory filtering using `DirectoryRuleResolver`, ensuring blocked paths are excluded during both ID fetching and full metadata scans.
    - Enhances incremental synchronization logic to preserve artist ID stability by pre-loading existing artist mappings and utilizing the maximum available ID.
    - Refines album grouping logic in the sync process to ensure consistent metadata (art and year) across entities.
    - Adds `dateModified` field to the `Song` model and `MediaStore` repository for better tracking of file changes.
- **Repository & Architecture**:
    - Refactors `MusicRepositoryImpl` to act as a true Single Source of Truth (SSOT), delegating data retrieval directly to `MusicDao` rather than `MediaStoreSongRepository`.
    - Optimizes repository methods (e.g., `getAlbums`, `getArtists`, `searchSongs`) to use IO-bound database queries instead of in-memory filtering.
- **Metadata & UI Theming**:
    - Updates `MetadataEditStateHolder` to force cache invalidation and theme regeneration when album art is updated.
    - Extends `ThemeStateHolder` and `ColorSchemeProcessor` with mechanisms to invalidate and re-generate color schemes for specific URIs.
- **Utilities**:
    - Improves `DirectoryRuleResolver` logic to support nested rules, using the most specific (longest) path match to determine if a directory is blocked or allowed.
- **Database**:
    - Adds helper queries to `MusicDao` for retrieving artist IDs by name and finding the maximum artist ID.

- **MediaStoreSongRepository**:
    - Simplifies `normalizePath` to use `absolutePath` instead of attempting to resolve `canonicalPath`, reducing unnecessary overhead and potential IO exceptions during path normalization.
- **DirectoryRuleResolver**:
    - Improves `isParentOrSame` logic by using case-insensitive prefix matching for path comparisons.
    - Refactors path length checks to safely handle bounds when determining if a path is a subdirectory.

…fined sync logic

- **Paging & Data Loading**:
    - Introduces `MediaStorePagingSource` to support efficient, paginated loading of songs based on pre-filtered IDs, ensuring complex directory rules are applied before paging.
    - Refactors `LibraryStateHolder` to use reactive collectors instead of imperative "load" functions, ensuring the UI remains in sync with the underlying data source automatically.
- **Repository & Architecture**:
    - Updates `MusicRepositoryImpl` to delegate data retrieval to `songRepository`, enabling real-time UI updates when directory preferences change.
    - Enhances `MediaStoreSongRepository` with a relaxed base selection filter (removing `IS_MUSIC` check) to capture a broader range of audio files while maintaining a minimum duration threshold.
    - Implements `getPaginatedSongs` in the repository layer to provide a seamless `PagingData` flow.
- **Synchronization & Worker**:
    - Restores and refines `SyncWorker` scheduling within `SyncManager` to handle incremental background rescans.
    - Updates `SyncWorker` scanning logic to support a "Global Augmented Scan," allowing it to bypass system-folder skip rules (like the `Android/` directory) if a subdirectory is explicitly allowed.
    - Improves directory normalization by switching from `canonicalPath` to `absolutePath` to avoid unnecessary IO overhead.
- **UI & UX Flow**:
    - Updates `SettingsViewModel` and `SetupViewModel` to handle directory permission toggles within a coroutine scope, ensuring preferences are saved before triggering a refresh.
    - Refines `FileExplorerStateHolder` logic for `toggleDirectoryAllowed` with optimistic updates to prevent UI race conditions during rapid toggles.
- **Bug Fixes & Refinements**:
    - Fixes logic in `FileExplorerStateHolder` to correctly handle nested directory rules (e.g., unblocking a parent while preserving specific child rules).
    - Optimizes path matching in `MediaStoreSongRepository` using string manipulation (`lastIndexOf`) instead of creating `File` objects.

- **ThemeStateHolder**:
    - Introduces `currentAlbumArtUri` to track the URI of the currently active album art, allowing for precise cache invalidation and UI updates.
    - Updates `extractAndGenerateColorScheme` to maintain the new `currentAlbumArtUri` state during successful extractions and error resets.
    - Refines `forceRegenerateColorScheme` to automatically update the global `_currentAlbumArtColorSchemePair` if the invalidated URI matches the currently playing track, ensuring the UI reflects color changes immediately.

- **ColorSchemeProcessor**:
    - Updates `getOrGenerateColorScheme` to support a `forceRefresh` parameter, allowing the system to bypass memory and database caches.
    - Modifies `loadBitmapForColorExtraction` to disable Coil's memory and disk cache policies when a refresh is forced, ensuring the latest image data is used for extraction.
- **ThemeStateHolder**:
    - Refines `forceRegenerateColorScheme` to utilize the new `forceRefresh` flag in `ColorSchemeProcessor`.
    - Adds debug logging to track URI matching and state updates during regeneration.
    - Ensures the global color scheme flow is updated immediately if the invalidated URI matches the currently active album art.