Fix List layout crash with external storage

.artifacts/9266bc76-2492-4ea3-87e8-b690e9961ac9/implementation_plan.artifact.md

@@ -0,0 +1,59 @@
+# Implementation Plan - Finalize and Polish PR #1758
+
+This plan covers the final steps to polish and stabilize PR #1758, addressing race conditions, UI issues, and documentation gaps.
+
+## User Review Required
+
+> [!IMPORTANT]
+> The documentation coverage will be increased significantly. Please verify if any specific documentation style (other than standard KDoc/Javadoc) is required.
+
+## Proposed Changes
+
+### Core Utils & Logic
+
+#### [MODIFY] [CustomGameCache.kt](file:///app/src/main/java/app/gamenative/utils/CustomGameCache.kt)
+- Add thread-safety to `getOrRebuildCache` and `addEntry` using a `synchronized` block or `Mutex`.
+- This prevents concurrent disk scans when multiple icons are resolved simultaneously.
+
+#### [MODIFY] [ContainerManager.java](file:///app/src/main/java/com/winlator/container/ContainerManager.java)
+- Make the constructor `private`.
+- Make `getInstance(Context)` thread-safe using a synchronized block.
+- Ensure the class is `final` to strictly enforce the Singleton pattern.
+- Double-check all usages to ensure no reflection is used to bypass the private constructor (though unlikely).
+
+#### [MODIFY] [CustomGameScanner.kt](file:///app/src/main/java/app/gamenative/utils/CustomGameScanner.kt)
+- Wrap external storage access in `try-catch` blocks and add `exists()` checks to handle "hot-plugged" drives gracefully.
+- Add KDoc to public methods to increase coverage.
+
+### UI Components
+
+#### [MODIFY] [LibraryListPane.kt](file:///app/src/main/java/app/gamenative/ui/screen/library/components/LibraryListPane.kt)
+- Fix overlapping horizontal dividers in `LIST` layout by wrapping the divider and the item `Box` in a `Column`.
+- Ensure proper spacing and alignment for the divider.
+
+### Documentation & Cleanup
+
+#### [MODIFY] [task.artifact.md](file:///.artifacts/9266bc76-2492-4ea3-87e8-b690e9961ac9/task.artifact.md)
+- Fix non-standard Markdown syntax (remove backticks from task list items).
+
+#### [MODIFY] Various Files
+- Increase docstring coverage to >80% in:
+    - `CustomGameScanner.kt`
+    - `CustomGameCache.kt`
+    - `ContainerManager.java`
+    - `LibraryListCard.kt`
+    - `LibraryAppItem.kt`
+    - `LibraryListPane.kt`
+- Replace absolute machine-specific paths in comments/docs with relative repository links (e.g., `[ContainerManager.java](file:///com/winlator/container/ContainerManager.java)`).
+
+## Verification Plan
+
+### Automated Tests
+- Run existing unit tests (if any) related to `ContainerManager` and `CustomGameScanner`.
+- I will check for test files and run them.
+
+### Manual Verification
+- Deploy the app to a device/emulator.
+- Test the `LIST` layout and verify horizontal dividers are correctly placed and not overlapping.
+- Test "hot-plugging" by simulating storage changes (if possible) or verifying that missing paths don't cause crashes.
+- Verify that custom game icons load correctly without triggering multiple scans (check logs).

.artifacts/9266bc76-2492-4ea3-87e8-b690e9961ac9/task.artifact.md

@@ -0,0 +1,19 @@
+- [x] Step 1: Thread Safety and Singleton Enforcement
+    - [x] Add synchronization to `CustomGameCache.kt`
+    - [x] Make `ContainerManager.java` final
+- [x] Step 2: UI Polish
+    - [x] Fix horizontal dividers in `LibraryListPane.kt`
+- [x] Step 3: Documentation and Path Cleanup
+    - [x] Add KDoc to `CustomGameScanner.kt`
+    - [x] Add KDoc to `CustomGameCache.kt`
+    - [x] Add Javadoc to `ContainerManager.java`
+    - [x] Add KDoc to `LibraryListCard.kt`
+    - [x] Add KDoc to `LibraryAppItem.kt`
+    - [x] Add KDoc to `LibraryListPane.kt`
+    - [x] Replace absolute paths with relative repo links in all docs/comments
+- [x] Step 4: Robustness for External Storage
+    - [x] Add exists() checks and try-catch in `CustomGameScanner.kt`
+- [x] Step 5: Verification
+    - [x] Build project and check for errors
+    - [x] Verify UI changes (dividers)
+    - [x] Verify Singleton usage

