fix: Keep game art in step with Steam's grid folder; apply review fixes (#948)

docs/development/added-games.md

@@ -68,7 +68,7 @@ store search whose result has the same name), then SteamGridDB, then the exe's i
 art chooser (an Artwork row) shows the game folder's images, Steam's official piece and
 SteamGridDB's best few (fetched when it opens); a tap applies one, "Search SteamGridDB…"
 opens a search (it starts with the game's name and opens the match at once when one is
-exact; it lists every image SteamGridDB returns for the slot), "Pick image…" takes a file through the same
+exact; it lists every image SteamGridDB returns for the slot, up to four pages of 50), "Pick image…" takes a file through the same
 picker (png, jpg, jpeg, webp, ico), "Reset to automatic" drops the choice. A choice is a
 copy in `files/added-art/<appid>/chosen-<slot>.<ext>`, its source in the preferences.
 
@@ -86,8 +86,16 @@ SteamGridDB's best few, "Search SteamGridDB…", "Pick image…", "Reset to auto
 through `ArtTarget`. A choice is a copy in `files/steam-art/<appid>/chosen-<slot>.<ext>`
 (`SteamGameArt`); `Library.steamGames` shows it in place of the librarycache image, and with a
 client running the Cover / Background / Logo is also set in Steam
-(`SetCustomArtworkForApp` / `ClearCustomArtworkForApp`). Choosing while Steam is closed changes
-the launcher only. Icon is launcher-only. Games from GOG, Epic and Amazon are not covered.
+(`SetCustomArtworkForApp` / `ClearCustomArtworkForApp`). Icon is launcher-only.
+
+`SteamGrid` keeps both sides in step through the client's grid folder
+(`userdata/<account>/config/grid`, `<appid>p`, `_hero`, `_logo`), for Steam and Custom games alike.
+A choice is written there at once, so it reaches Steam while the client is closed. Every library
+scan (`Library.launchableGames`) compares the folder with what was last written or read
+(`grid-<slot>` in the game's art folder): a file Steam changed becomes the choice (source Steam),
+a file removed in Steam drops it, and files the shortcuts writer placed itself
+(`.droiddeck-art.json`) are not mistaken for choices. A chosen image is stored as
+`chosen-<slot>-<time>.<ext>`, so a new choice has a new path and shows at once. Games from GOG, Epic and Amazon are not covered.
 
 Setup › Launcher › Games holds the Artwork switch (automatic fetching) and the
 SteamGridDB API key: the user's own, sealed with `CredentialCipher`, wins over the build's
@@ -98,5 +106,5 @@ skipped.
 
 `AddedExesTest`, `AddedGameEditsTest` (bulk add and skip, edits to the listing on a stable
 appid, Steam-side read-back, art choice and reset), `AddedGamesCandidatesTest`,
-`AddedGameArtLookupTest` (key precedence), `SteamGameArtTest` (Steam game art choice and reset), `GameIdentifierTest`, `PickListingTest`, and
+`AddedGameArtLookupTest` (key precedence), `SteamGameArtTest` (Steam game art choice and reset), `SteamGridTest` (grid folder both ways), `GameIdentifierTest`, `PickListingTest`, and
 `tools/tests/test_steam_shortcuts.py` for the writer.