swiftui-performance

# SwiftUI Performance

Audit SwiftUI view performance from a reproducible symptom to measured
remediation. Route animation design to `swiftui-animation`, production telemetry
to `metrickit`, ownership/leak analysis to `ios-memgraph-analysis`, navigation
behavior to `swiftui-navigation`, state architecture to `swiftui-patterns`, and
layout construction to `swiftui-layout-components`.

## Contents

- [Workflow Decision Tree](#workflow-decision-tree)
- [1. Code-First Review](#1-code-first-review)
- [2. Guide the User to Profile](#2-guide-the-user-to-profile)
- [3. Analyze and Diagnose](#3-analyze-and-diagnose)
- [4. Remediate](#4-remediate)
- [Common Code Smells (and Fixes)](#common-code-smells-and-fixes)
- [5. Verify](#5-verify)
- [Outputs](#outputs)
- [Instruments Profiling](#instruments-profiling)
- [Identity and Lifetime](#identity-and-lifetime)
- [Lazy Loading Patterns](#lazy-loading-patterns)
- [State and Observation Optimization](#state-and-observation-optimization)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Workflow Decision Tree

- Code supplied: review it first and label findings as hypotheses.
- Symptoms only: collect the smallest relevant view, data flow, reproduction,
  device, OS, and build configuration.
- Inconclusive review: collect a trace or lane screenshots before prescribing a
  broad refactor.

Use this triage list for both code and trace analysis:

- Broad state dependencies or invalidation storms
- Unstable list identity or root conditional swapping
- Formatting, sorting, decoding, or synchronous I/O in `body`
- Layout/geometry feedback loops and oversized images
- Implicit animation applied to a large hierarchy

## 1. Code-First Review

Map each suspect from the triage list to exact code. Report likely causes with
code references, but label them code-backed hypotheses until a trace confirms
cost. Propose a minimal repro or measurement when evidence is missing.

## 2. Guide the User to Profile

Use the SwiftUI Instruments template on a **Release build** and real device when
possible. Reproduce the exact interaction, capturing SwiftUI lanes, Time
Profiler, and Hangs/Hitches as relevant. Ask for the trace or screenshots of the
lanes and call tree.

## 3. Analyze and Diagnose

Apply the same triage list to trace evidence. Correlate long or frequent SwiftUI
updates with the Time Profiler call tree and the reproduced interaction. Separate
trace-backed findings from code-backed hypotheses and name the next measurement
that would resolve remaining uncertainty.

## 4. Remediate

Apply targeted fixes:
- Narrow state scope (`@State`/`@Observable` closer to leaf views).
- Stabilize identities for `ForEach` and lists.
- Move heavy work out of `body` into model-layer precomputation, an explicit derived
  value updated when its inputs change, a memoized helper, or background processing.
  Use `@State` only when the view owns both the value and its update lifecycle; it is
  not a generic cache for arbitrary computation.
- Use `equatable()` only when equality is cheaper than recomputing the subtree and
  the compared inputs have stable value semantics.
- Downsample images before rendering.
- Reduce layout complexity or use fixed sizing where possible.

## Common Code Smells (and Fixes)

| Smell | Evidence to seek | Targeted fix |
|---|---|---|
| Formatter, sort, filter, or decode in `body` | Long/frequent body updates with matching call-tree cost | Recompute when inputs change; downsample/decode off the main actor |
| `UUID()` or unstable `id: \.self` | Recreated rows, lost state, excess updates | Use stable model identity |
| Root `if`/`else` swaps | State reset or update spikes when toggled | Localize conditional content/modifiers when semantics allow |
| Broad model reads | Many unrelated views update together | Pass narrow values or move reads into focused child views |
| Geometry writes during layout | Repeating layout/update cycle | Threshold changes or replace the feedback path with stable layout |

## 5. Verify

Ask the user to re-run the same capture and compare with baseline metrics.
Summarize the delta (CPU, frame drops, memory peak) if provided.

## Outputs

Provide:
- A short metrics table (before/after if available).
- Top issues (ordered by impact).
- Proposed fixes with estimated effort.

## Instruments Profiling

Use the **SwiftUI template** in Instruments (Cmd+I to profile). Current SwiftUI lanes include Update Groups, Long View Body Updates, Long Representable Updates / Representable Updates, Other Long Updates / Other Updates, and the Cause & Effect Graph. Correlate those with Time Profiler and Hangs/Hitches.

Add `Self._printChanges()` in debug builds to log which property triggered a view update:

```swift
var body: some View {
    #if DEBUG
    let _ = Self._printChanges()  // "MyView: @self, _count changed."
    #endif
    Text("Count: \(count)")
}
```

See [references/optimizing-swiftui-performance-instruments.md](references/optimizing-swiftui-performance-instruments.md) for the full profiling workflow.

## Identity and Lifetime

Identity controls view lifetime and state. Use stable model IDs in repeated
content and reserve `.id(_:)` changes for intentional resets. Prefer
`@ViewBuilder` or generic composition over `AnyView` in profiled hot rows. Treat
root conditional branches as suspects—not automatic defects—when evidence shows
state churn or expensive recreation.

```swift
Text(title)
    .foregroundStyle(isHighlighted ? .yellow : .primary)

ForEach(items) { item in
    Row(item: item).id(item.stableID)
}
```

## Lazy Loading Patterns

Use lazy containers when profiling shows eager construction, layout, or update
work is material; there is no universal item-count threshold. Route grid/list
construction choices to `swiftui-layout-components`.

Guardrails:

- Off-screen views are removed from the lazy stack. SwiftUI may keep them briefly, then delete the views and their view-local state.
-