@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-performance/references/demystify-swiftui-performance-wwdc23.md

@@ -1,220 +1,131 @@
-# Demystify SwiftUI Performance (WWDC23) (Summary)
+# Mental Model: Dependencies, Identity and Lifecycle
 
-Context: WWDC23 session on building a mental model for SwiftUI performance and
-triaging hangs, hitches, and excessive update work.
+Notes drawn from the WWDC23 session "Demystify SwiftUI performance". Use them
+to explain why a SwiftUI screen does more work than it should.
 
-## Contents
-- Core mental model
-- Dependencies and invalidation
-- Expensive body work
-- Identity rules for lists and tables
-- Initialization and lifecycle pitfalls
-- Debugging tools
-- Fix patterns
-- What to verify after a change
+## The Model
 
-## Core mental model
+- For each frame, SwiftUI should do only the work the current state requires.
+- A slow screen almost always has one of three problems: each update does too
+  much, updates happen too often, or identity is unstable and work gets thrown
+  away and redone.
+- Work in a loop: measure, find the cause, change one thing, measure again.
+  Always measure again; gains are hard to judge by eye.
 
-SwiftUI performance starts with one rule: only work that is required for the
-current state should happen for the current frame.
+## Dependencies Decide What Updates
 
-A slow screen usually means one of these is false:
+A view is re-evaluated when something it depends on changes. Dependencies come
+from:
 
-- too much work happens per update
-- updates happen too often
-- identity is unstable, so SwiftUI redoes work it could have reused
+- `@State` and `@Binding`
+- `@Observable` models and `@ObservedObject`
+- `@Environment` values
+- identity supplied by containers such as `ForEach`, `List` and `Table`
 
-The session's practical loop is:
+Aim for dependencies that are exact, not just few:
 
-- Measure
-- Identify
-- Optimize
-- Re-measure
+- A row that shows one element should not depend on the whole collection.
+- Values that change quickly (scroll offsets, timers, playback position) should
+  not travel through the environment, where they reach many views.
+- Extract subviews so each one reads a smaller part of the state.
 
-Do not skip the last step. SwiftUI optimizations are easy to misjudge by eye.
+`Self._printChanges()` tells you which property changed, whether a parent
+re-rendered the view, and whether the view reacts to state it does not
+display. It is a debugging aid; do not ship it and do not treat it as a
+profiler.
 
-## Dependencies and invalidation
+## Work That Does Not Belong in `body`
 
-A view updates when one of its dependencies changes.
-
-Common dependency sources:
-
-- `@State`
-- `@Binding`
-- `@Observable` / `@ObservedObject`
-- `@Environment`
-- container-derived identity (`ForEach`, `List`, `Table`)
-
-The performance goal is not "fewer dependencies" in the abstract. The goal is
-**precise dependencies** so only the view that needs to update actually updates.
-
-### Practical implications
-
-- Avoid a row depending on a whole collection if it only needs one element.
-- Avoid broad environment-driven updates for fast-changing values.
-- Extract subviews when a smaller view can read a smaller state surface.
-
-### Debug-only dependency inspection
-
-`Self._printChanges()` is useful in debug builds when you are not sure why a
-view keeps updating.
-
-Use it to answer:
-
-- which property changed?
-- which parent view re-rendered?
-- is the view reacting to state it should not care about?
-
-Do not treat `_printChanges()` output as a shipping-time profiling tool.
-
-## Expensive body work
-
-View bodies need to stay cheap.
-
-Typical mistakes:
-
-- string formatting in `body`
-- array filtering and sorting in `body`
-- expensive image work in `body`
-- constructing large attributed strings during render
-- initializing heavy models in-line with view creation
+Frequent offenders: formatting strings, filtering and sorting, image
+processing, building large attributed strings, and constructing heavy model
+objects inline.
 
 ```swift
-// DON'T
-var body: some View {
-    List(items.filter(shouldShow).sorted(by: sortRule)) { item in
-        Text(numberFormatter.string(from: item.value as NSNumber) ?? "")
-    }
+// Every evaluation filters, sorts and formats each row again.
+List(orders.filter { $0.isOpen }.sorted { $0.date > $1.date }) { order in
+    Text(order.amount.formatted(.currency(code: "EUR")))
 }
 
-// DO
-var body: some View {
-    List(viewModel.visibleItems) { item in
-        Text(item.formattedValue)
-    }
+// The model prepares rows once, when its inputs change.
+List(board.openRows) { row in
+    Text(row.amountText)
 }
 ```
 
