@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/swiftui-performance/references/optimizing-swiftui-performance-instruments.md

@@ -1,29 +1,234 @@
 # Optimizing SwiftUI Performance with Instruments (Summary)
 
-Context: WWDC session introducing the next-generation SwiftUI Instrument in Instruments 26 and how to diagnose SwiftUI-specific bottlenecks.
+Context: WWDC session introducing the SwiftUI Instrument in Instruments 26 and
+how to diagnose SwiftUI-specific bottlenecks.
 
-## Key takeaways
+## Contents
+- When to use the SwiftUI Instrument
+- Recommended capture setup
+- Reading the SwiftUI timeline
+- Workflow for long view body updates
+- Workflow for frequent updates
+- Cause and Effect Graph usage
+- Common hotspots
+- Fix patterns
+- Re-measure checklist
 
-- Profile SwiftUI issues with the SwiftUI template (SwiftUI instrument + Time Profiler + Hangs/Hitches).
-- Long view body updates are a common bottleneck; use "Long View Body Updates" to identify slow bodies.
-- Set inspection range on a long update and correlate with Time Profiler to find expensive frames.
-- Keep work out of `body`: move formatting, sorting, image decoding, and other expensive work into cached or precomputed paths.
-- Use Cause & Effect Graph to diagnose *why* updates occur; SwiftUI is declarative, so backtraces are often unhelpful.
-- Avoid broad dependencies that trigger many updates (e.g., `@Observable` arrays or global environment reads).
-- Prefer granular view models and scoped state so only the affected view updates.
-- Environment values update checks still cost time; avoid placing fast-changing values (timers, geometry) in environment.
-- Profile early and often during feature development to catch regressions.
+## When to use the SwiftUI Instrument
 
-## Suggested workflow (condensed)
+Use the SwiftUI Instrument when the symptom is clearly tied to view updates,
+layout, rendering, or state fan-out.
 
-1. Record a trace in Release mode using the SwiftUI template.
-2. Inspect "Long View Body Updates" and "Other Long Updates."
-3. Zoom into a long update, then inspect Time Profiler for hot frames.
-4. Fix slow body work by moving heavy logic into precomputed/cache paths.
-5. Use Cause & Effect Graph to identify unintended update fan-out.
-6. Re-record and compare the update counts and hitch frequency.
+Good fits:
 
-## Example patterns from the session
+- scrolling stutters in a SwiftUI-heavy screen
+- pushing a destination causes a pause during view construction
+- an animation feels inconsistent even without obvious main-thread blocking
+- a timer or observable object causes too many updates
 
