[UI] Add per-update image transitions and placeholder policies

[NachoSoto]

UIKit callers can now choose a transition and placeholder policy for each image update. This supports appearance-specific artwork that crossfades even on cache hits and keeps the displayed image while its replacement loads, without altering renderer results or cache identity.

imageView.setData(
    newData,
    transition: .crossfade(duration: 0.3),
    placeholderPolicy: .keepCurrentImage
)

The defaults preserve existing .data behavior. .none disables animation; .keepCurrentImage falls back to normal placeholders when no image is displayed. Presentation options travel with each request, and duplicate data does not replace a pending request's options. The SwiftUI loader retains its existing interface and behavior.

Added UIKit behavior tests for cached/uncached animation, immediate updates, placeholder retention/fallback, duplicate requests, stale completions, nil resets, empty results, and deferred sizing.

Validation: all 64 tests passed on iOS 27 Simulator; strict SwiftLint passed. Four compatibility tests also pass unchanged on the pre-PR implementation. They cover renderer preparation order, synchronous source delivery, pending-placeholder suppression, and scheduling without a placeholder.

Consumer: https://github.com/WatchChessApp/watchchessapp/pull/1226

Consumer demonstration

WatchChess light → dark → light using this API, recorded on iOS 27 Simulator and exported at 60 fps:

crossfade-60fps.mp4

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-10T21:42:57.249199Z	21720df	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[NachoSoto]

Reviewed and corrected in 21720df.

The submitted version was not fully equivalent to the old default behavior. The audit found that it constructed the source renderer before the placeholder, added an extra UI-scheduler hop to source results when a placeholder renderer was present, and added beginFromCurrentState to UIKit's transition options. The extra scheduler hop could defer an available source image and show a queued placeholder first.

Restored the original renderer preparation order, source/placeholder scheduling, and exact UIKit animation options. Keeping the current image with a configured placeholder now uses the same empty-placeholder pipeline as the previous app wrapper. Standard updates also avoid the newly introduced read of the displayed image.

Validation:

• Added four compatibility tests using only the old public API and a controlled scheduler.
• All four pass unchanged against the pre-PR implementation (92bd7f1). Its UIKit view and loader are identical to WatchChess's previous pin (6257943).
• Three of those tests failed on the originally submitted PR, reproducing the ordering/timing regressions.
• All four pass after the fix; the full updated suite passes all 64 tests, including cancellation, nil resets, deduplication, deferred sizing, default animation, and the new opt-in policies. Strict SwiftLint passes.

No remaining unintended behavioral difference was found in #94's default paths. The new explicit policies intentionally add behavior; the tests and code comparison are not an exhaustive proof of every possible interleaving.

Separate dependency scope: the app pin also includes already-merged AsyncImageView #92, which gives SwiftUI image replacements an identity so their existing opacity transitions run. That is a separate intentional behavior change from #94, so the whole dependency upgrade should not be described as 100% behavior-equivalent.

[NachoSoto]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 21720df10a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".