Search window speedups, including for very large decks

[liamiak]

What this fixes

With a large (~500 card) deck, any effect that opens the library view froze the UI for
several seconds — and froze it again on right-click sort, on close, and on every reopen.

Measured

Instrumented on a 500-card library, reopening the search window:

cards=492 totalMs=6156 panelLoopMs=6142 setPanelsMs=1 promptMs=0
scaleImage calls=984 hits=208 misses=776 scaleMs=6110
cacheDelta miss=1548 loadOk=204 loadEx=568 loadMs=1430 evict=696

99% of the time was inside ImageCache.scaleImage, and about three quarters of that
was re-rendering card faces for cards with no local image — ~284 of them, at ~16ms each,
redrawn on every single refresh because placeholder renders were deliberately never cached.
The remainder was image decode, made worse by ~700 cache evictions per refresh against a
400-entry cap that could not hold even one such view.

Panel bookkeeping — the thing that looks quadratic and was — turned out to be ~30ms of the
6156. It is fixed here too, but it was never the problem.

The commits

1. Zone view refreshes. doRefresh matched cards to panels with a linear scan each
   (quadratic in zone size); setCardPanels did the same in its dispose loop.
   updatePromptVisibility called getCards() for one anyMatch, and getCards() copies,
   sorts and filters the whole zone every call — so a refresh walked the zone twice. Bursts
   of zone-change events each rebuilt the whole window; those are now coalesced, with a flush
   for the animation/targeting lookups that need current panels immediately.

2. Cache placeholder renders, and size the cache. The 77% above. Placeholder renders are
   cached and tracked so image-presence probes aren't fooled, and dropped when the fetcher
   delivers the real image. The 400-entry cap is treated as "unset" and raised to 1500 — see
   the note below. Soft values so memory pressure, not entry count, is what ultimately evicts.

3. Load card images asynchronously. Decode, corner rounding, resampling and
   ImageKeys.getImageFile's File.exists cascade move off the EDT. Only provably-pure image
   work leaves it: key resolution beyond ImageKeys, placeholder rendering
   (FCardImageRenderer has mutable statics) and Card.getCardForUi were audited as not
   thread-safe and stay. Resizes also stop re-running the full setCard per layout pass.

4. Cache the drawn card face. A face is always drawn at 488x680 times the screen scale
   regardless of the size requested, and only the resample afterwards is size-specific —
   ~16ms against ~1ms. Caching only the scaled copy meant a different size redrew from
   scratch. Caching the render itself makes any later request at any size a resample away.

5. Warm deck card images at match start. The first search of a match was always cold, and
   the placeholder rendering that dominates it cannot leave the EDT. So do it early: decode
   deck images on a worker, hand missing ones to the online fetcher, and draw their faces one
   per EDT event while nobody is waiting. Because (4) caches a face independently of display
   size, this needs no advance knowledge of how large the eventual view will be.

Notes for reviewers

• On raising the image cache size. UI_IMAGE_CACHE_MAXIMUM defaults to 400 and appears
  nowhere in the settings UI, so in practice nobody has chosen it — and because
  AbstractPreferences.save() writes every key, existing users all have a literal 400 in
  their preferences file, so raising the default alone would fix nothing for them. This treats
  exactly 400 as "unset" and uses 1500, leaving any other value alone as one somebody actually
  set. Happy to change the approach if you'd rather this were surfaced as a real setting.

• Commit 3 is not measurable on the machine this was tested on. With ~57% of that
  collection's images missing locally, most cards take the placeholder path, which stays on the
  EDT — so moving decode off it changes little there. Its value is arithmetic rather than
  observed: ~14ms per card of decode, so on the order of seconds for a user with a complete
  local collection. Flagging it rather than letting it ride on the overall result.

• The measurements are from one machine and one collection state. The 77% figure is
  specific to a partially-downloaded collection. With all images present the split shifts
  toward decode and cache sizing.

• getImageNoDefault had no remaining callers after commit 3 and is removed.

Testing