-- Caching formatted distance strings in a location manager instead of computing in `body`.
-- Replacing a dependency on a global favorites array with per-item view models to reduce update fan-out.
+If the symptom is a broad app freeze with no clear UI source, start with Hangs
+or Time Profiler first, then move to SwiftUI-specific tools.
+
+## Recommended capture setup
+
+Profile with the same assumptions you use for shipping code:
+
+- Release build
+- real device
+- reproducible interaction sequence
+- minimal debug logging
+- enough repetitions to show a pattern, not a one-off spike
+
+A good baseline template is:
+
+- SwiftUI Instrument
+- Time Profiler
+- Hangs or Animation Hitches when relevant
+
+## Reading the SwiftUI timeline
+
+Key lanes to understand:
+
+### Update Groups
+
+High-level buckets of SwiftUI work over time. Useful for spotting bursts of
+activity even when no single update is individually slow.
+
+### Long View Body Updates
+
+Use this lane when a view `body` itself is expensive.
+
+Interpretation:
+
+- orange indicates notable cost
+- red indicates clearly too-slow view updates
+
+### Long Platform View Updates
+
+This usually points to UIKit/AppKit work hosted inside SwiftUI, including:
+
+- `UIViewRepresentable`
+- `UIViewControllerRepresentable`
+- heavy `List`/table bridging
+- embedded media or web views
+
+### Other Long Updates
+
+Catches expensive work outside pure body computation, such as:
+
+- text layout
+- geometry
+- list diffing
+- update coordination
+
+## Workflow for long view body updates
+
+### 1. Find a red or orange update
+
+Start with one obviously expensive update rather than a long trace window.
+
+### 2. Set inspection range
+
+Select the update window so Time Profiler aligns with the same time slice.
+
+### 3. Inspect the call tree or flame graph
+
+Look for work that should not be happening during body evaluation.
+
+Common surprises:
+
+- formatter allocation
+- sorting or filtering collections
+- image decoding
+- string building
+- model initialization
+- synchronous persistence reads
+
+### 4. Move heavy work out of `body`
+
+```swift
+// DON'T
+var body: some View {
+    Text(items.sorted(by: \.date).map(\.title).joined(separator: ", "))
+}
+
+// DO
+var body: some View {
+    Text(viewModel.joinedTitles)
+}
+```
+
+### 5. Re-record the same flow
+
+If the trace still shows long view body updates, the expensive work likely just
+moved into a child view or another dependency path.
+
+## Workflow for frequent updates
+
+Some screens feel slow because updates happen too often, not because any one
+update is catastrophic.
+
+### 1. Use Update Groups first
+
+Look for long active ranges with many updates but no large red spikes.
+
+### 2. Inspect counts, not just duration
+
+A screen doing cheap work 200 times can still feel worse than one doing one
+moderately expensive update.
+
+### 3. Open Cause and Effect Graph
+
+This is often the fastest way to answer:
+
+- what changed?
+- which dependency triggered the update?
+- why did that change fan out to unrelated views?
+
+### 4. Narrow the dependency scope
+
+Typical fixes:
+
+- extract subviews so they only read the state they need
+- replace broad shared models with narrower derived state
+- avoid environment values for fast-changing data
+- split large `@Observable` models if unrelated properties change together
+
+## Cause and Effect Graph usage
+
+Use it when backtraces are misleading.
+
+SwiftUI is declarative, so the expensive work may not appear near the code that
+caused the update chain.
+
+Good uses:
+
+- a selection change updates an unrelated sidebar
+- a timer invalidates a full list
+- geometry updates ripple through many subviews
+- a global favorites model causes every row to re-evaluate
+
+## Common hotspots
+
+### Formatter allocation
+
+Avoid constructing `DateFormatter`, `NumberFormatter`, or `MeasurementFormatter`
+in `body` or per-row views.
+
+### Filtering or sorting in the view tree
+
+Precompute filtered collections before render.
+
+### Geometry-driven layout churn
+
+Avoid feeding raw geometry values through broad observable state.
+
+### Identity instability
+
+Lists and tables get expensive when identity changes or row counts vary in ways
+SwiftUI cannot efficiently diff.
+
+### Platform view bridging
+
+Audit representables for repeated configuration work in `updateUIView` or
+`updateUIViewController`.
+
+## Fix patterns
+
+### Cache presentation data
+
+```swift
+@Observable
+final class TripPresentationModel {
+    var formattedDistance: String = ""
+
+    func update(distance: Measurement<UnitLength>, formatter: MeasurementFormatter) {
+        formattedDistance = formatter.string(from: distance)
+    }
+}
+```
+
+### Scope observable dependencies
+
+Prefer models where a row reads only row-local state.
+
+### Keep representable updates idempotent
+
+Only mutate the hosted platform view when input values actually changed.
+
+### Gate noisy signals
+
+A geometry or timer signal may need thresholding, debouncing, or coalescing.
+
+## Re-measure checklist
+
+After every change:
+
+- record the same flow again
+- compare update count, not just total runtime
+- verify hitch frequency went down
+- verify no new Long Platform View Updates appeared
+- verify behavior in Release on device
+
+If a change makes one screen faster but causes more updates elsewhere, keep
+following the dependency graph until the fan-out is truly reduced.

package/pipeline/skills/shared/external/swiftui-performance/references/understanding-hangs-in-your-app.md

@@ -1,33 +1,233 @@
 # Understanding Hangs in Your App (Summary)
 
-Context: Apple guidance on identifying hangs caused by long-running main-thread work and understanding the main run loop.
+Context: Apple guidance on identifying hangs caused by long-running main-thread
+work and understanding the main run loop.
 
-## Key concepts
+## Contents
+- What a hang is
+- Main-thread work stages
+- Triage workflow
+- Common root causes
+- Fix patterns
+- Verification checklist
+- Related SwiftUI implications
 
-- A hang is a noticeable delay in a discrete interaction (typically >100 ms).
-- Hangs almost always come from long-running work on the main thread.
-- The main run loop processes UI events, timers, and main-queue work sequentially.
+## What a hang is
+
+A hang is a noticeable delay in a discrete interaction. Apple commonly frames
+this as main-thread busy time long enough for the user to feel the UI stop
+responding.
+
+Practical thresholds:
+
+- Under ~100 ms usually feels immediate.
+- Around 100-250 ms starts to feel sticky.
+- Above ~250 ms is a likely hang candidate.
+- Multi-second stalls are usually obvious product bugs, not subtle perf issues.
+
+The important point is not the exact number. A hang is user-perceived blocked
+interaction, and the main thread is usually where the problem lives.
 
 ## Main-thread work stages
 
