@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,553 +1,504 @@
 # Core Animation Bridge
 
-Patterns for bridging Core Animation (QuartzCore) with SwiftUI. Use when SwiftUI's built-in animation system is insufficient -- typically for performance-critical layer animations, unsupported animation curves, or direct CALayer manipulation. Overflow reference for the `swiftui-animation` skill.
+Material that did not fit in the main SwiftUI animation skill. Reach for Core
+Animation only when SwiftUI's animation system cannot do the job: layer animation on a
+hot path, a curve SwiftUI cannot express, or direct work on a `CALayer`.
 
 ## Contents
 
-- [When to Drop Below SwiftUI Animations](#when-to-drop-below-swiftui-animations)
+- [When dropping down is justified](#when-dropping-down-is-justified)
+- [The model value rule](#the-model-value-rule)
 - [CABasicAnimation](#cabasicanimation)
 - [CAKeyframeAnimation](#cakeyframeanimation)
 - [CASpringAnimation](#caspringanimation)
 - [CAAnimationGroup](#caanimationgroup)
 - [CADisplayLink](#cadisplaylink)
-- [UIViewRepresentable Wrapper for CA Layers](#uiviewrepresentable-wrapper-for-ca-layers)
-- [Bridging CA Animations with SwiftUI State](#bridging-ca-animations-with-swiftui-state)
-- [Performance Considerations](#performance-considerations)
-
-## When to Drop Below SwiftUI Animations
-
-SwiftUI's animation system covers most use cases. Drop to Core Animation only when:
-
-| Scenario | Why CA Is Needed |
-|----------|-----------------|
-| **Custom timing functions** beyond spring/ease | `CAMediaTimingFunction` supports arbitrary cubic Bezier curves |
-| **Layer-specific properties** (shadowPath, borderWidth, etc.) | SwiftUI does not expose all CALayer animatable properties |
-| **Additive animations** | CA supports additive blending of multiple concurrent animations on the same property |
-| **Frame-synchronized drawing** | `CADisplayLink` provides precise frame timing for custom rendering |
-| **Performance-critical particle/effects** | Direct layer manipulation avoids SwiftUI's diffing overhead |
-| **Animation along a path** | `CAKeyframeAnimation` supports `CGPath`-based animation paths |
-
-If SwiftUI's `withAnimation`, `PhaseAnimator`, or `KeyframeAnimator` can achieve the effect, prefer them. Core Animation bridging adds complexity and requires explicit `UIViewRepresentable` wrappers.
+- [Hosting layer animation in SwiftUI](#hosting-layer-animation-in-swiftui)
+- [Moving state across the bridge](#moving-state-across-the-bridge)
+- [Performance](#performance)
+- [Apple documentation](#apple-documentation)
+
+## When dropping down is justified
+
+| Need | Why Core Animation |
+|---|---|
+| Arbitrary timing | `CAMediaTimingFunction` takes any cubic Bezier control points |
+| Layer-only properties | `shadowPath`, `borderWidth` and similar are not all reachable from SwiftUI |
+| Additive animation | several animations can run on one property at the same time and blend |
+| Drawing locked to the display | `CADisplayLink` fires once per refresh |
+| Particles and ambient effects | plain layers skip SwiftUI's view diffing entirely |
+| Motion along a path | `CAKeyframeAnimation` follows a `CGPath` |
+
+If `withAnimation`, `PhaseAnimator` or `KeyframeAnimator` can do it, use them.
+Every bridge means a `UIViewRepresentable`, layer lifetimes and state to keep
+in sync.
+
+## The model value rule
+
+Core Animation animates the presentation layer, a copy of the layer drawn on
+screen. The model layer keeps whatever value you last assigned. When the
+animation is removed, the presentation snaps back to the model. So every time
+you add an animation, also assign the end value to the layer itself.
+
+`fillMode = .forwards` with `isRemovedOnCompletion = false` hides the snap by
+keeping the finished animation attached, but the model still holds the old
+value, hit testing and later animations start from the wrong place, and the
+animation object is never released. Set the model value instead; keep that pair
+for the rare case where the model value must not change.
 
 ## CABasicAnimation
 
-[`CABasicAnimation`](https://sosumi.ai/documentation/quartzcore/cabasicanimation) interpolates a single layer property between two values.
-
-### Basic Usage
+One property, from one value to another:
 
 ```swift
-import QuartzCore
-
-let animation = CABasicAnimation(keyPath: "opacity")
-animation.fromValue = 0.0
-animation.toValue = 1.0
-animation.duration = 0.3
-animation.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
-
-// Apply to a layer
-layer.add(animation, forKey: "fadeIn")
-layer.opacity = 1.0 // Set the final model value
+let fade = CABasicAnimation(keyPath: "opacity")
+fade.fromValue = badgeLayer.opacity
+fade.toValue = 0.2
+fade.duration = 0.3
+fade.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+badgeLayer.add(fade, forKey: "fade")
+badgeLayer.opacity = 0.2                      // model value
 ```
 
-### Custom Bezier Timing
+A custom Bezier curve on a position:
 
 ```swift
-// Custom cubic Bezier curve -- not available in SwiftUI
-let timingFunction = CAMediaTimingFunction(controlPoints: 0.2, 0.8, 0.2, 1.0)
-
-let animation = CABasicAnimation(keyPath: "position.y")
-animation.fromValue = layer.position.y
-animation.toValue = layer.position.y - 100
-animation.duration = 0.5
-animation.timingFunction = timingFunction
-animation.fillMode = .forwards
-animation.isRemovedOnCompletion = false
-
-layer.add(animation, forKey: "customBezier")
+let rise = CABasicAnimation(keyPath: "position.y")
+rise.fromValue = tagLayer.position.y
+rise.toValue = tagLayer.position.y - 80
+rise.duration = 0.5
+rise.timingFunction = CAMediaTimingFunction(controlPoints: 0.16, 1.0, 0.3, 1.0)
+tagLayer.add(rise, forKey: "rise")
+tagLayer.position.y -= 80
 ```
 
-### Shadow Path Animation
+Animating `shadowPath`, which SwiftUI has no handle on:
 
 ```swift
-// Animate shadowPath -- not possible in pure SwiftUI
-let animation = CABasicAnimation(keyPath: "shadowPath")
-animation.fromValue = layer.shadowPath
-animation.toValue = UIBezierPath(roundedRect: newBounds, cornerRadius: 16).cgPath
-animation.duration = 0.3
-animation.timingFunction = CAMediaTimingFunction(name: .easeOut)
-
-layer.shadowPath = UIBezierPath(roundedRect: newBounds, cornerRadius: 16).cgPath
-layer.add(animation, forKey: "shadowPath")
+let target = UIBezierPath(roundedRect: tileLayer.bounds, cornerRadius: 16).cgPath
+let reshape = CABasicAnimation(keyPath: "shadowPath")
+reshape.fromValue = tileLayer.shadowPath
+reshape.toValue = target
+reshape.duration = 0.35
+tileLayer.add(reshape, forKey: "shadowPath")
+tileLayer.shadowPath = target
 ```
 
-**Important:** Always set the model value (the property on the layer itself) to the final state. Core Animation operates on a separate presentation layer -- without setting the model value, the layer snaps back when the animation completes.
-
-> **Docs:** [CABasicAnimation](https://sosumi.ai/documentation/quartzcore/cabasicanimation) | [CAMediaTimingFunction](https://sosumi.ai/documentation/quartzcore/camediatimingfunction)
-
 ## CAKeyframeAnimation
 
-[`CAKeyframeAnimation`](https://sosumi.ai/documentation/quartzcore/cakeyframeanimation) animates a property through a sequence of values or along a path.
-
-### Value-Based Keyframes
+### Through a list of values
 
 ```swift
-let animation = CAKeyframeAnimation(keyPath: "transform.scale")
-animation.values = [1.0, 1.3, 0.9, 1.05, 1.0]
-animation.keyTimes = [0, 0.25, 0.5, 0.75, 1.0] // Normalized [0..1]
-animation.duration = 0.6
-animation.timingFunctions = [
-    CAMediaTimingFunction(name: .easeOut),
-    CAMediaTimingFunction(name: .easeIn),
+let pop = CAKeyframeAnimation(keyPath: "transform.scale")
+pop.values = [1.0, 1.25, 0.92, 1.04, 1.0]
+pop.keyTimes = [0, 0.3, 0.55, 0.8, 1.0]       // fractions of duration
+pop.duration = 0.6
+pop.timingFunctions = [
     CAMediaTimingFunction(name: .easeOut),
-    CAMediaTimingFunction(name: .easeInEaseOut)
+    CAMediaTimingFunction(name: .easeInEaseOut),
+    CAMediaTimingFunction(name: .easeInEaseOut),
+    CAMediaTimingFunction(name: .easeIn)
 ]
-
-layer.add(animation, forKey: "bounceScale")
+iconLayer.add(pop, forKey: "pop")
 ```
 
-### Path-Based Animation
+### Along a path
 
 ```swift
-// Animate position along a CGPath -- unique to CAKeyframeAnimation
-let path = CGMutablePath()
-path.move(to: CGPoint(x: 50, y: 300))
-path.addCurve(
-    to: CGPoint(x: 300, y: 50),
-    control1: CGPoint(x: 100, y: 50),
-    control2: CGPoint(x: 250, y: 300)
-)
-
-let animation = CAKeyframeAnimation(keyPath: "position")
-animation.path = path
-animation.duration = 1.5
-animation.rotationMode = .rotateAuto // Rotate along the tangent
-animation.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
-
-layer.add(animation, forKey: "pathAnimation")
-layer.position = CGPoint(x: 300, y: 50)
+let route = CGMutablePath()
+route.move(to: start)
+route.addCurve(to: end, control1: CGPoint(x: start.x, y: end.y - 120),
+               control2: CGPoint(x: end.x, y: start.y - 120))
+
+let fly = CAKeyframeAnimation(keyPath: "position")
+fly.path = route
+fly.rotationMode = .rotateAuto                 // face along the tangent
+fly.duration = 0.9
+planeLayer.add(fly, forKey: "fly")
+planeLayer.position = end
 ```
 
-### Shake Animation (Discrete Keyframes)
+### A shake helper
 
 ```swift
-func shakeAnimation() -> CAKeyframeAnimation {
-    let animation = CAKeyframeAnimation(keyPath: "transform.translation.x")
-    animation.values = [0, -10, 10, -8, 8, -5, 5, 0]
-    animation.keyTimes = [0, 0.125, 0.25, 0.375, 0.5, 0.625, 0.75, 1.0]
-    animation.duration = 0.5
-    animation.timingFunction = CAMediaTimingFunction(name: .easeOut)
-    return animation
+extension CALayer {
+    func shakeHorizontally() {
+        let shake = CAKeyframeAnimation(keyPath: "transform.translation.x")
+        shake.values = [0, -12, 12, -9, 9, -4, 4, 0]
+        shake.keyTimes = [0, 0.14, 0.28, 0.42, 0.57, 0.71, 0.85, 1]
+        shake.duration = 0.5
+        shake.timingFunction = CAMediaTimingFunction(name: .easeOut)
+        add(shake, forKey: "shake")
+    }
 }
 ```
 
-> **Docs:** [CAKeyframeAnimation](https://sosumi.ai/documentation/quartzcore/cakeyframeanimation)
+The values return to zero, so no model value needs setting.
 
 ## CASpringAnimation
 
-[`CASpringAnimation`](https://sosumi.ai/documentation/quartzcore/caspringanimation) applies spring physics to a layer property. It extends `CABasicAnimation` with physical spring attributes.
-
-### Physical Spring Parameters
+A `CABasicAnimation` subclass with `mass`, `stiffness`, `damping` and
+`initialVelocity`:
 
 ```swift
-let spring = CASpringAnimation(keyPath: "transform.scale")
-spring.fromValue = 0.0
-spring.toValue = 1.0
-spring.mass = 1.0
-spring.stiffness = 200.0
-spring.damping = 10.0
-spring.initialVelocity = 0.0
-spring.duration = spring.settlingDuration // Use the physics-calculated duration
-
-layer.add(spring, forKey: "springScale")
-layer.transform = CATransform3DIdentity
+let settle = CASpringAnimation(keyPath: "transform.scale")
+settle.mass = 1
+settle.stiffness = 180
+settle.damping = 14
+settle.initialVelocity = 0
+settle.fromValue = 0.85
+settle.toValue = 1.0
+settle.duration = settle.settlingDuration      // let the spring finish
+cardLayer.add(settle, forKey: "settle")
+cardLayer.transform = CATransform3DIdentity
 ```
 
-### Perceptual Spring (iOS 17+)
+From iOS 17 the perceptual initializer matches SwiftUI's
+`Spring(duration:bounce:)`:
 
 ```swift
-let spring = CASpringAnimation(perceptualDuration: 0.5, bounce: 0.3)
-spring.keyPath = "position.y"
-spring.fromValue = layer.position.y
-spring.toValue = layer.position.y - 100
-
-layer.add(spring, forKey: "perceptualSpring")
-layer.position.y -= 100
+let settle = CASpringAnimation(perceptualDuration: 0.45, bounce: 0.2)
+settle.keyPath = "transform.scale"
+settle.fromValue = 0.85
+settle.toValue = 1.0
 ```
 
-The `perceptualDuration` and `bounce` initializer matches SwiftUI's `Spring(duration:bounce:)`, making it easier to keep CA and SwiftUI spring behaviors consistent.
-
-### Matching SwiftUI Spring Presets
+Rough equivalents of the SwiftUI presets. All three presets default to a
+0.5 second duration and differ in bounce:
 
-| SwiftUI Preset | CA Equivalent |
-|---------------|---------------|
-| `.smooth` | `CASpringAnimation(perceptualDuration: 0.5, bounce: 0.0)` |
-| `.snappy` | `CASpringAnimation(perceptualDuration: 0.4, bounce: 0.15)` |
-| `.bouncy` | `CASpringAnimation(perceptualDuration: 0.5, bounce: 0.3)` |
-
-> **Docs:** [CASpringAnimation](https://sosumi.ai/documentation/quartzcore/caspringanimation)
+| SwiftUI | `perceptualDuration` | `bounce` |
+|---|---|---|
+| `.smooth` | 0.5 | 0.0 |
+| `.snappy` | 0.5 | 0.15 |
+| `.bouncy` | 0.5 | 0.3 |
 
 ## CAAnimationGroup
 
-[`CAAnimationGroup`](https://sosumi.ai/documentation/quartzcore/caanimationgroup) runs multiple animations concurrently on the same layer.
+Several animations on one layer, sharing timing:
 
 ```swift
-let scaleAnim = CABasicAnimation(keyPath: "transform.scale")
-scaleAnim.fromValue = 0.5
-scaleAnim.toValue = 1.0
-
-let opacityAnim = CABasicAnimation(keyPath: "opacity")
-opacityAnim.fromValue = 0.0
-opacityAnim.toValue = 1.0
-
-let group = CAAnimationGroup()
-group.animations = [scaleAnim, opacityAnim]
-group.duration = 0.4
-group.timingFunction = CAMediaTimingFunction(name: .easeOut)
-
-layer.add(group, forKey: "appearGroup")
-layer.transform = CATransform3DIdentity
-layer.opacity = 1.0
+let grow = CABasicAnimation(keyPath: "transform.scale")
+grow.fromValue = 0.6
+grow.toValue = 1.0
+
+let show = CABasicAnimation(keyPath: "opacity")
+show.fromValue = 0
+show.toValue = 1
+
+let entrance = CAAnimationGroup()
+entrance.animations = [grow, show]
+entrance.duration = 0.4
+entrance.timingFunction = CAMediaTimingFunction(name: .easeOut)
+bannerLayer.add(entrance, forKey: "entrance")
+bannerLayer.transform = CATransform3DIdentity
+bannerLayer.opacity = 1
 ```
 
-> **Docs:** [CAAnimationGroup](https://sosumi.ai/documentation/quartzcore/caanimationgroup)
-
 ## CADisplayLink
 
-[`CADisplayLink`](https://sosumi.ai/documentation/quartzcore/cadisplaylink) is a timer synchronized to the display's refresh rate. Use it for frame-accurate custom drawing, particle systems, or manual animation loops.
-
-### Basic Display Link
+A timer that fires in step with the display.
 
 ```swift
-import QuartzCore
-
-final class FrameAnimator {
-    private var displayLink: CADisplayLink?
+@MainActor
+final class CountUpDriver: NSObject {
+    private var link: CADisplayLink?
     private var startTime: CFTimeInterval = 0
+    private let length: CFTimeInterval = 2
+    var onFrame: (Double) -> Void = { _ in }
 
     func start() {
-        displayLink = CADisplayLink(target: self, selector: #selector(onFrame))
-        displayLink?.add(to: .main, forMode: .common)
+        guard link == nil else { return }
         startTime = CACurrentMediaTime()
+        let link = CADisplayLink(target: self, selector: #selector(frame(_:)))
+        link.preferredFrameRateRange = CAFrameRateRange(minimum: 60, maximum: 120, preferred: 120)
+        link.add(to: .main, forMode: .common)
+        self.link = link
     }
 
     func stop() {
-        displayLink?.invalidate()
-        displayLink = nil
+        link?.invalidate()
+        link = nil
     }
 
-    @objc private func onFrame(_ link: CADisplayLink) {
-        let elapsed = link.timestamp - startTime
-        let progress = min(elapsed / 2.0, 1.0) // 2-second animation
-
-        // Update rendering based on progress
-        updateAnimation(progress: progress)
-
-        if progress >= 1.0 {
-            stop()
-        }
-    }
-
-    private func updateAnimation(progress: Double) {
-        // Custom per-frame rendering logic
+    @objc private func frame(_ link: CADisplayLink) {
+        let progress = min((link.timestamp - startTime) / length, 1)
+        onFrame(progress)
+        if progress >= 1 { stop() }
     }
 }
 ```
 
-### ProMotion Frame Rate Control
+Frame-rate guidance for `preferredFrameRateRange` on ProMotion displays:
 
-On ProMotion displays (120 Hz), use `preferredFrameRateRange` to balance smoothness and power:
+| Preferred | For |
+|---|---|
+| 120 | scrolling and following a finger |
+| 60 | ordinary animation |
+| 30 | slow ambient motion, or saving power |
 
-```swift
-displayLink?.preferredFrameRateRange = CAFrameRateRange(
-    minimum: 30,
-    maximum: 120,
-    preferred: 60
-)
-```
+Always call `invalidate()` when finished. A display link left running keeps the
+CPU awake and drains the battery, and it retains its target until invalidated.
 
-| Range | Use Case |
-|-------|----------|
-| `preferred: 120` | Smooth scrolling, gesture tracking |
-| `preferred: 60` | Standard animations |
-| `preferred: 30` | Ambient/slow animations, power saving |
-
-**Important:** Always call `invalidate()` when done. A running `CADisplayLink` prevents the CPU from idling and drains battery.
-
-> **Docs:** [CADisplayLink](https://sosumi.ai/documentation/quartzcore/cadisplaylink) | [Optimizing ProMotion refresh rates](https://sosumi.ai/documentation/quartzcore/optimizing-promotion-refresh-rates-for-iphone-13-pro-and-ipad-pro)
-
-## UIViewRepresentable Wrapper for CA Layers
-
-To use Core Animation layers inside SwiftUI, wrap them in a `UIViewRepresentable`.
-
-### Animated Layer View
+## Hosting layer animation in SwiftUI
 
 ```swift
-import SwiftUI
-import QuartzCore
-
-struct AnimatedLayerView: UIViewRepresentable {
+struct SoundWave: UIViewRepresentable {
     var isAnimating: Bool
-    var color: Color
+    var tint: UIColor
 
-    func makeUIView(context: Context) -> AnimatedLayerUIView {
-        let view = AnimatedLayerUIView()
-        return view
+    func makeUIView(context: Context) -> SoundWaveView {
+        SoundWaveView()
     }
 
-    func updateUIView(_ uiView: AnimatedLayerUIView, context: Context) {
-        uiView.updateColor(UIColor(color))
-
+    func updateUIView(_ view: SoundWaveView, context: Context) {
+        view.setTint(tint)
         if isAnimating {
-            uiView.startAnimation()
+            view.startWaving()
         } else {
-            uiView.stopAnimation()
+            view.stopWaving()
         }
     }
 
-    static func dismantleUIView(_ uiView: AnimatedLayerUIView, coordinator: ()) {
-        uiView.stopAnimation()
+    static func dismantleUIView(_ view: SoundWaveView, coordinator: ()) {
+        view.stopWaving()
     }
 }
-```
 
-### The Backing UIView
-
-```swift
-final class AnimatedLayerUIView: UIView {
-    private let animationLayer = CAShapeLayer()
-    private var displayLink: CADisplayLink?
+final class SoundWaveView: UIView {
+    private let waveLayer = CAShapeLayer()
+    private var link: CADisplayLink?
     private var phase: CGFloat = 0
 
     override init(frame: CGRect) {
         super.init(frame: frame)
-        setupLayer()
+        configureLayer()
     }
 
     required init?(coder: NSCoder) {
         super.init(coder: coder)
-        setupLayer()
+        configureLayer()
     }
 
-    private func setupLayer() {
-        animationLayer.fillColor = UIColor.systemBlue.cgColor
-        animationLayer.strokeColor = nil
-        layer.addSublayer(animationLayer)
+    private func configureLayer() {
+        waveLayer.fillColor = UIColor.systemBlue.cgColor
+        layer.addSublayer(waveLayer)
     }
 
     override func layoutSubviews() {
         super.layoutSubviews()
-        animationLayer.frame = bounds
-        updatePath()
-    }
-
-    func updateColor(_ color: UIColor) {
-        // Animate color change at the CA layer level
-        let animation = CABasicAnimation(keyPath: "fillColor")
-        animation.fromValue = animationLayer.fillColor
-        animation.toValue = color.cgColor
-        animation.duration = 0.3
-
-        animationLayer.fillColor = color.cgColor
-        animationLayer.add(animation, forKey: "colorChange")
+        waveLayer.frame = bounds
     }
 
-    func startAnimation() {
-        guard displayLink == nil else { return }
-        displayLink = CADisplayLink(target: self, selector: #selector(tick))
-        displayLink?.preferredFrameRateRange = CAFrameRateRange(
-            minimum: 30, maximum: 60, preferred: 60
-        )
-        displayLink?.add(to: .main, forMode: .common)
+    func setTint(_ color: UIColor) {
+        guard waveLayer.fillColor != color.cgColor else { return }
+        let recolor = CABasicAnimation(keyPath: "fillColor")
+        recolor.fromValue = waveLayer.fillColor
+        recolor.toValue = color.cgColor
+        recolor.duration = 0.25
+        waveLayer.add(recolor, forKey: "fillColor")
+        waveLayer.fillColor = color.cgColor
     }
 
-    func stopAnimation() {
-        displayLink?.invalidate()
-        displayLink = nil
+    func startWaving() {
+        guard link == nil else { return }
+        let link = CADisplayLink(target: self, selector: #selector(advanceWave(_:)))
+        link.preferredFrameRateRange = CAFrameRateRange(minimum: 20, maximum: 60, preferred: 30)
+        link.add(to: .main, forMode: .common)
+        self.link = link
     }
 
-    @objc private func tick(_ link: CADisplayLink) {
-        phase += 0.05
-        updatePath()
+    func stopWaving() {
+        link?.invalidate()
+        link = nil
     }
 
-    private func updatePath() {
-        let path = CGMutablePath()
-        let width = bounds.width
-        let height = bounds.height
-        let midY = height / 2
-
-        path.move(to: CGPoint(x: 0, y: midY))
-        for x in stride(from: 0, to: width, by: 2) {
-            let relativeX = x / width
-            let y = midY + sin((relativeX * .pi * 4) + phase) * (height * 0.3)
-            path.addLine(to: CGPoint(x: x, y: y))
+    @objc private func advanceWave(_ link: CADisplayLink) {
+        phase += 0.12
+        let crest = stride(from: bounds.minX, through: bounds.maxX, by: 3).map { x in
+            CGPoint(x: x, y: bounds.midY + sin(x / 24 + phase) * 18)
         }
-        path.addLine(to: CGPoint(x: width, y: height))
-        path.addLine(to: CGPoint(x: 0, y: height))
-        path.closeSubpath()
-
-        animationLayer.path = path
+        let outline = CGMutablePath()
+        outline.addLines(between: [CGPoint(x: bounds.minX, y: bounds.maxY)]
+            + crest + [CGPoint(x: bounds.maxX, y: bounds.maxY)])
+        outline.closeSubpath()
+        waveLayer.path = outline
     }
 }
 ```
 
-### SwiftUI Usage
+In SwiftUI:
 
 ```swift
-struct WaveView: View {
-    @State private var isAnimating = true
-
-    var body: some View {
-        Button { isAnimating.toggle() } label: {
-            AnimatedLayerView(isAnimating: isAnimating, color: .blue)
-                .frame(height: 200)
-                .clipShape(.rect(cornerRadius: 16))
-        }
-        .buttonStyle(.plain)
-    }
+@State private var recording = false
+
+Button { recording.toggle() } label: {
+    SoundWave(isAnimating: recording, tint: recording ? .systemRed : .systemBlue)
+        .frame(height: 200)
+        .clipShape(.rect(cornerRadius: 16))
 }
 ```
 
-### Key Rules for CA-in-SwiftUI Wrappers
+Rules for the wrapper:
 
-1. **Create layers in `makeUIView` or the UIView subclass initializer**, not in `updateUIView`.
-2. **Stop display links in `dismantleUIView`** to prevent leaks and background CPU usage.
-3. **Guard against redundant animation starts** in `updateUIView` -- it runs on every SwiftUI state change.
-4. **Set model values alongside CA animations** so the layer state is correct after animations complete.
+1. Layers are built once, when the view is made (`makeUIView` or the
+   `UIView` initializer). `updateUIView` only changes them.
+2. `dismantleUIView` is where display links get invalidated; skip it and they
+   leak and keep the CPU busy after the view is gone.
+3. SwiftUI calls `updateUIView` for any relevant state change, so a start call
+   there must be idempotent.
+4. Assign model values next to every Core Animation animation.
 
-## Bridging CA Animations with SwiftUI State
+## Moving state across the bridge
 
-### Triggering CA Animations from SwiftUI State Changes
+### Firing an animation from SwiftUI
 
-```swift
-struct PulseButton: UIViewRepresentable {
-    var pulseCount: Int // Increment to trigger a pulse
+Pass a counter in. The coordinator remembers the last value, so the view
+animates only when the counter actually changes:
 
-    func makeUIView(context: Context) -> PulseUIView {
-        PulseUIView()
-    }
+```swift
+struct Ripple: UIViewRepresentable {
+    var fireCount: Int
 
-    func updateUIView(_ uiView: PulseUIView, context: Context) {
-        // Only animate when pulseCount changes, not on every update
-        if context.coordinator.lastPulseCount != pulseCount {
-            context.coordinator.lastPulseCount = pulseCount
-            uiView.pulse()
-        }
+    final class Coordinator {
+        var lastFired = 0
     }
 
     func makeCoordinator() -> Coordinator { Coordinator() }
 
-    final class Coordinator {
-        var lastPulseCount = 0
+    func makeUIView(context: Context) -> RippleView { RippleView() }
+
+    func updateUIView(_ view: RippleView, context: Context) {
+        guard fireCount != context.coordinator.lastFired else { return }
+        context.coordinator.lastFired = fireCount
+        view.emit()
     }
 }
 
-final class PulseUIView: UIView {
-    private let pulseLayer = CAShapeLayer()
+final class RippleView: UIView {
+    private let ring = CAShapeLayer()
 
     override init(frame: CGRect) {
         super.init(frame: frame)
-        pulseLayer.fillColor = UIColor.systemBlue.withAlphaComponent(0.3).cgColor
-        layer.addSublayer(pulseLayer)
+        ring.fillColor = UIColor.systemTeal.cgColor
+        ring.opacity = 0
+        layer.addSublayer(ring)
     }
 
-    required init?(coder: NSCoder) { fatalError() }
+    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
 
     override func layoutSubviews() {
         super.layoutSubviews()
-        let size = min(bounds.width, bounds.height)
-        let rect = CGRect(
-            x: (bounds.width - size) / 2,
-            y: (bounds.height - size) / 2,
-            width: size,
-            height: size
-        )
-        pulseLayer.path = UIBezierPath(ovalIn: rect).cgPath
+        ring.frame = bounds
+        ring.path = UIBezierPath(ovalIn: bounds.insetBy(dx: bounds.width / 4, dy: bounds.height / 4)).cgPath
     }
 
-    func pulse() {
-        let scaleAnim = CABasicAnimation(keyPath: "transform.scale")
-        scaleAnim.fromValue = 1.0
-        scaleAnim.toValue = 1.5
-
-        let opacityAnim = CABasicAnimation(keyPath: "opacity")
-        opacityAnim.fromValue = 1.0
-        opacityAnim.toValue = 0.0
-
-        let group = CAAnimationGroup()
-        group.animations = [scaleAnim, opacityAnim]
-        group.duration = 0.6
-        group.timingFunction = CAMediaTimingFunction(name: .easeOut)
-
-        pulseLayer.add(group, forKey: "pulse")
+    func emit() {
+        let spread = CABasicAnimation(keyPath: "transform.scale")
+        spread.fromValue = 1.0
+        spread.toValue = 1.5
+        let fade = CABasicAnimation(keyPath: "opacity")
+        fade.fromValue = 1.0
+        fade.toValue = 0.0
+
+        let burst = CAAnimationGroup()
+        burst.animations = [spread, fade]
+        burst.duration = 0.6
+        burst.timingFunction = CAMediaTimingFunction(name: .easeOut)
+        ring.add(burst, forKey: "burst")
+        ring.opacity = 0
     }
 }
 ```
 
-### Reading CA Animation Completion in SwiftUI
+### Reporting completion back to SwiftUI
 
-Use `CAAnimationDelegate` on the Coordinator to report animation completion back to SwiftUI:
+The coordinator is the animation's delegate. It owns the link back to SwiftUI,
+so `animationDidStop` can write through the `Binding`:
 
 ```swift
-struct AnimatedBadge: UIViewRepresentable {
-    @Binding var isAnimationComplete: Bool
-
-    func makeCoordinator() -> Coordinator { Coordinator(self) }
+struct SpringyBadge: UIViewRepresentable {
+    var trigger: Int
+    @Binding var settled: Bool
 
-    func makeUIView(context: Context) -> UIView {
-        let view = UIView()
-        let badge = CAShapeLayer()
-        badge.path = UIBezierPath(ovalIn: CGRect(x: 0, y: 0, width: 40, height: 40)).cgPath
-        badge.fillColor = UIColor.systemRed.cgColor
-        badge.name = "badge"
-        view.layer.addSublayer(badge)
-        return view
-    }
-
-    func updateUIView(_ uiView: UIView, context: Context) {}
-
-    func animateIn(_ uiView: UIView) {
-        guard let badge = uiView.layer.sublayers?.first(where: { $0.name == "badge" }) else { return }
+    @MainActor
+    final class Coordinator: NSObject, CAAnimationDelegate {
+        var parent: SpringyBadge
+        var lastTrigger = 0
 
-        let spring = CASpringAnimation(perceptualDuration: 0.5, bounce: 0.3)
-        spring.keyPath = "transform.scale"
-        spring.fromValue = 0.0
-        spring.toValue = 1.0
-        spring.delegate = uiView.next as? CAAnimationDelegate
+        init(owner: SpringyBadge) { parent = owner }
 
-        badge.add(spring, forKey: "appear")
-        badge.transform = CATransform3DIdentity
+        nonisolated func animationDidStop(_ anim: CAAnimation, finished flag: Bool) {
+            guard flag else { return }
+            MainActor.assumeIsolated { parent.settled = true }
+        }
     }
 
-    final class Coordinator: NSObject, CAAnimationDelegate {
-        var parent: AnimatedBadge
+    func makeCoordinator() -> Coordinator { Coordinator(owner: self) }
 
-        init(_ parent: AnimatedBadge) { self.parent = parent }
+    func makeUIView(context: Context) -> UIView {
+        let host = UIView()
+        let dot = CAShapeLayer()
+        dot.name = "dot"
+        dot.path = CGPath(ellipseIn: CGRect(origin: .zero, size: CGSize(width: 40, height: 40)), transform: nil)
+        dot.fillColor = UIColor.systemOrange.cgColor
+        host.layer.addSublayer(dot)
+        return host
+    }
 
-        func animationDidStop(_ anim: CAAnimation, finished flag: Bool) {
-            if flag {
-                parent.isAnimationComplete = true
-            }
-        }
+    func updateUIView(_ host: UIView, context: Context) {
+        context.coordinator.parent = self            // keep the binding current
+        guard trigger != context.coordinator.lastTrigger,
+              let dot = host.layer.sublayers?.first(where: { $0.name == "dot" })
+        else { return }
+        context.coordinator.lastTrigger = trigger
+
+        let grow = CASpringAnimation(perceptualDuration: 0.4, bounce: 0.35)
+        grow.keyPath = "transform.scale"
+        grow.fromValue = 0.6
+        grow.toValue = 1.0
+        grow.delegate = context.coordinator
+        dot.add(grow, forKey: "grow")
+        dot.transform = CATransform3DIdentity
     }
 }
 ```
 
-## Performance Considerations
-
-### CA vs. SwiftUI Animation Performance
-
-| Aspect | SwiftUI Animation | Core Animation |
-|--------|------------------|----------------|
-| **Rendering** | View diffing + render tree | Direct layer manipulation |
-| **Thread** | Main thread for state, render server for compositing | Same -- render server composites |
-| **Overhead** | SwiftUI body re-evaluation per frame (for animatable) | No body re-evaluation |
-| **Best for** | Standard UI transitions | Particle effects, wave animations, complex paths |
-
-### Guidelines
-
-- **Avoid mixing CA animations and SwiftUI animations on the same property.** They use separate animation systems and will conflict.
-- **Use `CADisplayLink` sparingly.** A running display link prevents the CPU from sleeping. Always invalidate when not needed.
-- **Prefer `CAShapeLayer` for path-based animations** over redrawing in `draw(_:)`. Shape layers are GPU-accelerated.
-- **Set `shouldRasterize = true`** on complex static sublayer trees to cache them as bitmaps, but disable it during animation (rasterization prevents smooth per-frame updates).
-- **Match CA spring parameters to SwiftUI springs** using the `perceptualDuration:bounce:` initializer so animations feel consistent across the bridge boundary.
+The delegate must be `context.coordinator`. A plain `UIView` does not conform
+to `CAAnimationDelegate`, so looking one up through the responder chain gives
+`nil` and the callback never fires. Refreshing `coordinator.parent` in
+`updateUIView` keeps the binding pointing at the current state.
+
+Reset `settled` to `false` in the SwiftUI code that increments `trigger`, not
+inside `updateUIView`; writing state during a view update triggers a runtime
+warning and an extra render pass.
+
+## Performance
+
+| | SwiftUI animation | Core Animation |
+|---|---|---|
+| Mechanism | view diffing and the render tree | direct layer changes |
+| Per frame | `body` of animatable views re-evaluated as data interpolates | no `body` evaluation |
+| Best for | ordinary UI transitions | particles, waves, complex paths |
+
+Both end up composited by the render server, and both keep their state on the
+main thread.
+
+- Never animate one property from both systems. They do not coordinate and
+  will fight.
+- Use `CADisplayLink` sparingly and invalidate it the moment it is not needed.
+- For animated paths, update a `CAShapeLayer` rather than redrawing in
+  `draw(_:)`; shape layers are rendered on the GPU.
+- `shouldRasterize = true` caches a complex, static sublayer tree as a bitmap.
+  Turn it off while that tree animates, or the cache is rebuilt every frame.
+- Build Core Animation springs with `perceptualDuration:bounce:` so they feel
+  like the SwiftUI springs next to them.
+
+## Apple documentation
+
+- [CABasicAnimation](https://developer.apple.com/documentation/quartzcore/cabasicanimation)
+- [CAMediaTimingFunction](https://developer.apple.com/documentation/quartzcore/camediatimingfunction)
+- [CAKeyframeAnimation](https://developer.apple.com/documentation/quartzcore/cakeyframeanimation)
+- [CASpringAnimation](https://developer.apple.com/documentation/quartzcore/caspringanimation)
+- [CAAnimationGroup](https://developer.apple.com/documentation/quartzcore/caanimationgroup)
+- [CADisplayLink](https://developer.apple.com/documentation/quartzcore/cadisplaylink)
+- [Optimizing ProMotion refresh rates](https://developer.apple.com/documentation/quartzcore/optimizing-promotion-refresh-rates-for-iphone-13-pro-and-ipad-pro)