-The winning pattern is precomputation at the model boundary, not clever work in
-`body`.
-
-## Identity rules for lists and tables
-
-Identity is one of the biggest hidden performance levers in SwiftUI.
+Do this preparation where data enters the model, not in the view.
 
-### Stable identity matters
+## Identity for Lists and Tables
 
-Use stable IDs that survive refreshes and sorting. If identity churns, SwiftUI
-cannot reuse rows, preserve animations, or diff efficiently.
-
-### Constant row count matters
-
-Inside `ForEach`, SwiftUI expects a predictable mapping between data elements and
-rendered views.
-
-Avoid patterns like:
+- Ids must survive a refresh and a re-sort. When they churn, SwiftUI cannot
+  reuse rows, keep animations or diff efficiently.
+- `ForEach` expects each element to map to a predictable view. Do not wrap rows
+  in `if item.isVisible { ... }`; iterate a collection that is already filtered
+  so every element yields exactly one row.
 
 ```swift
-ForEach(items) { item in
-    if item.isVisible {
-        Row(item: item)
-    }
+ForEach(shelf.visibleBooks) { book in
+    BookRow(book: book)
 }
 ```
 
-Prefer:
+- Keep `AnyView` out of list rows that are rendered often.
+- A `TableRow` resolves to exactly one row. Keep row structure predictable and
+  prefer the simpler `Table` initialisers when they fit.
 
-```swift
-ForEach(visibleItems) { item in
-    Row(item: item)
-}
-```
-
-### Avoid `AnyView` in hot list rows
-
-Type erasure can hide useful structural information and increase work in large
-lists or tables.
-
-### Table-specific note
-
-`TableRow` resolves to a single row. Keep row structure predictable and use the
-streamlined `Table` APIs when possible.
+## Initialisation and Lifecycle
 
-## Initialization and lifecycle pitfalls
-
-### Heavy model creation in view init/body
-
-Keep view initialization lightweight. Start async work with `.task` or from a
-model object.
+Keep `init` cheap; SwiftUI can create view values many times. Start expensive
+or asynchronous work from `.task` or from a model:
 
 ```swift
-// DON'T
-struct DetailView: View {
-    let loader = BigLoader() // heavy construction
-}
-
-// DO
-struct DetailView: View {
-    @State private var model: DetailModel?
+struct InvoiceDetail: View {
+    let invoiceID: Invoice.ID
+    @State private var loader: InvoiceLoader?
 
     var body: some View {
-        content
-            .task {
-                model = await loadDetailModel()
+        Group {
+            if let loader {
+                InvoiceSummary(loader: loader)
+            } else {
+                ProgressView()
             }
+        }
+        .task(id: invoiceID) {
+            loader = await InvoiceLoader.prepare(for: invoiceID)
+        }
     }
 }
 ```
 
-### Hidden work from computed properties
-
-A computed property can still be body work if it runs during render. If it is
-expensive, treat it like body work and precompute it.
-
-## Debugging tools
-
-### Instruments
-
-Use Instruments for hangs, hitches, update counts, and expensive frames.
-
-### `_printChanges()`
-
-Use it in debug to inspect dependency behavior.
-
-### Release-build validation
-
-A debug build can make SwiftUI performance look worse or different than a
-shipping build. Validate important performance changes in Release on device.
-
-## Fix patterns
-
-### Split views by dependency boundary
-
-If one small piece of state changes frequently, isolate the subview that reads
-it.
-
-### Pre-filter and cache collections
+The version to avoid stores `let loader = InvoiceLoader(id:)` as a property, so
+the loader is rebuilt every time the parent creates the view.
 