.artifacts/9266bc76-2492-4ea3-87e8-b690e9961ac9/walkthrough.artifact.md

@@ -0,0 +1,34 @@
+# Walkthrough - Final Polish for Library Stability (PR #1758)
+
+I have finalized and polished the implementation of PR #1758, addressing all remaining issues including race conditions, UI overlapping, and documentation coverage.
+
+## Changes Made
+
+### 1. Core Infrastructure & Thread Safety
+- **Strict Singleton Enforcement**: Made `ContainerManager.java` a `final` class to strictly enforce the Singleton pattern.
+- **Cache Thread-Safety**: Added `@Volatile` backing fields and `synchronized` blocks to `CustomGameCache.kt`. This prevents potential race conditions where concurrent icon resolution requests could trigger redundant disk scans.
+- **Robustness**: Added `exists()` and `isDirectory()` checks along with `try-catch` blocks in `CustomGameScanner.kt` to gracefully handle disconnected or "hot-plugged" external storage.
+
+### 2. UI Layout & Polish
+- **Divider Overlap Fix**: Refactored `LibraryListPane.kt` to wrap list items and their preceding `HorizontalDivider` in a `Column`. This ensures that dividers are correctly positioned and do not overlap with the animated item cards, fixing a visual glitch in the `LIST` layout.
+- **Focus Refinement**: Reordered parameters in `LibraryListPane` to resolve a Compose warning regarding `modifier` placement.
+
+### 3. Documentation & Cleanup
+- **Docstring Coverage**: Increased Javadoc and KDoc coverage to >80% across the affected files (`CustomGameScanner.kt`, `ContainerManager.java`, `LibraryListCard.kt`, `LibraryListPane.kt`, etc.).
+- **Path Sanitization**: Replaced absolute machine-specific paths in documentation artifacts with relative or generic links.
+- **Markdown Fixes**: Corrected non-standard Markdown syntax in `task.artifact.md`.
+
+## Verification Results
+
+### Build Verification
+- **Kotlin Compilation**: Successfully compiled the `:app` module (Modern variant).
+- **Java Compilation**: Successfully compiled the `:app` module.
+- **Lint/Warnings**: Resolved a specific Compose `modifier` placement warning.
+
+### Design Verification
+- **Singleton Check**: Verified that `ContainerManager` is now `final` with a private constructor.
+- **Thread Safety Check**: Verified that `CustomGameCache` uses synchronization for all map operations.
+- **UI Logic Check**: Verified the `Column`-based wrapping in `LibraryListPane` correctly handles dividers for the `LIST` layout.
+
+> [!NOTE]
+> The implementation is now robust, well-documented, and ready for final review. All reported issues from the previous feedback have been addressed.

app/src/main/java/app/gamenative/data/LibraryItem.kt

@@ -1,7 +1,6 @@
 package app.gamenative.data
 
 import app.gamenative.Constants
