Notes/GameView.md (8088B)
1# Per-keystroke hitches on populated databases
2
3## Symptom
4
5Solving a puzzle on iPhone 14 Pro Max produces visible hitches as letters
6appear in the grid. The same build on a freshly-set-up iPhone 13 Mini (new
7Apple Account, empty store) is smooth. Disabling iCloud sync in Settings does
8not help. Disabling ProMotion (removing `CADisableMinimumFrameDurationOnPhone`
9from `Info.plist`) does not help. Running "Reset Database" from the
10diagnostics screen restores responsiveness immediately.
11
12The shared property of the three things that *did* affect responsiveness
13(brand-new account, reset database) is **how much data the local Core Data
14store contains**, not network or display behaviour.
15
16## Diagnosis
17
18Per-keystroke trace:
19
201. The user types a letter. `GameMutator.setLetter` updates the in-memory
21 `Game` and calls `emitMove`, which schedules
22 `MoveBuffer.enqueue(...)` on the `MoveBuffer` actor.
232. If the new edit targets a different cell than the previous one,
24 `enqueue` triggers `performFlush()` for Lamport ordering.
253. `performFlush` calls `persistAndAssignLamports`, which on a background
26 context inserts a `MoveEntity`, updates the `GameEntity`
27 (`lamportHighWater`, `updatedAt`), updates a `CellEntity`, and saves.
284. `viewContext.automaticallyMergesChangesFromParent = true`
29 (`PersistenceController.swift:39`) merges the background save into the
30 main context.
315. `GameListView` declares
32 `@FetchRequest<GameEntity>(sortDescriptors: [], animation: .default)`
33 (`GameListView.swift:11-15`). The merge invalidates the fetch request,
34 which marks `GameListView` dirty.
356. SwiftUI recomputes `GameListView.body`. The body reads two computed
36 properties:
37
38 ```swift
39 private var inProgress: [GameSummary] {
40 games.compactMap(GameSummary.init(entity:))
41 .filter { $0.completedAt == nil }
42 .sorted { ... }
43 }
44 private var completed: [GameSummary] {
45 games.compactMap(GameSummary.init(entity:))
46 .filter { $0.completedAt != nil }
47 .sorted { ... }
48 }
49 ```
50
51 Each calls `games.compactMap(GameSummary.init(entity:))` independently.
527. `GameSummary.init(entity:)` (`GameStore.swift:34-77`) calls
53 `XD.parse(source)`, constructs a full `Puzzle`, and walks every
54 `CellEntity` to build the thumbnail array.
55
56So per keystroke, on the main thread:
57
58```
59GameCount × 2 × (XD.parse + Puzzle init + thumbnail build)
60```
61
62With one game in the store the cost is invisible. With many games it is
63proportional to library size and lands on every cell-change keystroke.
64
65## Why this matches every observation
66
67- **Empty DB after reset → fast.** The `@FetchRequest` returns nothing, so
68 the body has no per-game work to do.
69- **iCloud disabled didn't help.** The work is local: a Core Data save in
70 the view context is enough to invalidate the fetch request. Network
71 state is irrelevant.
72- **ProMotion disabled didn't help.** The cost is real and on the main
73 thread. Capping the refresh rate only changes whether the dropped frame
74 is visible, not whether the work happens.
75- **iPhone 13 Mini (new account) was fast.** Same code, but the library was
76 empty, so the FetchRequest had nothing to iterate.
77- **Got worse over time.** Every game added to the library multiplies the
78 per-keystroke cost.
79
80## Why `GameListView` is involved while `PuzzleView` is on screen
81
82`NavigationStack` does **not** unmount the root view when a destination is
83pushed; it only covers it visually. The root remains in the view hierarchy,
84its property wrappers stay live, and SwiftUI continues to invalidate and
85re-evaluate its body whenever a tracked dependency changes. `@FetchRequest`
86is a Core Data observer; it fires on context changes regardless of whether
87the view that owns it is currently visible. SwiftUI does not skip body
88evaluation for "covered" views, because visibility is a render-tree concept
89while body evaluation is a data-graph concept — it has to compute the new
90body to know whether anything visible changed (toolbar, title, navigation
91state, transitions, etc.).
92
93`animation: .default` on the fetch request also wraps each invalidation in
94an animation transaction, which can amplify the perceived hitch.
95
96## Secondary issue (not the root cause of the hitch)
97
98`MoveEntity` rows are only pruned after CloudKit confirms the snapshot save.
99`AppServices.swift:71` wraps the entire `afterFlush` callback in
100`guard isEnabled` — meaning that with iCloud sync disabled, snapshots are
101never created and moves are never pruned. The move table grows unbounded.
102This is not what is producing the per-keystroke hitch (the dominant cost is
103the FetchRequest + `XD.parse`), but it is a real correctness/space concern
104worth fixing separately so users running with sync off don't accumulate
105forever.
106
107## Verification
108
109Drop a one-line probe at the top of `GameListView.body`:
110
111```swift
112let _ = print("GameListView body")
113```
114
115Run a build against the populated database. If the print fires on every
116cell-change keystroke, the diagnosis is correct.
117
118## Fixes
119
120### Recommended: gate `@FetchRequest` on visibility
121
122Stop doing the work entirely while the puzzle is on screen. The
123`@FetchRequest` only observes Core Data because the view that owns it is
124live. Removing the owning view from the hierarchy tears down the underlying
125`NSFetchedResultsController`. `NavigationStack` fires `.onDisappear` on the
126root when a destination is pushed, which is the signal we need.
127
128```swift
129struct GameListView: View {
130 let store: GameStore
131 let shareController: ShareController
132 @Binding var navigationPath: NavigationPath
133
134 @State private var isActive = true
135
136 var body: some View {
137 Group {
138 if isActive {
139 GameListContent(
140 store: store,
141 shareController: shareController,
142 navigationPath: $navigationPath
143 )
144 } else {
145 Color.clear
146 }
147 }
148 .onAppear { isActive = true }
149 .onDisappear { isActive = false }
150 }
151}
152
153private struct GameListContent: View {
154 // current GameListView body, including:
155 @FetchRequest(sortDescriptors: [], animation: .default)
156 private var games: FetchedResults<GameEntity>
157 // ...
158}
159```
160
161Push `PuzzleView` → `.onDisappear` → `isActive = false` →
162`GameListContent` is removed → `@FetchRequest` is torn down → keystrokes no
163longer have a SwiftUI subscriber to invalidate. Pop back → `.onAppear` →
164`isActive = true` → fresh fetch, list reflects whatever changed.
165
166Caveats:
167
1681. `.onDisappear` also fires when a sheet covers the list (`NewGameSheet`,
169 `SettingsView`). That's fine — list is not visible then either — but
170 quick sheet dismissals will flap `isActive`. If that becomes a problem,
171 gate on debounce or on `navigationPath.count > 0` instead.
1722. The first frame after popping back has to fetch and build summaries.
173 For a small-to-moderate library this should be imperceptible; if it
174 isn't, render a cached lightweight snapshot in the inactive branch.
1753. This addresses the "while typing" case only. Opening the library on a
176 populated database still triggers the same `XD.parse`-per-game work
177 during scrolling and resizing. If that becomes a problem, the longer-
178 term fix is to cache derived summary fields (title, publisher, date,
179 gridWidth, gridHeight, blockMask) directly on `GameEntity` so the list
180 path never parses XD.
181
182### Alternative: cache derived puzzle data on `GameEntity`
183
184Pre-compute and store everything `GameSummary` needs (title, publisher,
185date, width, height, block mask) on `GameEntity` at creation time. `XD.parse`
186disappears from the hot path entirely. This is a bigger change (schema +
187migration + initialisation) but fixes both the "while typing" case and the
188"opening a populated library" case.
189
190### Cheap partial: deduplicate the iteration
191
192`inProgress` and `completed` both iterate `games.compactMap(...)`. Compute
193the summaries once per body and partition. Halves the constant but stays
194O(games) per keystroke; not a real fix.