[Agent] perf(ui): SwiftUI performance audit — reduce scroll stutter (#3480)

* perf(ui): SwiftUI performance audit — reduce scroll stutter and Realm overhead

* perf(ui): eliminate per-frame re-renders and lazy-collection misuse

- ConsoleGamesView: ForEach now uses Results<PVGame> directly instead
  of .toArray().filter{} — avoids O(n) array allocation every render
- CustomPageIndicator: remove GeometryReader wrapper; use
  .frame(maxWidth:.infinity) instead to avoid per-frame layout pass
- HomeContinueSection: cache PVSaveState footer lookup in @State;
  only refresh on page/focus change, not every body re-render
- HomeView: move scroll offset tracking into a reference-type
  ScrollTracker so previousOffset mutations never trigger HomeView
  body re-evaluation; isSearchBarVisible written only when it changes
- GameItemView: cache discCount (relatedFiles.toArray()) on onAppear
  instead of re-computing on every body evaluation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(ui): address Copilot review — bounded concurrency and search task cleanup

- Cap concurrent Realm reloads to 4 in refreshFromRealmChanges() to
  prevent thread/memory spikes on large libraries
- Apply same bounded concurrency cap to loadAllGames() startup load
- Cancel searchDebounceTask on .onSubmit to avoid redundant post-submit
  query; also cancel on .onDisappear to prevent stale background tasks
- Trigger loadGamesIfNeeded for all systems in TVMediaSystemsView.task
  so systems not yet loaded appear in the grid without depending on the
  lazy-load side effect of shelf rows

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(ui): address Copilot review — scroll perf & state safety

- ConsoleGamesView: use absoluteString for view identity to avoid
  Optional(...) in the .id() string
- TVMediaMainView: build ordered refresh list (selected system first),
  add defer to reset isLoading on cancellation, update stale comment
  in systemsWithGames
- HomeContinueSection: centre indicators without ScrollView when they
  fit; only use ScrollView when pages > maxVisibleIndicators

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: address Copilot review — stable view IDs, ScrollTracker, disc count

- ConsoleGamesView: use trueArtworkURL?.absoluteString instead of
  optional string interpolation (both PVGame call sites)
- TVMediaMainView: task(id:) now uses full system identifiers list,
  not just count, to catch same-count replacements/reorders
- HomeView: drop ObservableObject from ScrollTracker; hold via @State
  to eliminate unused subscription overhead
- GameItemView: add onChange(of: relatedFiles.count) to keep
  cachedDiscCount in sync when files are imported while cell is visible
- changelog: reflect all fixes accurately

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: address Copilot round-3 review — optional URL IDs and actor clarity

- Fix remaining 4 ConsoleGamesView call sites that still used
  \`\(game.trueArtworkURL)\` (Optional interpolation); all cell .id
  modifiers now use \`trueArtworkURL?.absoluteString ?? ""\`
- Clarify thread-safety in loadGamesForSystemAsync: remove redundant
  \`await MainActor.run\` (fn is already @mainactor) and add doc comment
  explaining actor isolation for concurrent TaskGroup callers
- Update changelog to reflect all call sites fixed and actor change

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: address Copilot review — icon reactivity, focus, disc-count dedup

- TVMediaSystemsView: make icon-load task reactive to systemsWithGames
  changes (previously ran once on appear when cache may be empty)
- TVMediaSystemsView: assign focusedSystemID via onChange when first
  systems appear, not only onAppear when list may still be empty
- GameItemView: extract refreshCachedDiscCount() to eliminate duplicated
  disc-count computation between onAppear and onChange handlers

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: use [String] identity for icon-load task to avoid join collisions

.map(\.identifier).joined() can produce the same string for
different identifier arrays (e.g. ["ab","c"] == ["a","bc"]).
[String] is Hashable/Equatable and correctly distinguishes all arrays.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: use defer to reset isLoading on task cancellation

Ensures TVMediaSystemDetailView's loading state resets even when the
.task is cancelled (e.g. view disappears before loadContent finishes).
Consistent with the defer pattern already used in loadAllGames.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: github-actions[bot]

.changelog/3478.md

@@ -0,0 +1,13 @@
+### Fixed
+- **TVMediaMainView scroll performance** — `refreshFromRealmChanges()` now only reloads games for the selected and already-loaded systems (instead of all systems sequentially), reducing Realm queries on each write from O(n) to O(loaded).
+- **TVMediaHomeView startup time** — `loadAllGames()` now loads system game lists concurrently (via `TaskGroup`) instead of one system at a time, speeding up the home shelf render.
+- **Search debounce** — `TVMediaSearchView` now debounces the search text `onChange` by 300ms so Realm is not queried on every keystroke.
+- **Icon-load scroll stutter** — `TVMediaSystemShelfRow` and `TVMediaSystemHeader` no longer hold a shared `@ObservedObject` on `SystemIconLoader`; icon rendering is delegated to a new `TVMediaSystemIconView` that scopes redraws to the icon only, preventing full-shelf invalidation when unrelated system icons load.
+- **Stable view identity in game grids** — `ConsoleGamesView` grid and list cells now use `"\(id)_\(trueArtworkURL)"` as their SwiftUI identity instead of the full model `hashValue`, so only artwork changes force view recreation rather than every Realm write touching playCount/lastPlayed.
+- **ForEach ID stability in recent searches** — `TVMediaSearchView` recent-search chips now use the search string as their ForEach ID instead of array offset, preventing unnecessary redraws on search history reordering.
+- **Live Realm fallback removed from hot path** — `systemsWithGames` computed property no longer calls `system.games.count` (a live Realm query) as a fallback, using only the pre-loaded snapshot cache instead.
+- **Lazy Results in ConsoleGamesView** — `showGamesGrid` and `showGamesList` with `Results<PVGame>` now pass the Realm `Results` directly to `ForEach` instead of calling `.toArray().filter {}` on every render, eliminating full-library array allocation on each scroll frame.
+- **GeometryReader removed from CustomPageIndicator** — page dot indicator no longer wraps its content in a `GeometryReader` to measure container width; replaced with `.frame(maxWidth: .infinity)` centering, removing per-frame layout measurement during paging.
+- **Cached footer save-state lookup** — `HomeContinueSection` now caches the current `PVSaveState` in `@State` and only re-resolves it on page/focus changes, avoiding a live Realm query in every body render.
+- **Scroll frame re-renders eliminated** — `HomeView` scroll-offset tracking moved to a reference-type `ScrollTracker` so that `previousOffset` mutations no longer trigger `HomeView` body re-evaluation on every pixel of scroll; `isSearchBarVisible` is now only written when its value actually changes.
+- **discCount cached in GameItemView** — multi-disc indicator count is computed once on `onAppear` instead of calling `relatedFiles.toArray()` on every body re-render of each visible game cell.

.changelog/3480.md

@@ -0,0 +1,7 @@
+### Changed
+- **SwiftUI scroll performance** — Reduced scroll stutter: all `ConsoleGamesView` cell identities now consistently use `trueArtworkURL?.absoluteString ?? ""` instead of string-interpolating an optional (which produced `Optional(...)` strings and caused spurious view recreation), `TVMediaSystemsView` task identity uses the full system-identifiers list instead of count alone (fixes missed updates on same-count replacements), `TVMediaLibraryModel` ordered refresh prioritises the visible system, all loading task blocks use `defer { isLoading = false }` to guarantee loading state resets on task cancellation, and `CustomPageIndicator` centres indicators without a `ScrollView` when all fit in the viewport.
+- **ScrollTracker** — Removed unnecessary `ObservableObject` conformance; `ScrollTracker` is now a plain reference type held via `@State`, eliminating subscription overhead while keeping the same no-redraw semantics.
+- **Disc indicator** — `GameItemView` now refreshes `cachedDiscCount` via `onChange(of: game.relatedFiles.count)` so the multi-disc badge stays accurate if files are added while the cell is on-screen; disc-count computation extracted into `refreshCachedDiscCount()` to eliminate duplication between `onAppear` and `onChange`.
+- **Actor isolation** — `loadGamesForSystemAsync` is explicitly `@MainActor` with Realm reads isolated in a detached task; mutations to `gamesBySystemIdentifier` are direct assignments on the main actor (no redundant `MainActor.run` wrapper).
+- **Icon loading reactivity** — `TVMediaSystemsView` icon-load task now uses `systemsWithGames` identifiers as its `id` so icons are requested for systems that become visible after the initial load (previously the task ran once on appear when the cache might still be empty).
+- **Initial focus assignment** — `TVMediaSystemsView` now also assigns `focusedSystemID` in `onChange(of: systemsWithGames.count)` so focus is set once the first systems appear, even if the cache was empty during `.onAppear`.

PVUI/Sources/PVSwiftUI/Consoles/ConsoleGamesView.swift

@@ -885,7 +885,7 @@ struct ConsoleGamesView: SwiftUI.View {
                     }
                 }
                 /// Use compound ID so view recreates when artwork URL changes
-                .id("\(game.id)_\(game.trueArtworkURL)")
+                .id("\(game.id)_\(game.trueArtworkURL?.absoluteString ?? "")")
                 .focusableIfAvailable()
                 .contextMenu {
                     GameContextMenu(
@@ -924,8 +924,11 @@ struct ConsoleGamesView: SwiftUI.View {
                 ) {
                     launchGame(md5: model.md5)
                 }
-                /// Use model hash as ID so view recreates when artwork URL changes
-                .id(model.hashValue)
+                /// Recreate the tile only when the artwork URL changes, not on every
+                /// model field update (playCount, lastPlayed, etc.).  Using the full
+                /// model.hashValue caused unnecessary view identity changes and scroll
+                /// stutter on Realm writes.
+                .id("\(model.id)_\(model.trueArtworkURL?.absoluteString ?? "")")
                 .focusableIfAvailable()
                 .contextMenu {
                     if let live = liveGame(for: model) {
@@ -948,44 +951,46 @@ struct ConsoleGamesView: SwiftUI.View {
     private func showGamesGrid(_ games: Results<PVGame>) -> some View {
         ScrollViewReader { proxy in
             LazyVGrid(columns: columns, spacing: 10) {
-                // Custom styling for grid items
-                ForEach(games.toArray().filter { !$0.isInvalidated }, id: \.id) { game in
-                    GameItemView(
-                        game: game,
-                        constrainHeight: false,
-                        viewType: .cell,
-                        sectionContext: .allGames,
-                        isFocused: Binding(
-                            get: {
-                                !game.isInvalidated &&
-                                gamesViewModel.focusedSection == .allGames &&
-                                gamesViewModel.focusedItemInSection == game.id
-                            },
-                            set: {
-                                if $0 && !game.isInvalidated {
-                                    gamesViewModel.focusedSection = .allGames
-                                    gamesViewModel.focusedItemInSection = game.id
+                // Use Results<PVGame> directly (lazy) — avoid .toArray() which materialises all games
+                ForEach(games, id: \.id) { game in
+                    if !game.isInvalidated {
+                        GameItemView(
+                            game: game,
+                            constrainHeight: false,
+                            viewType: .cell,
+                            sectionContext: .allGames,
+                            isFocused: Binding(
+                                get: {
+                                    !game.isInvalidated &&
+                                    gamesViewModel.focusedSection == .allGames &&
+                                    gamesViewModel.focusedItemInSection == game.id
+                                },
+                                set: {
+                                    if $0 && !game.isInvalidated {
+                                        gamesViewModel.focusedSection = .allGames
+                                        gamesViewModel.focusedItemInSection = game.id
+                                    }
                                 }
+                            )
+                        ) {
+                            Task.detached { @MainActor in
+                                SceneCoordinator.shared.launchGame(game.freeze())
                             }
-                        )
-                    ) {
-                        Task.detached { @MainActor in
-                            SceneCoordinator.shared.launchGame(game.freeze())
                         }
-                    }
-                    /// Use compound ID so view recreates when artwork URL changes
-                    .id("\(game.id)_\(game.trueArtworkURL)")
-                    .focusableIfAvailable()
-                    .contextMenu {
-                        GameContextMenu(
-                            game: game,
-                            rootDelegate: rootDelegate,
-                            contextMenuDelegate: self
-                        )
-                    }
+                        /// Use compound ID so view recreates when artwork URL changes
+                        .id("\(game.id)_\(game.trueArtworkURL?.absoluteString ?? "")")
+                        .focusableIfAvailable()
+                        .contextMenu {
+                            GameContextMenu(
+                                game: game,
+                                rootDelegate: rootDelegate,
+                                contextMenuDelegate: self
+                            )
+                        }
 #if !os(tvOS) && !os(watchOS)
-                    .onDrag { game.romDragProvider() }
+                        .onDrag { game.romDragProvider() }
 #endif
+                    }
                 }
             }
         }
@@ -1019,7 +1024,7 @@ struct ConsoleGamesView: SwiftUI.View {
                     }
                 }
                 /// Use compound ID so view recreates when artwork URL changes
-                .id("\(game.id)_\(game.trueArtworkURL)")
+                .id("\(game.id)_\(game.trueArtworkURL?.absoluteString ?? "")")
                 .focusableIfAvailable()
                 .contextMenu {
                     GameContextMenu(
@@ -1060,8 +1065,11 @@ struct ConsoleGamesView: SwiftUI.View {
                 ) {
                     launchGame(md5: model.md5)
                 }
-                /// Use model hash as ID so view recreates when artwork URL changes
-                .id(model.hashValue)
+                /// Recreate the tile only when the artwork URL changes, not on every
+                /// model field update (playCount, lastPlayed, etc.).  Using the full
+                /// model.hashValue caused unnecessary view identity changes and scroll
+                /// stutter on Realm writes.
+                .id("\(model.id)_\(model.trueArtworkURL?.absoluteString ?? "")")
                 .focusableIfAvailable()
                 .contextMenu {
                     if let live = liveGame(for: model) {
@@ -1083,29 +1091,32 @@ struct ConsoleGamesView: SwiftUI.View {
     @ViewBuilder
     private func showGamesList(_ games: Results<PVGame>) -> some View {
         LazyVStack(spacing: 8) {
-            ForEach(games.toArray().filter { !$0.isInvalidated }, id: \.id) { game in
-                GameItemView(
-                    game: game,
-                    constrainHeight: false,
-                    viewType: .row,
-                    sectionContext: .allGames,
-                    isFocused: Binding(
-                        get: {
-                            !game.isInvalidated &&
-                            gamesViewModel.focusedSection == .allGames &&
-                            gamesViewModel.focusedItemInSection == game.id },
-                        set: { if $0 && !game.isInvalidated { gamesViewModel.focusedItemInSection = game.id} }
-                    ))
-                {
-                    loadGame(game)
-                }
-                /// Use compound ID so view recreates when artwork URL changes
-                .id("\(game.id)_\(game.trueArtworkURL)")
-                .focusableIfAvailable()
-                .contextMenu { GameContextMenu(game: game, rootDelegate: rootDelegate, contextMenuDelegate: self) }
+            // Use Results<PVGame> directly (lazy) — avoid .toArray() which materialises all games
+            ForEach(games, id: \.id) { game in
+                if !game.isInvalidated {
+                    GameItemView(
+                        game: game,
+                        constrainHeight: false,
+                        viewType: .row,
+                        sectionContext: .allGames,
+                        isFocused: Binding(
+                            get: {
+                                !game.isInvalidated &&
+                                gamesViewModel.focusedSection == .allGames &&
+                                gamesViewModel.focusedItemInSection == game.id },
+                            set: { if $0 && !game.isInvalidated { gamesViewModel.focusedItemInSection = game.id} }
+                        ))
+                    {
+                        loadGame(game)
+                    }
+                    /// Use compound ID so view recreates when artwork URL changes
+                    .id("\(game.id)_\(game.trueArtworkURL?.absoluteString ?? "")")
+                    .focusableIfAvailable()
+                    .contextMenu { GameContextMenu(game: game, rootDelegate: rootDelegate, contextMenuDelegate: self) }
 #if !os(tvOS) && !os(watchOS)
-                .onDrag { game.romDragProvider() }
+                    .onDrag { game.romDragProvider() }
 #endif
+                }
             }
         }
     }
@@ -1222,8 +1233,7 @@ struct ConsoleGamesView: SwiftUI.View {
                         ) {
                             launchGame(md5: game.md5)
                         }
-                        /// Use model hash as ID so view recreates when artwork URL changes
-                        .id(game.hashValue)
+                        .id("\(game.id)_\(game.trueArtworkURL?.absoluteString ?? "")")
                         .focusableIfAvailable()
                         .contextMenu {
                             if let live = liveGame(for: game) {
@@ -1598,8 +1608,7 @@ extension ConsoleGamesView {
         ) {
             launchGame(md5: game.md5)
         }
-        /// Use model hash as ID so view recreates when artwork URL changes
-        .id(game.hashValue)
+        .id("\(game.id)_\(game.trueArtworkURL?.absoluteString ?? "")")
         .focusableIfAvailable()
         .contextMenu {
             if let live = liveGame(for: game) {