-Do filtering, mapping, sorting, and grouping before rendering.
+An expensive computed property read during rendering counts as body work too.
+Compute it ahead of time.
 
-### Avoid broad environment reads in hot paths
+## Tools
 
-Environment is convenient but not free. Keep fast-changing values local unless
-multiple subtrees truly need them.
+Instruments shows hangs, hitches, update counts and expensive frames. Confirm
+findings in a Release build on a device; a Debug build can look worse, or just
+different.
 
-### Reduce hidden allocations
+## Fix Patterns
 
-Move formatters, bundle lookups, and derived strings out of repeated body paths.
+- Split views along dependency boundaries.
+- Filter, map, sort and group before rendering.
+- Keep reads of broad environment values out of hot paths; keep values that
+  change quickly local.
+- Move formatters, bundle lookups and derived strings out of code that runs on
+  every update.
 
-## What to verify after a change
+## Checking a Fix
 
-After optimizing, check all of the following:
+After a change, check that:
 
-- the target interaction feels smoother
-- update counts dropped in Instruments
-- row identity stayed stable across reloads
-- animation behavior still matches product intent
-- no correctness bugs were introduced by caching or splitting views
+- the interaction is visibly smoother,
+- update counts went down,
+- row identity stays the same across reloads,
+- animations still do what was intended,
+- caching or splitting did not introduce a correctness bug.
 
-A performance fix that breaks state ownership or animation correctness is not a
-real fix.
+A change that breaks state ownership or animation is not a fix.

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

@@ -1,234 +1,128 @@
-# Optimizing SwiftUI Performance with Instruments (Summary)
+# Profiling with the SwiftUI Instrument
 
-Context: WWDC session introducing the SwiftUI Instrument in Instruments 26 and
-how to diagnose SwiftUI-specific bottlenecks.
+Based on the WWDC25 session "Optimize SwiftUI performance with Instruments".
+The SwiftUI Instrument described here ships with Instruments 26.
 
-## 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
+## When It Is the Right Tool
 
-## When to use the SwiftUI Instrument
+Reach for it when the symptom points at view updates, layout, rendering or
+state spreading too far:
 
-Use the SwiftUI Instrument when the symptom is clearly tied to view updates,
-layout, rendering, or state fan-out.
+- scrolling stutters,
+- a push to a new screen pauses first,
+- an animation is uneven although nothing obviously blocks the main thread,
+- a timer or observable model triggers far more updates than expected.
 
-Good fits:
+When the whole app freezes and nothing points at the UI, start with Hangs or
+Time Profiler and come to the SwiftUI lanes afterwards.
 
-- 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
+## Capture Setup
 
-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.
+- Release build on a real device.
+- A sequence you can repeat exactly.
+- As little debug logging as possible.
+- Enough repetitions that a pattern shows.
 
-## Recommended capture setup
+A good default set: the SwiftUI Instrument plus Time Profiler, and Hangs or
+Animation Hitches when the symptom calls for it.
 
-Profile with the same assumptions you use for shipping code:
+## The SwiftUI Lanes
 
-- Release build
-- real device
-- reproducible interaction sequence
-- minimal debug logging
-- enough repetitions to show a pattern, not a one-off spike
+| Lane | What it tells you |
+|------|-------------------|
+| Update Groups | Coarse buckets of work. Shows bursts even when no single update is slow. |
+| Long View Body Updates | `body` evaluations that took too long. Orange is worth a look, red is clearly too slow. |
+| Long Platform View Updates | Time in hosted UIKit or AppKit views: `UIViewRepresentable`, `UIViewControllerRepresentable`, heavy list or table bridging, embedded media or web views. |
+| Other Long Updates | Text layout, geometry, list diffing and update coordination. |
 