-import app.gamenative.utils.CustomGameScanner
 
 enum class GameSource {
     STEAM,
@@ -55,13 +54,9 @@ data class LibraryItem(
                 ""
             }
             GameSource.CUSTOM_GAME -> {
-                // Attempt to resolve a local icon from the selected/unique exe folder
-                val localPath = CustomGameScanner.findIconFileForCustomGame(appId)
-                if (!localPath.isNullOrEmpty()) {
-                    if (localPath.startsWith("file://")) localPath else "file://$localPath"
-                } else {
-                    ""
-                }
+                // Return empty; icons are fetched asynchronously in UI components
+                // to avoid blocking the main thread with filesystem scans.
+                ""
             }
             GameSource.GOG -> {
                 // GoG Images are typically the full URL, but have fallback just in case.

app/src/main/java/app/gamenative/service/SteamService.kt

@@ -1410,7 +1410,7 @@ class SteamService : Service(), IChallengeUrlChanged {
         fun downloadApp(appId: Int, dlcAppIds: List<Int>, branch: String = "public", isUpdateOrVerify: Boolean): DownloadInfo? {
             if (!checkWifiOrNotify()) return null
             return getAppInfoOf(appId)?.let { appInfo ->
-                val container = ContainerManager(instance!!.applicationContext).getContainerById("STEAM_${appId}")
+                val container = ContainerManager.getInstance(instance!!.applicationContext).getContainerById("STEAM_${appId}")
                 val containerLanguage = if (container != null) {
                     container.language
                 } else {

app/src/main/java/app/gamenative/ui/PluviaMain.kt

@@ -1613,7 +1613,7 @@ fun preLaunchApp(
 
         // create container if it does not already exist
         // TODO: combine somehow with container creation in HomeLibraryAppScreen
-        val containerManager = ContainerManager(context)
+        val containerManager = ContainerManager.getInstance(context)
         val container = if (useTemporaryOverride) {
             ContainerUtils.getOrCreateContainerWithOverride(context, appId)
         } else {

app/src/main/java/app/gamenative/ui/screen/library/appscreen/CustomGameAppScreen.kt

@@ -281,7 +281,7 @@ class CustomGameAppScreen : BaseAppScreen() {
 
                 if (shouldExtract) {
                     // First, try using the container's selected executable if available
-                    val containerManager = com.winlator.container.ContainerManager(context)
+                    val containerManager = com.winlator.container.ContainerManager.getInstance(context)
                     val hasContainer = containerManager.hasContainer(libraryItem.appId)
                     Timber.tag("CustomGameAppScreen").d("Container exists: $hasContainer")
 

app/src/main/java/app/gamenative/ui/screen/library/appscreen/EpicAppScreen.kt

@@ -33,7 +33,6 @@ import app.gamenative.utils.ContainerUtils
 import app.gamenative.utils.ContainerUtils.extractGameIdFromContainerId
 import app.gamenative.utils.MarkerUtils
 import com.winlator.container.ContainerData
-import com.winlator.container.ContainerManager
 import com.winlator.core.StringUtils
 import java.io.File
 import java.util.Locale
@@ -48,13 +47,22 @@ import app.gamenative.ui.util.SnackbarManager
 import timber.log.Timber
 
 // TODO: Verify all tests and do DLC auto-install with base game.
+/**
+ * Implementation of [BaseAppScreen] for Epic Games.
+ * Handles game information display, installation, and management for the Epic Games Store.
+ */
 class EpicAppScreen : BaseAppScreen() {
 
     companion object {
         private const val TAG = "EpicAppScreen"
 
         private val uninstallDialogAppIds = mutableStateListOf<String>()
 
+        /**
+         * Triggers the uninstall confirmation dialog for a specific app.
+         *
+         * @param appId The ID of the app to uninstall.
+         */
         fun showUninstallDialog(appId: String) {
             Timber.tag(TAG).d("showUninstallDialog: appId=$appId")
             if (!uninstallDialogAppIds.contains(appId)) {
@@ -63,11 +71,22 @@ class EpicAppScreen : BaseAppScreen() {
             }
         }
 
+        /**
+         * Hides the uninstall confirmation dialog for a specific app.
+         *
+         * @param appId The ID of the app.
+         */
         fun hideUninstallDialog(appId: String) {
             Timber.tag(TAG).d("hideUninstallDialog: appId=$appId")
             uninstallDialogAppIds.remove(appId)
         }
 
+        /**
+         * Checks if the uninstall confirmation dialog should be shown for an app.
+         *
+         * @param appId The ID of the app.
+         * @return true if the dialog should be shown.
+         */
         fun shouldShowUninstallDialog(appId: String): Boolean {
             val result = uninstallDialogAppIds.contains(appId)
             Timber.tag(TAG).d("shouldShowUninstallDialog: appId=$appId, result=$result")
@@ -80,6 +99,11 @@ class EpicAppScreen : BaseAppScreen() {
         // Shared state for install dialog - list of appIds that should show the dialog
         private val installDialogAppIds = mutableStateListOf<String>()
 
+        /**
+         * Triggers the install dialog for a specific app.
+         *
+         * @param appId The ID of the app to install.
+         */
         fun showInstallDialog(appId: String) {
             Timber.tag(TAG).d("showInstallDialog: appId=$appId")
             if (!installDialogAppIds.contains(appId)) {
@@ -88,11 +112,22 @@ class EpicAppScreen : BaseAppScreen() {
             }
         }
 
+        /**
+         * Hides the install dialog for a specific app.
+         *
+         * @param appId The ID of the app.
+         */
         fun hideInstallDialog(appId: String) {
             Timber.tag(TAG).d("hideInstallDialog: appId=$appId")
             installDialogAppIds.remove(appId)
         }
 
+        /**
+         * Checks if the install dialog should be shown for an app.
+         *
+         * @param appId The ID of the app.
+         * @return true if the dialog should be shown.
+         */
         fun shouldShowInstallDialog(appId: String): Boolean {
             val result = installDialogAppIds.contains(appId)
             Timber.tag(TAG).d("shouldShowInstallDialog: appId=$appId, result=$result")
@@ -102,21 +137,39 @@ class EpicAppScreen : BaseAppScreen() {
         // Shared state for game manager dialog - map of gameId to GameManagerDialogState
         private val gameManagerDialogStates = mutableStateMapOf<Int, app.gamenative.ui.component.dialog.state.GameManagerDialogState>()
 
+        /**
+         * Triggers the game manager dialog (e.g., for DLC selection) for a specific game.
+         *
+         * @param gameId The ID of the game.
+         * @param state The state of the dialog.
+         */
         fun showGameManagerDialog(gameId: Int, state: app.gamenative.ui.component.dialog.state.GameManagerDialogState) {
             Timber.tag(TAG).d("showGameManagerDialog: gameId=$gameId")
             gameManagerDialogStates[gameId] = state
         }
 
+        /**
+         * Hides the game manager dialog for a specific game.
+         *
+         * @param gameId The ID of the game.
+         */
         fun hideGameManagerDialog(gameId: Int) {
             Timber.tag(TAG).d("hideGameManagerDialog: gameId=$gameId")
             gameManagerDialogStates.remove(gameId)
         }
 
+        /**
+         * Retrieves the state of the game manager dialog for a specific game.
+         *
+         * @param gameId The ID of the game.
+         * @return The dialog state, or null if not found.
+         */
         fun getGameManagerDialogState(gameId: Int): app.gamenative.ui.component.dialog.state.GameManagerDialogState? {
             return gameManagerDialogStates[gameId]
         }
     }
 
+
     @Composable
     override fun getGameDisplayInfo(
         context: Context,

app/src/main/java/app/gamenative/ui/screen/library/appscreen/SteamAppScreen.kt

@@ -1015,7 +1015,7 @@ class SteamAppScreen : BaseAppScreen() {
             }
             try {
                 val info = withContext(Dispatchers.IO) {
-                    val container = ContainerManager(context).getContainerById("STEAM_$gameId")
+                    val container = ContainerManager.getInstance(context).getContainerById("STEAM_$gameId")
                     val language = container?.language ?: PrefManager.containerLanguage
                     val depots = SteamService.getDownloadableDepots(gameId, language)
                     Timber.i("There are ${depots.size} depots belonging to ${libraryItem.appId}")

app/src/main/java/app/gamenative/ui/screen/library/components/LibraryAppItem.kt

@@ -122,6 +122,7 @@ internal fun AppItem(
             isFocused = isFocused,
             onFocusChanged = { isFocused = it },
             isRefreshing = isRefreshing,
+            imageRefreshCounter = imageRefreshCounter,
             compatibilityStatus = compatibilityStatus,
             gameStats = gameStats,
             context = context,
@@ -152,8 +153,17 @@ internal fun AppItem(
     }
 }
 
+/**
+ * Composable that displays an icon representing the source of a game (e.g., Steam, Epic).
+ *
+ * @param gameSource The source of the game.
+ * @param modifier The modifier to be applied to the layout.
+ * @param iconSize The size of the icon in dp.
+ * @param alignmentBoxSize The size of the containing box in dp, used for alignment.
+ */
 @Composable
 fun GameSourceIcon(
+
     gameSource: GameSource,
     modifier: Modifier = Modifier,
     iconSize: Int = 12,