@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swiftui-animation/references/animation-advanced.md

@@ -1,825 +1,613 @@
-# SwiftUI Animation Advanced Reference
+# Advanced SwiftUI Animation
 
-Detailed API reference for SwiftUI animation types, protocols, and patterns.
-Covers material beyond the SKILL.md summary.
+Depth behind the main skill: custom curves, the full `Spring` API, unit
+curves, richer phase and keyframe patterns, transactions, every transition and
+symbol effect, Reduce Motion handling and performance.
 
 ## Contents
 
-- [CustomAnimation Protocol (iOS 17+)](#customanimation-protocol-ios-17)
-- [Spring Type -- All Initializer Variants](#spring-type-all-initializer-variants)
-- [UnitCurve Types (iOS 17+)](#unitcurve-types-ios-17)
-- [PhaseAnimator Deep Patterns](#phaseanimator-deep-patterns)
-- [KeyframeAnimator Multi-Track Examples](#keyframeanimator-multi-track-examples)
+- [CustomAnimation (iOS 17+)](#customanimation-ios-17)
+- [Spring, every initializer](#spring-every-initializer)
+- [UnitCurve (iOS 17+)](#unitcurve-ios-17)
+- [PhaseAnimator patterns](#phaseanimator-patterns)
+- [KeyframeAnimator patterns](#keyframeanimator-patterns)
 - [Transaction and TransactionKey](#transaction-and-transactionkey)
-- [Scoped Implicit Animation](#scoped-implicit-animation)
-- [All Transition Types (iOS 17+)](#all-transition-types-ios-17)
-- [All Symbol Effect Types](#all-symbol-effect-types)
-- [Reduce Motion Implementation Patterns](#reduce-motion-implementation-patterns)
-- [Animation Performance Tips](#animation-performance-tips)
+- [Choosing an implicit scope](#choosing-an-implicit-scope)
+- [Every transition (iOS 17+)](#every-transition-ios-17)
+- [Every symbol effect](#every-symbol-effect)
+- [Reduce Motion](#reduce-motion)
+- [Performance](#performance)
 
-## CustomAnimation Protocol (iOS 17+)
-
-Create entirely custom animation curves by conforming to `CustomAnimation`.
+## CustomAnimation (iOS 17+)
 
 ```swift
 @preconcurrency protocol CustomAnimation: Hashable, Sendable
 ```
 
-### Required Method
+One requirement and two optional hooks:
 
 ```swift
+// Required. Return the value at `time`, or nil once the animation is finished.
 func animate<V: VectorArithmetic>(
-    value: V,
-    time: TimeInterval,
-    context: inout AnimationContext<V>
+    value: V, time: TimeInterval, context: inout AnimationContext<V>
 ) -> V?
-```
-
-Return the interpolated value at the given time. Return `nil` when the
-animation is complete.
 
-### Optional Methods
-
-```swift
+// Optional. Current velocity, used when another animation takes over.
 func velocity<V: VectorArithmetic>(
-    value: V,
-    time: TimeInterval,
-    context: AnimationContext<V>
+    value: V, time: TimeInterval, context: AnimationContext<V>
 ) -> V?
 
+// Optional. Return true to absorb a new animation instead of being replaced.
 func shouldMerge<V: VectorArithmetic>(
-    previous: Animation,
-    value: V,
-    time: TimeInterval,
-    context: inout AnimationContext<V>
+    previous: Animation, value: V, time: TimeInterval, context: inout AnimationContext<V>
 ) -> Bool
 ```
 
-### Full Example: Elastic Ease-In-Out
+`value` is the full distance to travel; the return value is how much of it has
+been covered at `time`.
+
+A back-out curve that overshoots slightly and then settles:
 
 ```swift
-struct ElasticAnimation: CustomAnimation {
-    let duration: TimeInterval
+struct OvershootAnimation: CustomAnimation {
+    var duration: TimeInterval
+    var tension: Double = 1.7
 
     func animate<V: VectorArithmetic>(
-        value: V,
-        time: TimeInterval,
-        context: inout AnimationContext<V>
+        value: V, time: TimeInterval, context: inout AnimationContext<V>
     ) -> V? {
-        guard time <= duration else { return nil }
-        let p = time / duration
-        let s = sin((20 * p - 11.125) * ((2 * .pi) / 4.5))
-        let progress: Double
-        if p < 0.5 {
-            progress = -(pow(2, 20 * p - 10) * s) / 2
-        } else {
-            progress = (pow(2, -20 * p + 10) * s) / 2 + 1
-        }
+        if time > duration { return nil }
+        let t = time / duration - 1
+        let progress = t * t * ((tension + 1) * t + tension) + 1
         return value.scaled(by: progress)
     }
 }
-```
-
-### Ergonomic Extension Pattern
 
-Expose custom animations as static members on `Animation`.
-
-```swift
 extension Animation {
-    static var elastic: Animation {
-        elastic(duration: 0.35)
-    }
+    static var overshoot: Animation { overshoot(duration: 0.4) }
 
-    static func elastic(duration: TimeInterval) -> Animation {
-        Animation(ElasticAnimation(duration: duration))
+    static func overshoot(duration: TimeInterval) -> Animation {
+        Animation(OvershootAnimation(duration: duration))
     }
 }
 
-// Usage
-withAnimation(.elastic(duration: 0.5)) { isActive.toggle() }
+// withAnimation(.overshoot(duration: 0.5)) { panelOffset = 0 }
 ```
 
-### Supporting Types
-
-| Type | Role |
-|---|---|
-| `AnimationContext<V>` | Carries environment and per-animation state |
-| `AnimationState` | Key-value storage for persisted state |
-| `AnimationStateKey` | Protocol for defining custom state keys |
-
-## Spring Type -- All Initializer Variants
-
-### Perceptual (Preferred)
+Supporting types:
 
-```swift
-Spring(duration: 0.5, bounce: 0.0)
-```
-
-- `duration` -- Perceptual duration controlling pace. Default `0.5`.
-- `bounce` -- Bounciness. `0.0` = no bounce, `1.0` = undamped. Negative values
-  produce overdamped springs. Default `0.0`.
+- `AnimationContext<V>`: the environment plus state private to one running
+  animation.
+- `AnimationState`: a key-value store that persists across `animate` calls.
+- `AnimationStateKey`: the protocol your own state keys conform to.
 
-### Physical Parameters
+## Spring, every initializer
 
-```swift
-Spring(mass: 1.0, stiffness: 100.0, damping: 10.0, allowOverDamping: false)
-```
+### `Spring(duration:bounce:)`
 
-- `mass` -- Mass at end of spring. Default `1.0`.
-- `stiffness` -- Spring stiffness coefficient.
-- `damping` -- Friction-like drag force.
-- `allowOverDamping` -- Permit damping ratio > 1. Default `false`.
+- `duration`: perceived pace. Default `0.5`.
+- `bounce`: `0.0` none, `1.0` undamped, below zero overdamped. Default `0.0`.
 
-### Response-Based
+### `Spring(mass:stiffness:damping:allowOverDamping:)`
 
-```swift
-Spring(response: 0.5, dampingRatio: 0.7)
-```
+- `mass`: default `1.0`.
+- `stiffness`: the spring constant.
+- `damping`: the drag that slows it.
+- `allowOverDamping`: permits a damping ratio above 1. Default `false`.
 
-- `response` -- Stiffness expressed as approximate duration in seconds.
-- `dampingRatio` -- Fraction of critical damping. `1.0` = critically damped.
+### `Spring(response:dampingRatio:)`
 
-### Settling-Based
+- `response`: stiffness expressed as a rough duration in seconds.
+- `dampingRatio`: how much of critical damping is applied, where `1.0` means
+  exactly critical.
 
-```swift
-Spring(settlingDuration: 1.0, dampingRatio: 0.8, epsilon: 0.001)
-```
+### `Spring(settlingDuration:dampingRatio:epsilon:)`
 
-- `settlingDuration` -- Estimated time to come to rest.
-- `dampingRatio` -- Fraction of critical damping.
-- `epsilon` -- Threshold for considering the spring at rest. Default `0.001`.
+- `settlingDuration`: estimated time until it comes to rest.
+- `epsilon`: how close to rest counts as at rest. Default `0.001`.
 
 ### Presets
 
 ```swift
-Spring.smooth                                  // no bounce
-Spring.smooth(duration: 0.5, extraBounce: 0.0)
-Spring.snappy                                  // small bounce
-Spring.snappy(duration: 0.4, extraBounce: 0.1)
-Spring.bouncy                                  // visible bounce
-Spring.bouncy(duration: 0.5, extraBounce: 0.2)
+Spring.smooth
+Spring.smooth(duration: 0.6)
+Spring.snappy
+Spring.snappy(duration: 0.35, extraBounce: 0.05)
+Spring.bouncy
+Spring.bouncy(duration: 0.55, extraBounce: 0.15)
 ```
 
-### Querying State
+### Asking a spring questions
 
 ```swift
-let spring = Spring(duration: 0.5, bounce: 0.3)
-let v = spring.value(target: 1.0, initialVelocity: 0.0, time: 0.25)
-let vel = spring.velocity(target: 1.0, initialVelocity: 0.0, time: 0.25)
-let settle = spring.settlingDuration(target: 1.0, initialVelocity: 0.0, epsilon: 0.001)
+let pad = Spring(duration: 0.45, bounce: 0.2)
+let position = pad.value(target: 100.0, initialVelocity: 0, time: 0.1)
+let speed = pad.velocity(target: 100.0, initialVelocity: 0, time: 0.1)
+let restAt = pad.settlingDuration(target: 100.0, initialVelocity: 0, epsilon: 0.01)
 ```
 
-### Parameter Conversion
+Any spring can also be read in the other parameter systems through `mass`,
+`stiffness`, `damping`, `response`, `dampingRatio` and `settlingDuration`.
+For example, a spring with a 0.5 second duration and 0.3 bounce converts to
+mass 1.0, stiffness about 157.9 and damping about 17.6.
 
-```swift
-let spring = Spring(duration: 0.5, bounce: 0.3)
-// Access physical equivalents:
-spring.mass       // 1.0
-spring.stiffness  // 157.9
-spring.damping    // 17.6
-spring.response
-spring.dampingRatio
-spring.settlingDuration
-```
+## UnitCurve (iOS 17+)
 
-## UnitCurve Types (iOS 17+)
-
-Map input progress [0,1] to output progress [0,1]. Used with
+A `UnitCurve` maps progress in [0, 1] to eased progress in [0, 1]. Use it with
 `.timingCurve(_:duration:)`.
 
-### Built-in Curves
+Built in: `.linear`, `.easeIn`, `.easeOut`, `.easeInOut`, `.circularEaseIn`,
+`.circularEaseOut`, `.circularEaseInOut`.
 
-```swift
-UnitCurve.linear
-UnitCurve.easeIn
-UnitCurve.easeOut
-UnitCurve.easeInOut
-UnitCurve.circularEaseIn
-UnitCurve.circularEaseOut
-UnitCurve.circularEaseInOut
-```
-
-### Custom Bezier Curve
+Custom:
 
 ```swift
-UnitCurve.bezier(
-    startControlPoint: UnitPoint(x: 0.42, y: 0.0),
-    endControlPoint: UnitPoint(x: 0.58, y: 1.0)
+let gentle = UnitCurve.bezier(
+    startControlPoint: UnitPoint(x: 0.25, y: 0.1),
+    endControlPoint: UnitPoint(x: 0.25, y: 1.0)
 )
+let halfway = gentle.value(at: 0.5)
+let slope = gentle.velocity(at: 0.5)
+let reversed = gentle.inverse          // x and y swapped
 ```
 
-### Instance Members
+In use:
 
 ```swift
-let curve = UnitCurve.easeInOut
-curve.value(at: 0.5)    // output progress at midpoint
-curve.velocity(at: 0.5) // rate of change at midpoint
-curve.inverse            // swaps x and y components
+.animation(.timingCurve(UnitCurve.circularEaseOut, duration: 0.35), value: isOpen)
+.animation(.timingCurve(0.34, 1.56, 0.64, 1, duration: 0.45), value: isOpen)
 ```
 
-### Usage with Animation
+## PhaseAnimator patterns
 
-```swift
-.animation(.timingCurve(UnitCurve.circularEaseIn, duration: 0.4), value: x)
-
-// Cubic bezier control points
-.animation(.timingCurve(0.68, -0.55, 0.27, 1.55, duration: 0.5), value: x)
-```
-
-## PhaseAnimator Deep Patterns
-
-### Multi-Phase with Complex State
+### Phases that carry their own values
 
 ```swift
-enum LoadPhase: CaseIterable {
-    case ready, loading, spinning, complete
-
-    var scale: Double {
-        switch self {
-        case .ready: 1.0
-        case .loading: 0.9
-        case .spinning: 1.0
-        case .complete: 1.1
-        }
-    }
+enum UploadPhase: CaseIterable {
+    case idle, preparing, sending, done
 
-    var rotation: Angle {
-        switch self {
-        case .spinning: .degrees(360)
-        default: .zero
-        }
-    }
-
-    var opacity: Double {
-        self == .loading ? 0.7 : 1.0
-    }
+    var scale: Double { self == .preparing ? 0.9 : 1 }
+    var spin: Angle { self == .sending ? .degrees(360) : .zero }
+    var opacity: Double { self == .idle ? 0.6 : 1 }
 }
 
-struct LoadingIndicator: View {
-    var body: some View {
-        PhaseAnimator(LoadPhase.allCases) { phase in
-            Image(systemName: "arrow.triangle.2.circlepath")
-                .font(.title)
-                .scaleEffect(phase.scale)
-                .rotationEffect(phase.rotation)
-                .opacity(phase.opacity)
-        } animation: { phase in
-            switch phase {
-            case .ready: .smooth(duration: 0.2)
-            case .loading: .easeIn(duration: 0.15)
-            case .spinning: .linear(duration: 0.6)
-            case .complete: .spring(duration: 0.3, bounce: 0.4)
-            }
-        }
+PhaseAnimator(UploadPhase.allCases) { phase in
+    Image(systemName: "arrow.up.circle.fill")
+        .scaleEffect(phase.scale)
+        .rotationEffect(phase.spin)
+        .opacity(phase.opacity)
+} animation: { phase in
+    switch phase {
+    case .idle: .smooth
+    case .preparing: .easeIn(duration: 0.2)
+    case .sending: .linear(duration: 0.6)
+    case .done: .spring(duration: 0.45, bounce: 0.35)
     }
 }
 ```
 
-### Trigger-Based One-Shot
-
-Run through all phases once each time the trigger value changes.
+### One pass per trigger
 
 ```swift
-struct FeedbackDot: View {
-    @State private var feedbackTrigger = 0
-
-    var body: some View {
-        Button { feedbackTrigger += 1 } label: {
-            Circle()
-                .frame(width: 20, height: 20)
-                .phaseAnimator(
-                    [false, true, false],
-                    trigger: feedbackTrigger
-                ) { content, phase in
-                    content.scaleEffect(phase ? 1.5 : 1.0)
-                } animation: { _ in
-                    .spring(duration: 0.25, bounce: 0.5)
-                }
-        }
-        .buttonStyle(.plain)
+@State private var taps = 0
+
+Button("Like") { taps += 1 }
+    .phaseAnimator([false, true, false], trigger: taps) { content, pressed in
+        content.scaleEffect(pressed ? 1.2 : 1)
+    } animation: { _ in
+        .spring(duration: 0.3, bounce: 0.45)
     }
-}
 ```
 
-### View Modifier Form
+### Plain values as phases
+
+Phases do not have to be an enum:
 
 ```swift
-Text("Hello")
-    .phaseAnimator([0.0, 1.0, 0.0]) { content, phase in
-        content.opacity(phase)
-    } animation: { _ in .easeInOut(duration: 0.8) }
+Circle()
+    .phaseAnimator([0.2, 1.0, 0.2]) { content, level in
+        content.opacity(level)
+    } animation: { _ in
+        .easeInOut(duration: 0.8)
+    }
 ```
 
-## KeyframeAnimator Multi-Track Examples
+## KeyframeAnimator patterns
 
-### Bounce-and-Fade
+### Four tracks
 
 ```swift
-struct BounceValues {
-    var yOffset: Double = 0
-    var scale: Double = 1.0
-    var opacity: Double = 1.0
-    var rotation: Angle = .zero
+struct DropValues {
+    var y = -60.0
+    var scale = 0.8
+    var tilt = Angle.zero
+    var opacity = 0.0
 }
 
-struct BouncingBadge: View {
-    @State private var trigger = false
-
-    var body: some View {
-        Button { trigger.toggle() } label: {
-            Text("NEW")
-                .font(.caption.bold())
-                .padding(.horizontal)
-                .background(.red, in: Capsule())
-                .keyframeAnimator(
-                    initialValue: BounceValues(),
-                    trigger: trigger
-                ) { content, value in
-                    content
-                        .offset(y: value.yOffset)
-                        .scaleEffect(value.scale)
-                        .opacity(value.opacity)
-                        .rotationEffect(value.rotation)
-                } keyframes: { _ in
-                    KeyframeTrack(\.yOffset) {
-                        SpringKeyframe(-20, duration: 0.2)
-                        CubicKeyframe(5, duration: 0.15)
-                        SpringKeyframe(0, duration: 0.3)
-                    }
-                    KeyframeTrack(\.scale) {
-                        CubicKeyframe(1.3, duration: 0.2)
-                        CubicKeyframe(0.95, duration: 0.15)
-                        SpringKeyframe(1.0, duration: 0.3)
-                    }
-                    KeyframeTrack(\.rotation) {
-                        LinearKeyframe(.degrees(-5), duration: 0.1)
-                        LinearKeyframe(.degrees(5), duration: 0.1)
-                        SpringKeyframe(.zero, duration: 0.2)
-                    }
-                    KeyframeTrack(\.opacity) {
-                        MoveKeyframe(1.0)
-                    }
-                }
+Image(systemName: "gift.fill")
+    .keyframeAnimator(initialValue: DropValues(), trigger: revealCount) { view, v in
+        view
+            .offset(y: v.y)
+            .scaleEffect(v.scale)
+            .rotationEffect(v.tilt)
+            .opacity(v.opacity)
+    } keyframes: { _ in
+        KeyframeTrack(\.y) {
+            CubicKeyframe(0, duration: 0.3)
+            SpringKeyframe(-12, duration: 0.15)
+            SpringKeyframe(0, duration: 0.25)
+        }
+        KeyframeTrack(\.scale) {
+            CubicKeyframe(1.1, duration: 0.3)
+            SpringKeyframe(1.0, duration: 0.4)
+        }
+        KeyframeTrack(\.tilt) {
+            LinearKeyframe(.degrees(-8), duration: 0.15)
+            LinearKeyframe(.degrees(8), duration: 0.15)
+            SpringKeyframe(.zero, duration: 0.3)
+        }
+        KeyframeTrack(\.opacity) {
+            MoveKeyframe(1.0)
         }
-        .buttonStyle(.plain)
     }
-}
 ```
 
-### Repeating Keyframe Animation
+### Looping
 
 ```swift
-KeyframeAnimator(
-    initialValue: PulseValues(),
-    repeating: true
-) { value in
+struct Glow {
+    var scale = 1.0
+    var opacity = 0.5
+}
+
+KeyframeAnimator(initialValue: Glow(), repeating: true) { glow in
     Circle()
-        .fill(.blue)
-        .frame(width: 40, height: 40)
-        .scaleEffect(value.scale)
-        .opacity(value.opacity)
+        .fill(.yellow)
+        .scaleEffect(glow.scale)
+        .opacity(glow.opacity)
 } keyframes: { _ in
     KeyframeTrack(\.scale) {
-        CubicKeyframe(1.3, duration: 0.5)
-        CubicKeyframe(1.0, duration: 0.5)
+        CubicKeyframe(1.15, duration: 0.6)
+        CubicKeyframe(1, duration: 0.6)
     }
     KeyframeTrack(\.opacity) {
-        CubicKeyframe(0.6, duration: 0.5)
-        CubicKeyframe(1.0, duration: 0.5)
+        CubicKeyframe(0.95, duration: 0.6)
+        CubicKeyframe(0.5, duration: 0.6)
     }
 }
 ```
 
-### Keyframe Type Reference
+### Keyframe types
 
-| Type | Interpolation | Use case |
+| Keyframe | Motion | Typical use |
 |---|---|---|
-| `LinearKeyframe(value, duration:)` | Straight line between values | Steady movement |
-| `CubicKeyframe(value, duration:)` | Cubic bezier curve | Smooth easing |
-| `SpringKeyframe(value, duration:, spring:)` | Spring physics | Natural settle |
-| `MoveKeyframe(value)` | Instant jump | Reset to value immediately |
+| `LinearKeyframe(value, duration:)` | straight-line interpolation | steady movement |
+| `CubicKeyframe(value, duration:)` | cubic Bezier | smooth easing |
+| `SpringKeyframe(value, duration:spring:)` | driven by a spring | settling into place |
+| `MoveKeyframe(value)` | instant jump | resetting a value |
 
-### KeyframeTimeline for Manual Evaluation
+### Evaluating keyframes yourself
 
 ```swift
-let timeline = KeyframeTimeline(initialValue: AnimValues()) {
-    KeyframeTrack(\.scale) {
-        CubicKeyframe(1.5, duration: 0.3)
-        CubicKeyframe(1.0, duration: 0.4)
-    }
+let timeline = KeyframeTimeline(initialValue: 0.0) {
+    CubicKeyframe(20, duration: 0.3)
+    SpringKeyframe(0, duration: 0.5)
 }
-
-let totalDuration = timeline.duration
-let valueAtHalf = timeline.value(time: totalDuration / 2)
+let total = timeline.duration            // 0.8
+let atHalf = timeline.value(time: 0.5)
 ```
 
 ## Transaction and TransactionKey
 
-### Transaction Basics
-
-A `Transaction` carries the animation context for a state change. Every
-`withAnimation` call creates a transaction internally.
+Every state change travels with a `Transaction` that says how to animate it;
+`withAnimation` creates one behind the scenes.
 
 ```swift
-// Explicit transaction
-var transaction = Transaction(animation: .spring)
-withTransaction(transaction) {
-    isExpanded = true
-}
+let pinning = Transaction(animation: .snappy)
+withTransaction(pinning) { isPinned = true }
 ```
 
-### Overriding Animations with Transaction
+Removing the incoming animation for one subtree:
 
 ```swift
-// Remove the incoming transaction animation for this scoped content
-SomeView()
-    .transaction { transaction in
-        transaction.animation = nil
-    }
-
-// Override the scoped transaction animation when a value changes
-SomeView()
-    .transaction(value: selectedTab) { transaction in
-        transaction.animation = .smooth(duration: 0.3)
-    }
+BadgeView(count: count)
+    .transaction { $0.animation = nil }
 ```
 
-### Custom TransactionKey
+Overriding only when a particular value changes:
+
+```swift
+ChartView(points: points)
+    .transaction(value: selectedRange) { $0.animation = .smooth }
+```
 
-Store custom metadata in transactions.
+### Custom transaction metadata
 
 ```swift
-struct IsInteractiveKey: TransactionKey {
+struct DragDrivenKey: TransactionKey {
     static let defaultValue = false
 }
 
 extension Transaction {
-    var isInteractive: Bool {
-        get { self[IsInteractiveKey.self] }
-        set { self[IsInteractiveKey.self] = newValue }
+    var isDragDriven: Bool {
+        get { self[DragDrivenKey.self] }
+        set { self[DragDrivenKey.self] = newValue }
     }
 }
 
-// Usage
+// During a drag:
 var transaction = Transaction(animation: .interactiveSpring)
-transaction.isInteractive = true
-withTransaction(transaction) { dragOffset = newOffset }
+transaction.isDragDriven = true
+withTransaction(transaction) { cardOffset = dragTranslation }
 ```
 
-### Scoped Transaction Override
+A view downstream can read `transaction.isDragDriven` inside
+`.transaction { }` and choose a different animation.
+
+### Scoped override
+
+`.transaction(_:body:)` applies the change only to the modifiers in its body:
 
 ```swift
-// Apply transaction only within a body closure
-ParentView()
-    .transaction { $0.animation = .spring } body: { content in
-        content.scaleEffect(scale)
+Card()
+    .transaction { t in t.animation = .bouncy } body: { view in
+        view.scaleEffect(zoom)
     }
 ```
 
-### Scoped Implicit Animation
+## Choosing an implicit scope
 
-Use `.animation(_:body:)` when only selected modifiers should animate.
-Use `.animation(_:value:)` when a single value change should drive the view's
-animatable modifiers together. Use `.transaction(_:body:)` when you need to
-scope transaction overrides rather than attach one animation.
+| Need | Use |
+|---|---|
+| Animate some modifiers, not others | `.animation(_:body:)` |
+| One value drives every animatable modifier | `.animation(_:value:)` |
+| Adjust the transaction for a region rather than attach one animation | `.transaction(_:body:)` |
 
 ```swift
-CardView(isExpanded: isExpanded)
+NoteCard(note: note)
     .animation(.smooth) { content in
         content
-            .scaleEffect(isExpanded ? 1.05 : 1.0)
-            .shadow(radius: isExpanded ? 12 : 4)
+            .scaleEffect(isExpanded ? 1.05 : 1)
+            .shadow(radius: isExpanded ? 12 : 2)
     }
 ```
 
-## All Transition Types (iOS 17+)
-
-### Built-in Transitions
+## Every transition (iOS 17+)
 
-| Transition | Description | Example |
-|---|---|---|
-| `.opacity` | Fade in/out | `.transition(.opacity)` |
-| `.slide` | Slide from leading, exit trailing | `.transition(.slide)` |
-| `.scale` | Scale from zero | `.transition(.scale)` |
-| `.scale(_:anchor:)` | Scale with amount and anchor | `.transition(.scale(0.5, anchor: .bottom))` |
-| `.move(edge:)` | Move from specified edge | `.transition(.move(edge: .top))` |
-| `.push(from:)` | Push from edge with fade | `.transition(.push(from: .trailing))` |
-| `.offset(_:)` | Offset by CGSize | `.transition(.offset(CGSize(width: 0, height: 50)))` |
-| `.offset(x:y:)` | Offset by x and y | `.transition(.offset(x: 0, y: -100))` |
-| `.identity` | No visual change | `.transition(.identity)` |
-| `.blurReplace` | Blur and scale combined | `.transition(.blurReplace)` |
-| `.blurReplace(_:)` | Configurable blur replace | `.transition(.blurReplace(.downUp))` |
-| `.symbolEffect` | Default symbol effect | `.transition(.symbolEffect)` |
-| `.symbolEffect(_:options:)` | Custom symbol effect | `.transition(.symbolEffect(.appear))` |
-
-### Combining Transitions
+| Transition | Effect |
+|---|---|
+| `.opacity` | fade |
+| `.slide` | in from the leading edge, out toward the trailing edge |
+| `.scale` | grows from zero |
+| `.scale(0.5, anchor: .bottom)` | grows from a size and anchor |
+| `.move(edge: .leading)` | slides from an edge |
+| `.push(from: .trailing)` | push with a fade from an edge |
+| `.offset(CGSize(width: 0, height: 40))` | shifts by a size |
+| `.offset(x: 0, y: 40)` | shifts by components |
+| `.identity` | no visual change |
+| `.blurReplace` | blur combined with scale |
+| `.blurReplace(.downUp)` | configurable blur replace |
+| `.symbolEffect` | the default symbol transition |
+| `.symbolEffect(.appear)` | a chosen symbol effect, with options |
+
+Combining and splitting:
 
 ```swift
-// Slide + fade
 .transition(.slide.combined(with: .opacity))
-
-// Move from top + scale
-.transition(.move(edge: .top).combined(with: .scale))
-```
-
-### Asymmetric Transitions
-
-Different animation for insertion vs removal.
-
-```swift
+.transition(.scale.combined(with: .move(edge: .leading)))
 .transition(.asymmetric(
-    insertion: .push(from: .bottom).combined(with: .opacity),
-    removal: .scale.combined(with: .opacity)
+    insertion: .opacity.combined(with: .push(from: .top)),
+    removal: .opacity.combined(with: .scale(scale: 0.8))
 ))
 ```
 
-### Custom Transition
+`.asymmetric(insertion:removal:)` exists only on `AnyTransition`, so every
+argument inside it resolves to the `AnyTransition` members, where the sized
+scale is spelled `.scale(scale:anchor:)`. Elsewhere the `Transition` form
+`.scale(0.8)` works.
+
+### A custom Transition
 
 ```swift
-struct RotateTransition: Transition {
+struct FlipIn: Transition {
     func body(content: Content, phase: TransitionPhase) -> some View {
         content
-            .rotationEffect(phase.isIdentity ? .zero : .degrees(90))
+            .rotation3DEffect(.degrees(phase.isIdentity ? 0 : 90), axis: (x: 1, y: 0, z: 0))
             .opacity(phase.isIdentity ? 1 : 0)
     }
 }
 
-extension AnyTransition {
-    static var rotate: AnyTransition {
-        .init(RotateTransition())
-    }
+extension Transition where Self == FlipIn {
+    static var flipIn: FlipIn { FlipIn() }
 }
+
+// .transition(.flipIn)
 ```
 
-### TransitionPhase
+Where an API still wants the older type-erased value, wrap it:
+`AnyTransition(FlipIn())`, for example behind
+`extension AnyTransition { static var flipIn: AnyTransition { AnyTransition(FlipIn()) } }`.
 
-```swift
-enum TransitionPhase {
-    case willAppear   // View is about to be inserted
-    case identity     // View is fully presented
-    case didDisappear // View is being removed
-}
+`TransitionPhase`:
 
-// Check current phase
-phase.isIdentity  // true when fully presented
-```
+- `.willAppear`: about to be inserted.
+- `.identity`: fully on screen.
+- `.didDisappear`: being removed.
+- `isIdentity`: true only in the fully presented phase.
 
-### Attaching Animation to Transition
+### Pinning an animation to a transition
 
 ```swift
 .transition(
-    .move(edge: .bottom)
+    .scale(0.9)
         .combined(with: .opacity)
-        .animation(.spring(duration: 0.4, bounce: 0.2))
+        .animation(.spring(duration: 0.3, bounce: 0.15))
 )
 ```
 
-## All Symbol Effect Types
-
-### Discrete Effects (trigger with `value:`)
-
-| Effect | Scope | Direction |
-|---|---|---|
-| `.bounce` | `.byLayer`, `.wholeSymbol` | -- |
-| `.wiggle` | `.byLayer`, `.wholeSymbol` | `.up`, `.down`, `.left`, `.right`, `.forward`, `.backward`, `.clockwise`, `.counterClockwise`, `.custom(angle:)` |
-
-```swift
-Image(systemName: "bell.fill")
-    .symbolEffect(.bounce.byLayer, value: count)
-
-Image(systemName: "arrow.left.arrow.right")
-    .symbolEffect(.wiggle.left, value: swapCount)
-```
-
-### Indefinite Effects (toggle with `isActive:`)
-
-| Effect | Scope | Direction |
-|---|---|---|
-| `.pulse` | `.byLayer`, `.wholeSymbol` | -- |
-| `.variableColor` | `.byLayer`, `.wholeSymbol` | Chaining: `.cumulative`/`.iterative`, `.reversing`/`.nonReversing`, `.dimInactiveLayers`/`.hideInactiveLayers` |
-| `.scale` | `.byLayer`, `.wholeSymbol` | `.up`, `.down` |
-| `.breathe` | `.byLayer`, `.wholeSymbol` | -- |
-| `.rotate` | `.byLayer`, `.wholeSymbol` | `.clockwise`, `.counterClockwise` |
-
-```swift
-Image(systemName: "wifi")
-    .symbolEffect(.pulse.byLayer, isActive: isConnecting)
-
-Image(systemName: "gear")
-    .symbolEffect(.rotate.clockwise, isActive: isProcessing)
-
-Image(systemName: "speaker.wave.3.fill")
-    .symbolEffect(
-        .variableColor.cumulative.nonReversing.dimInactiveLayers,
-        options: .repeating,
-        isActive: isPlaying
-    )
-
-Image(systemName: "magnifyingglass")
-    .symbolEffect(.scale.up, isActive: isHighlighted)
-
-Image(systemName: "heart.fill")
-    .symbolEffect(.breathe, isActive: isFavorite)
-```
-
-### Transition Effects (appear/disappear)
-
-```swift
-Image(systemName: "checkmark.circle.fill")
-    .symbolEffect(.appear, isActive: showCheck)
-
-Image(systemName: "xmark.circle")
-    .symbolEffect(.disappear, isActive: shouldHide)
-```
-
-### Content Transition Effects (replace)
+## Every symbol effect
 
-```swift
-Image(systemName: isMuted ? "speaker.slash" : "speaker.wave.3")
-    .contentTransition(.symbolEffect(.replace.downUp))
+### Discrete, triggered by `value:`
 
-// Magic replace (morphs between symbols)
-Image(systemName: isPlaying ? "pause.fill" : "play.fill")
-    .contentTransition(.symbolEffect(.replace.magic(fallback: .downUp)))
-```
-
-Replace directions: `.downUp`, `.offUp`, `.upUp`.
-
-### SymbolEffectOptions
+- `.bounce`: scopes `.byLayer` and `.wholeSymbol`; no direction.
+- `.wiggle` (iOS 18): scopes, plus directions `.up`, `.down`, `.left`,
+  `.right`, `.forward`, `.backward`, `.clockwise`, `.counterClockwise`,
+  `.custom(angle:)`.
 
 ```swift
-.symbolEffect(.pulse, options: .default, isActive: true)
-.symbolEffect(.bounce, options: .repeating, value: count)
-.symbolEffect(.pulse, options: .nonRepeating, isActive: true)
-.symbolEffect(.bounce, options: .repeat(3), value: count)
-.symbolEffect(.pulse, options: .speed(2.0), isActive: true)
-
-// RepeatBehavior
-.symbolEffect(.bounce, options: .repeat(.periodic(3, delay: 0.5)), value: count)
-.symbolEffect(.pulse, options: .repeat(.continuous), isActive: true)
+Image(systemName: "tray.and.arrow.down.fill").symbolEffect(.bounce.byLayer, value: downloads)
+Image(systemName: "hand.wave.fill").symbolEffect(.wiggle.left, value: greetings)
 ```
 
-### Removing Effects
-
-```swift
-Image(systemName: "star.fill")
-    .symbolEffect(.pulse, isActive: true)
-    .symbolEffectsRemoved(reduceMotion)
-```
+### Indefinite, controlled by `isActive:`
 
-## Reduce Motion Implementation Patterns
+- `.pulse`
+- `.variableColor`: chain `.cumulative` or `.iterative`, `.reversing` or
+  `.nonReversing`, `.dimInactiveLayers` or `.hideInactiveLayers`.
+- `.scale`: `.up` or `.down`.
+- `.breathe` (iOS 18)
+- `.rotate` (iOS 18): `.clockwise` or `.counterClockwise`.
 
-### Environment Variable
+All of them take `.byLayer` or `.wholeSymbol`.
 
 ```swift
-@Environment(\.accessibilityReduceMotion) private var reduceMotion
+Image(systemName: "antenna.radiowaves.left.and.right").symbolEffect(.pulse.byLayer, isActive: isLive)
+Image(systemName: "gearshape.fill").symbolEffect(.rotate.clockwise, isActive: isSyncing)
+Image(systemName: "chart.bar.fill")
+    .symbolEffect(.variableColor.cumulative.nonReversing.dimInactiveLayers,
+                  options: .repeating, isActive: isLoading)
+Image(systemName: "plus.circle").symbolEffect(.scale.up, isActive: isHighlighted)
+Image(systemName: "moon.zzz.fill").symbolEffect(.breathe, isActive: isSleeping)
 ```
 
-### Pattern 1: Conditional Animation
+### Appear and disappear
 
 ```swift
-withAnimation(reduceMotion ? .none : .bouncy) {
-    isExpanded.toggle()
-}
+Image(systemName: "checkmark.seal.fill").symbolEffect(.appear, isActive: isVerified)
+Image(systemName: "exclamationmark.triangle").symbolEffect(.disappear, isActive: isResolved)
 ```
 
-### Pattern 2: Simplified Animation
-
-Replace bouncy/spring with crossfade when reduce motion is on.
-
-```swift
-withAnimation(reduceMotion ? .easeInOut(duration: 0.2) : .spring(duration: 0.4, bounce: 0.3)) {
-    selectedTab = newTab
-}
-```
+### Replace
 
-### Pattern 3: Disable Repeating Animations
+Replacement runs as a content transition:
 
 ```swift
-// WRONG: Ignores reduce motion
-PhaseAnimator(phases) { phase in /* ... */ }
-
-// CORRECT: Use trigger-based or skip entirely
-if !reduceMotion {
-    PhaseAnimator(phases) { phase in /* ... */ }
-} else {
-    StaticView()
-}
-```
-
-### Pattern 4: Symbol Effects
-
-```swift
-Image(systemName: "wifi")
-    .symbolEffect(.pulse, isActive: isSearching)
-    .symbolEffectsRemoved(reduceMotion)
-```
-
-### Pattern 5: Reusable Helper
-
-```swift
-extension Animation {
-    static func adaptive(
-        _ animation: Animation,
-        reduceMotion: Bool
-    ) -> Animation? {
-        reduceMotion ? nil : animation
-    }
-}
-
-// Usage
-withAnimation(.adaptive(.bouncy, reduceMotion: reduceMotion)) {
-    isVisible = true
-}
-```
-
-## Animation Performance Tips
-
-### Keep Content Closures Light
-
-The `content` closure in `KeyframeAnimator` and `PhaseAnimator` runs every
-frame while animating. Keep it to simple view modifiers.
-
-```swift
-// WRONG: Expensive computation per frame
-.keyframeAnimator(initialValue: v, trigger: t) { content, value in
-    let result = heavyComputation(value.progress)
-    return content.opacity(result)
-} keyframes: { _ in /* ... */ }
-
-// CORRECT: Only apply view modifiers
-.keyframeAnimator(initialValue: v, trigger: t) { content, value in
-    content.opacity(value.opacity)
-} keyframes: { _ in /* ... */ }
-```
-
-### Prefer Modifier-Based Animations
-
-Animating view modifiers (`opacity`, `scaleEffect`, `offset`, `rotationEffect`)
-is highly optimized. Avoid animating layout-triggering properties when possible.
-
-### Use drawingGroup for Complex Compositing
-
-```swift
-ComplexAnimatedView()
-    .drawingGroup()
-```
-
-Flattens the view hierarchy into a single Metal-backed layer. Use when
-compositing many overlapping animated views.
-
-### Limit Concurrent Animations
-
-Avoid animating dozens of views simultaneously. Use staggered delays.
-
-```swift
-ForEach(Array(items.enumerated()), id: \.element.id) { index, item in
-    ItemView(item: item)
-        .transition(.move(edge: .bottom).combined(with: .opacity))
-        .animation(.spring.delay(Double(index) * 0.05), value: isVisible)
-}
-```
-
-### Avoid Re-creating Views During Animation
-
-Ensure animated views maintain stable identity. Use explicit `id()` modifiers
-or stable `ForEach` identifiers.
-
-```swift
-// WRONG: View identity changes, breaks animation
-ForEach(Array(items.enumerated()), id: \.offset) { index, item in
-    ItemView(item: item)
-}
+Image(systemName: isLocked ? "lock.fill" : "lock.open.fill")
+    .contentTransition(.symbolEffect(.replace.downUp))
 
-// CORRECT: Stable identity from model
-ForEach(items) { item in
-    ItemView(item: item)
-}
+Image(systemName: isRecording ? "stop.circle.fill" : "record.circle")
+    .contentTransition(.symbolEffect(.replace.magic(fallback: .offUp)))   // iOS 18
 ```
 
-### Use geometryGroup() for Nested Geometry
+Directions: `.downUp`, `.offUp`, `.upUp`. `.magic` morphs shared parts of the
+two symbols and falls back to the given direction when it cannot.
 
-Isolate child geometry from parent animations when they conflict.
+### Options
 
 ```swift
-ParentView()
-    .scaleEffect(parentScale)
-    .geometryGroup()  // children see stable geometry
+.symbolEffect(.bounce, options: .default, value: n)
+.symbolEffect(.bounce, options: .repeating, value: n)
+.symbolEffect(.bounce, options: .nonRepeating, value: n)
+.symbolEffect(.bounce, options: .repeat(2), value: n)
+.symbolEffect(.bounce, options: .speed(2.0), value: n)
+.symbolEffect(.breathe, options: .repeat(.periodic(4, delay: 1.0)), isActive: on)   // iOS 18
+.symbolEffect(.breathe, options: .repeat(.continuous), isActive: on)               // iOS 18
 ```
 
-### Transaction for Selective Animation Override
+`.symbolEffectsRemoved(_:)` strips symbol effects from a subtree, for example
+`.symbolEffectsRemoved(reduceMotion)`.
 
-Override animation for specific subtrees without affecting siblings.
+## Reduce Motion
 
 ```swift
-// Disable animation on one child while parent animates
-ChildView()
-    .transaction { $0.animation = nil }
+@Environment(\.accessibilityReduceMotion) private var reduceMotion
 ```
 
-### Profile with Instruments
-
-Use the Core Animation instrument in Xcode Instruments to verify:
-- Frame rate stays at 120 fps (ProMotion devices) or 60 fps.
-- No offscreen rendering passes.
-- GPU utilization stays reasonable during animations.
+1. **No animation.**
+
+   ```swift
+   withAnimation(reduceMotion ? .none : .bouncy) { isOpen.toggle() }
+   ```
+
+2. **A calmer substitute.** Swap a spring or bounce for a short fade-like
+   curve:
+
+   ```swift
+   .animation(reduceMotion ? .easeInOut(duration: 0.2) : .bouncy, value: isOpen)
+   ```
+
+3. **No endless loops.** A `PhaseAnimator` without a trigger keeps moving no
+   matter what the setting says.
+
+   ```swift
+   if reduceMotion {
+       LoadingDots()
+   } else {
+       PhaseAnimator([0.4, 1.0]) { level in
+           LoadingDots().opacity(level)
+       }
+   }
+   ```
+
+   The trigger form, which plays once per change, is the other option.
+
+4. **Symbol effects.**
+
+   ```swift
+   StatusIcons().symbolEffectsRemoved(reduceMotion)
+   ```
+
+5. **A helper.**
+
+   ```swift
+   extension Animation {
+       static func motionAware(_ preferred: Animation, reduceMotion: Bool) -> Animation? {
+           reduceMotion ? nil : preferred
+       }
+   }
+
+   withAnimation(.motionAware(.bouncy, reduceMotion: reduceMotion)) { isOpen.toggle() }
+   ```
+
+## Performance
+
+- **Per-frame closures stay light.** `KeyframeAnimator` and `PhaseAnimator`
+  call their content every frame.
+
+  ```swift
+  // Wrong: sorts on every frame
+  .keyframeAnimator(initialValue: 0.0, trigger: t) { view, v in
+      view.overlay(Text(scores.sorted().first ?? "")).opacity(v)
+  } keyframes: { _ in LinearKeyframe(1.0, duration: 0.3) }
+
+  // Right: computed once, read per frame
+  let leader = scores.sorted().first ?? ""
+  // ... view.overlay(Text(leader)).opacity(v)
+  ```
+
+- **Animate cheap properties.** `opacity`, `scaleEffect`, `offset` and
+  `rotationEffect` are handled efficiently by the renderer. Animating `frame`,
+  padding or anything else that forces layout costs more.
+- **`.drawingGroup()`** flattens a subtree and draws it offscreen with Metal as
+  one image; useful when many overlapping views animate together.
+- **Stagger large groups** instead of starting dozens of animations at once:
+
+  ```swift
+  ForEach(Array(cards.enumerated()), id: \.element.id) { index, card in
+      CardView(card: card)
+          .offset(y: isShown ? 0 : 30)
+          .opacity(isShown ? 1 : 0)
+          .animation(.snappy.delay(Double(index) * 0.04), value: isShown)
+  }
+  ```
+
+- **Stable identity.** `ForEach(items.enumerated(), id: \.offset)` ties
+  identity to position, so inserts and deletes animate the wrong views. Use
+  the model's identity (`ForEach(items)`) or an explicit `.id()`.
+- **`.geometryGroup()`** makes children resolve their geometry together, which
+  stops them fighting a parent's animation such as a `scaleEffect`.
+- **Opt a child out** with `.transaction { $0.animation = nil }` while its
+  parent and siblings keep animating.
+- **Measure** with the Core Animation instrument in Instruments: aim for
+  120 fps on ProMotion displays (60 elsewhere), no offscreen rendering passes,
+  and moderate GPU load.