-A good baseline template is:
+## Workflow: One Update Is Too Slow
 
-- 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`
+1. Pick a single red or orange update, not a long stretch of timeline.
+2. Set the inspection range to that update so Time Profiler shows the same
+   interval.
+3. Read the call tree or flame graph. Typical findings: a formatter being
+   created, sorting or filtering, image decoding, string building, model
+   construction, a synchronous read from storage.
+4. Move that work out of `body`:
 
 ```swift
-// DON'T
-var body: some View {
-    Text(items.sorted(by: \.date).map(\.title).joined(separator: ", "))
-}
+// Before: runs on every evaluation.
+Text(playlist.tracks.sorted { $0.position < $1.position }
+    .map(\.title).joined(separator: ", "))
 
-// DO
-var body: some View {
-    Text(viewModel.joinedTitles)
-}
+// After: the model keeps the joined string current.
+Text(playlist.trackSummary)
 ```
 
-### 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.
+5. Record again. If long updates remain, the work probably moved into a child
+   view or reaches the view through another dependency.
 
-## Workflow for frequent updates
+## Workflow: Too Many Updates
 
-Some screens feel slow because updates happen too often, not because any one
-update is catastrophic.
+A screen can feel slow because it updates constantly, even if every single
+update is cheap.
 
-### 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
+- Start with Update Groups: look for long active stretches full of updates with
+  no red spikes.
+- Look at counts, not only durations. Cheap work done 200 times can feel worse
+  than one moderately expensive update.
+- Open the Cause and Effect Graph to see what changed, which dependency fired
+  and why the update spread.
 
 Typical fixes:
+- extract subviews that read only the state they show,
+- replace a broad shared model with narrower derived state,
+- stop passing fast-changing data through the environment,
+- split a large `@Observable` model whose unrelated properties change together.
 
-- 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
+## Cause and Effect Graph
 
-### Formatter allocation
+Use it when backtraces point in the wrong direction; in a declarative UI the
+code that did the work is often far from the code that caused it. Good uses:
 
-Avoid constructing `DateFormatter`, `NumberFormatter`, or `MeasurementFormatter`
-in `body` or per-row views.
+- changing the selection also updates an unrelated sidebar,
+- a timer invalidates an entire list,
+- a geometry change ripples through many subviews,
+- a global favourites model makes every row re-evaluate.
 
-### Filtering or sorting in the view tree
+## Hot Spots and How to Fix Them
 
-Precompute filtered collections before render.
+- Never build `DateFormatter`, `NumberFormatter` or `MeasurementFormatter` in
+  `body` or per row.
+- Filter collections before rendering; do not route raw geometry through a
+  broadly observed model.
+- Unstable identity and a row count that changes between passes make lists
+  and tables expensive.
+- Check representables for configuration repeated on every
+  `updateUIView` or `updateUIViewController` call.
 
-### 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
+Cache presentation values in a model:
 
 ```swift
 @Observable
-final class TripPresentationModel {
-    var formattedDistance: String = ""
+final class RunSummary {
+    private(set) var distanceText = ""
 
-    func update(distance: Measurement<UnitLength>, formatter: MeasurementFormatter) {
-        formattedDistance = formatter.string(from: distance)
+    func update(metres: Double, using formatter: MeasurementFormatter) {
+        let distance = Measurement<UnitLength>(value: metres, unit: .meters)
+        distanceText = 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
+- Scope observable dependencies so a row reads only its own state.
+- Make representable updates idempotent: touch the hosted view only when an
+  input actually changed.
+- Tame noisy geometry or timer signals with a threshold, debouncing or
+  coalescing.
 
-After every change:
+## Measuring Again
 
-- 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
+- Record the same flow again.
+- Compare how many updates happen, not only how long they take.
+- Confirm there are fewer hitches.
+- Confirm no new Long Platform View Updates appeared.
+- Check in Release on a 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.
+If one screen gets faster while updates rise somewhere else, keep following the
+dependency graph until the fan-out really goes down.