• mvn -pl forge-gui-desktop -am test: 286 tests, 0 failures, at every commit in the series.
• Manual play on Windows 11 with a ~500-card deck and a partially-downloaded image collection:
  search open/sort/close/reopen, first-search-of-match on a fresh profile, battlefield play,
  card-move animations, targeting, stack and game log, and placeholder→downloaded-image
  replacement.

🤖 Implemented with the assistance of Claude Code (Opus).

[tool4ever]

thanks, interesting ideas but rather large:
might take a while until a Dev with GUI interest has time to comb through it

[liamiak]

Force-pushed a rewrite of this branch — "rather large" was fair, and I wanted to re-review
the whole thing with Opus 5.0 and restructure it for ease of evaluation rather than leave it
sitting as one big lump. Rebased onto current master (nothing there has touched these files).

It is now five commits, each one mechanism, each building and passing the desktop test suite
on its own. The description above is rewritten around measurements rather than assertions.

Instrumenting it changed the PR rather than just documenting it. I had assumed the cost was
image decode plus cache eviction thrash. It is neither: ~77% of a 6.2s reopen was
re-rendering card faces for cards with no local image — ~284 of them at ~16ms, redrawn on
every refresh because placeholder renders were explicitly never cached ("the rendering speed
seems to be fast enough", which does not survive being multiplied by 284). The quadratic panel
bookkeeping I had led with turned out to be ~30ms of the 6156.

That also let me delete things rather than add them. Gone since you last looked:

• the new ZONE_CARD_IMAGE_SIZE preference and its ForgePreferences entry, along with the
  prefs.save() it did from inside a layout path — once a drawn card face is cached
  independently of display size, preloading no longer needs to know what size a view will ask
  for, so the preference had nothing left to do
• a whole-cache scan per downloaded image, replaced by a multimap of the affected keys
• a static font cache and a couple of other micro-optimisations that were not worth the
  questions they invited

Net effect is one fewer file touched than the version you commented on, and no new user
preference anywhere in the PR.

Two things I would rather flag than have you find:

• Commit 3 (async loading) is not measurable on the machine I tested on. ~57% of that
  collection's images are missing locally, and placeholder rendering has to stay on the EDT
  because FCardImageRenderer has mutable statics — so moving decode off it changes little
  there. The case it helps is a complete local collection, where the same numbers imply
  seconds saved, but that is inference from measurement rather than a measurement. If you
  would rather see it land separately, or not at all, that is a reasonable call.
• All the numbers come from one machine and one collection state, so the 77% is not a
  universal figure.

[tool4ever]

good call, that will surely help

[tool4ever]

Also worth noting Nr. 5 is related to a previous attempt: #7838

[liamiak]

Thanks — that pointer led somewhere I didn't expect.

Reading #7838, the concern tehdiplomat raised there turns out not to be specific to that PR. Desktop's on-demand fetcher has never handled rate limiting at all: SwingImageFetcher downloads via ImageIO.read(URL), which discards the HTTP status, so a 429 is indistinguishable from any other failed download and it keeps asking. Mobile got proper 429 handling and a cooldown in 678aae4 back in February, and the scryfallCooldownTime field it uses is declared on the shared ImageFetcher base class — only the mobile half was ever wired up. Desktop also keeps no gap between requests, while GuiDownloadService already keeps 100ms, and fetches go onto a work-stealing pool so a deck editor grid of missing images asks for all of them at once. I've opened #11524 for that; it's independent of this PR.

On the constraint itself, I went looking and found docs/Card-Images.md. It says "you can no longer predownload card images", and three lines later "You can do small pre-caching by loading your decks in the deck editor prior to playing to download just those images." As I read it, commit 5 sits on the second line rather than the first: same deck, same volume, same fetchImage path as opening the deck editor, and gated by the same UI_ENABLE_ONLINE_IMAGE_FETCHER preference that governs passive auto-download everywhere else. What differs is that it triggers itself at match start rather than waiting for you to open the editor. With #11524 in, it also inherits the pacing and the cooldown.

That said, automatic versus user-initiated is your call, not mine — if you'd rather pre-caching stayed something the player asks for, say so and I'll drop commit 5. The measured win in this PR is the rendering work; the fetching commit is the least evidenced part of it.