-- Event delivery to the correct view/handler.
-- Your code: state updates, data fetch, UI changes.
-- Core Animation commit to the render server.
+A typical interaction flows through three stages on the main thread:
+
+1. Event delivery to the target view or responder
+2. Your code mutating state, computing values, and scheduling UI changes
+3. Core Animation committing the frame tree to the render server
+
+If any one of those stages runs too long, the main run loop cannot get back to
+sleep and cannot service the next event in time.
+
+## Main run loop model
+
+The main run loop is a good mental model for hangs:
+
+- Healthy apps spend most of their time idle, waiting for work.
+- A busy run loop means new taps, gestures, timers, and redraw work queue up.
+- Main-actor tasks still execute on the main thread. Moving code to `@MainActor`
+  is a correctness tool, not a performance optimization.
+
+If the UI is stalled, assume the main thread is overloaded until profiling
+proves otherwise.
+
+## Triage workflow
+
+### 1. Reproduce a single concrete interaction
+
+Start with one specific symptom:
+
+- tapping a button does nothing for half a second
+- pushing a detail screen pauses before animating
+- dismissing a sheet freezes scrolling underneath
+
+Avoid broad goals like "the app feels slow" until you isolate a single path.
+
+### 2. Record with Instruments
+
+Use the Hangs instrument, and pair it with Time Profiler when needed.
+
+Good capture setup:
+
+- Release build
+- real device
+- repeatable interaction path
+- enough repetitions to confirm the same stall pattern
+
+### 3. Inspect busy windows on the main thread
+
+Look for long busy periods instead of staring at total CPU first.
+
+Questions to answer:
+
+- Is the main thread blocked in app code?
+- Is it blocked in synchronous I/O?
+- Is it repeatedly recalculating layout or view state?
+- Is there a lock or actor hop forcing serialization?
+
+### 4. Reduce the work, not just the symptom
+
+A useful fix removes or re-locates expensive work. A weak fix only hides the
+stall behind a spinner while the main thread still does too much.
+
+## Common root causes
+
+### Synchronous I/O on the main thread
+
+Typical offenders:
+
+- file reads
+- JSON decoding for large payloads
+- image decoding
+- database fetches
+- Keychain work done inline with UI gestures
+
+```swift
+// DON'T
+Button("Open") {
+    let data = try? Data(contentsOf: fileURL)
+    model = parse(data)
+}
+
+// DO
+Button("Open") {
+    Task {
+        let data = try await loadFileData()
+        let parsed = try await parseModel(from: data)
+        await MainActor.run { model = parsed }
+    }
+}
+```
+
+### Heavy work in event handlers
+
+A tap handler should kick off work, not do all the work inline.
+
+```swift
+// DON'T
+func didTapRefresh() {
+    items = expensiveRebuildOfEntireList()
+}
+
+// DO
+func didTapRefresh() {
+    Task {
+        let rebuilt = await rebuildList()
+        await MainActor.run { items = rebuilt }
+    }
+}
+```
+
+### Main-thread contention from layout or rendering
+
+SwiftUI and UIKit/AppKit can both stall if the view tree triggers too much work
+per interaction.
+
+Watch for:
+
+- repeated formatter creation
+- image resizing in `body`
+- expensive attributed string generation during scroll
+- layout invalidations triggered by frequent geometry changes
+
+### Locking and serialization
+
+A hang may show up as main-thread waiting, not main-thread computing.
+
+Examples:
+
+- a lock held by background work
+- synchronous dispatch back to main
+- a main-actor method waiting on another main-actor path
+
+### Priority inversion
+
+If high-priority UI work is waiting on lower-priority work that holds a needed
+resource, the UI still feels hung even if the main thread stack looks shallow.
+
+## Fix patterns
+
+### Keep main-thread work small and deterministic
+
+Prefer this split:
+
+- main thread: input, state wiring, view invalidation
+- background work: parsing, formatting batches, image prep, persistence
+- main thread again: commit the final result
+
+### Precompute instead of recompute
+
+```swift
+// DON'T
+Text(distanceFormatter.string(from: trip.distance))
+
+// DO
+Text(trip.formattedDistance)
+```
+
+If the value changes rarely, compute it at the model boundary.
+
+### Stream results instead of blocking for all results
+
+When practical, render partial state first and append or replace as work
+finishes.
+
+### Cancel stale work aggressively
+
+A common hang pattern is doing unnecessary work for content the user already
+navigated away from.
+
+```swift
+.task(id: searchQuery) {
+    results = []
+    results = await search(query: searchQuery)
+}
+```
+
+Pair this with cancellation inside the async work.
+
+## Verification checklist
+
+After a fix, confirm all of the following:
 
-## Why the main run loop matters
+- the same interaction no longer triggers a Hangs event
+- main-thread busy windows are shorter
+- the fix works in Release on device
+- repeated interaction does not regress frame pacing
+- cancellation works when navigating away mid-task
 
-- Only the main thread can update UI safely.
-- The run loop is the foundation that executes main-queue work.
-- If the run loop is busy, it can't handle new events; this causes hangs.
+If the hang disappears but scrolling or animation gets worse elsewhere, the
+work likely just moved rather than improved.
 
-## Diagnosing hangs
+## Related SwiftUI implications
 
-- Observe the main run loop's busy periods: healthy loops sleep most of the time.
-- Hang detection typically flags busy periods >250 ms.
-- The Hangs instrument can be configured to lower thresholds.
+SwiftUI-specific hangs often come from:
 
-## Practical takeaways
+- long view body updates
+- broad observable dependencies
+- list identity churn
+- hidden work in formatting or filtering
 
-- Keep main-thread work short; offload heavy work from event handlers.
-- Avoid long-running tasks on the main dispatch queue or main actor.
-- Use run loop behavior as a proxy for user-perceived responsiveness.
+Use the SwiftUI Instrument when the symptom is tied to view updates or layout.
+Use the Hangs instrument when the symptom is broad UI unresponsiveness and you
+first need to confirm the main thread is blocked.