codexkit 1.0.0

package/.codex/skills/swiftui-expert-skill/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: swiftui-expert-skill
+description: Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns.
+version: 1.0.0
+tags: [apple, ui]
+dependencies: []
+---
+
+# SwiftUI Expert Skill
+
+## When to Use
+
+- When building, reviewing, or refactoring SwiftUI code with modern APIs and best practices.
+
+## When NOT to Use
+
+- When the task does not involve SwiftUI (e.g., UIKit-only or non-Apple platforms).
+
+## Overview
+
+Use this skill to build, review, or improve SwiftUI features with correct state management, modern API usage, Swift concurrency best practices, optimal view composition, and iOS 26+ Liquid Glass styling. Prioritize native APIs, Apple design guidance, and performance-conscious patterns. This skill focuses on facts and best practices without enforcing specific architectural patterns.
+
+## Workflow Decision Tree
+
+### 1) Review existing SwiftUI code
+
+- Check property wrapper usage against the selection guide (see `references/state-management.md`)
+- Verify modern API usage (see `references/modern-apis.md`)
+- Verify view composition follows extraction rules (see `references/view-structure.md`)
+- Check performance patterns are applied (see `references/performance-patterns.md`)
+- Verify list patterns use stable identity (see `references/list-patterns.md`)
+- Check animation patterns for correctness (see `references/animation-basics.md`, `references/animation-transitions.md`)
+- Inspect Liquid Glass usage for correctness and consistency (see `references/liquid-glass.md`)
+- Validate iOS 26+ availability handling with sensible fallbacks
+
+### 2) Improve existing SwiftUI code
+
+- Audit state management for correct wrapper selection (prefer `@Observable` over `ObservableObject`)
+- Replace deprecated APIs with modern equivalents (see `references/modern-apis.md`)
+- Extract complex views into separate subviews (see `references/view-structure.md`)
+- Refactor hot paths to minimize redundant state updates (see `references/performance-patterns.md`)
+- Ensure ForEach uses stable identity (see `references/list-patterns.md`)
+- Improve animation patterns (use value parameter, proper transitions, see `references/animation-basics.md`, `references/animation-transitions.md`)
+- Suggest image downsampling when `UIImage(data:)` is used (as optional optimization, see `references/image-optimization.md`)
+- Adopt Liquid Glass only when explicitly requested by the user
+
+### 3) Implement new SwiftUI feature
+
+- Design data flow first: identify owned vs injected state (see `references/state-management.md`)
+- Use modern APIs (no deprecated modifiers or patterns, see `references/modern-apis.md`)
+- Use `@Observable` for shared state (with `@MainActor` if not using default actor isolation)
+- Structure views for optimal diffing (extract subviews early, keep views small, see `references/view-structure.md`)
+- Separate business logic into testable models (see `references/layout-best-practices.md`)
+- Use correct animation patterns (implicit vs explicit, transitions, see `references/animation-basics.md`, `references/animation-transitions.md`, `references/animation-advanced.md`)
+- Apply glass effects after layout/appearance modifiers (see `references/liquid-glass.md`)
+- Gate iOS 26+ features with `#available` and provide fallbacks
+
+## Core Guidelines
+
+### State Management
+
+- **Always prefer `@Observable` over `ObservableObject`** for new code
+- **Mark `@Observable` classes with `@MainActor`** unless using default actor isolation
+- **Always mark `@State` and `@StateObject` as `private`** (makes dependencies clear)
+- **Never declare passed values as `@State` or `@StateObject`** (they only accept initial values)
+- Use `@State` with `@Observable` classes (not `@StateObject`)
+- `@Binding` only when child needs to **modify** parent state
+- `@Bindable` for injected `@Observable` objects needing bindings
+- Use `let` for read-only values; `var` + `.onChange()` for reactive reads
+- Legacy: `@StateObject` for owned `ObservableObject`; `@ObservedObject` for injected
+- Nested `ObservableObject` doesn't work (pass nested objects directly); `@Observable` handles nesting fine
+
+### Modern APIs
+
+- Use `foregroundStyle()` instead of `foregroundColor()`
+- Use `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
+- Use `Tab` API instead of `tabItem()`
+- Use `Button` instead of `onTapGesture()` (unless need location/count)
+- Use `NavigationStack` instead of `NavigationView`
+- Use `navigationDestination(for:)` for type-safe navigation
+- Use two-parameter or no-parameter `onChange()` variant
+- Use `ImageRenderer` for rendering SwiftUI views
+- Use `.sheet(item:)` instead of `.sheet(isPresented:)` for model-based content
+- Sheets should own their actions and call `dismiss()` internally
+- Use `ScrollViewReader` for programmatic scrolling with stable IDs
+- Avoid `UIScreen.main.bounds` for sizing
+- Avoid `GeometryReader` when alternatives exist (e.g., `containerRelativeFrame()`)
+
+### Swift Best Practices
+
+- Use modern Text formatting (`.format` parameters, not `String(format:)`)
+- Use `localizedStandardContains()` for user-input filtering (not `contains()`)
+- Prefer static member lookup (`.blue` vs `Color.blue`)
+- Use `.task` modifier for automatic cancellation of async work
+- Use `.task(id:)` for value-dependent tasks
+
+### View Composition
+
+- **Prefer modifiers over conditional views** for state changes (maintains view identity)
+- Extract complex views into separate subviews for better readability and performance
+- Keep views small for optimal performance
+- Keep view `body` simple and pure (no side effects or complex logic)
+- Use `@ViewBuilder` functions only for small, simple sections
+- Prefer `@ViewBuilder let content: Content` over closure-based content properties
+- Separate business logic into testable models (not about enforcing architectures)
+- Action handlers should reference methods, not contain inline logic
+- Use relative layout over hard-coded constants
+- Views should work in any context (don't assume screen size or presentation style)
+
+### Performance
+
+- Pass only needed values to views (avoid large "config" or "context" objects)
+- Eliminate unnecessary dependencies to reduce update fan-out
+- Check for value changes before assigning state in hot paths
+- Avoid redundant state updates in `onReceive`, `onChange`, scroll handlers
+- Minimize work in frequently executed code paths
+- Use `LazyVStack`/`LazyHStack` for large lists
+- Use stable identity for `ForEach` (never `.indices` for dynamic content)
+- Ensure constant number of views per `ForEach` element
+- Avoid inline filtering in `ForEach` (prefilter and cache)
+- Avoid `AnyView` in list rows
+- Consider POD views for fast diffing (or wrap expensive views in POD parents)
+- Suggest image downsampling when `UIImage(data:)` is encountered (as optional optimization)
+- Avoid layout thrash (deep hierarchies, excessive `GeometryReader`)
+- Gate frequent geometry updates by thresholds
+- Use `Self._printChanges()` to debug unexpected view updates
+
+### Animations
+
+- Use `.animation(_:value:)` with value parameter (deprecated version without value is too broad)
+- Use `withAnimation` for event-driven animations (button taps, gestures)
+- Prefer transforms (`offset`, `scale`, `rotation`) over layout changes (`frame`) for performance
+- Transitions require animations outside the conditional structure
+- Custom `Animatable` implementations must have explicit `animatableData`
+- Use `.phaseAnimator` for multi-step sequences (iOS 17+)
+- Use `.keyframeAnimator` for precise timing control (iOS 17+)
+- Animation completion handlers need `.transaction(value:)` for reexecution
+- Implicit animations override explicit animations (later in view tree wins)
+
+### Liquid Glass (iOS 26+)
+
+**Only adopt when explicitly requested by the user.**
+
+- Use native `glassEffect`, `GlassEffectContainer`, and glass button styles
+- Wrap multiple glass elements in `GlassEffectContainer`
+- Apply `.glassEffect()` after layout and visual modifiers
+- Use `.interactive()` only for tappable/focusable elements
+- Use `glassEffectID` with `@Namespace` for morphing transitions
+
+## Quick Reference
+
+### Property Wrapper Selection (Modern)
+
+| Wrapper     | Use When                                                              |
+| ----------- | --------------------------------------------------------------------- |
+| `@State`    | Internal view state (must be `private`), or owned `@Observable` class |
+| `@Binding`  | Child modifies parent's state                                         |
+| `@Bindable` | Injected `@Observable` needing bindings                               |
+| `let`       | Read-only value from parent                                           |
+| `var`       | Read-only value watched via `.onChange()`                             |
+
+**Legacy (Pre-iOS 17):**
+| Wrapper | Use When |
+|---------|----------|
+| `@StateObject` | View owns an `ObservableObject` (use `@State` with `@Observable` instead) |
+| `@ObservedObject` | View receives an `ObservableObject` |
+
+### Modern API Replacements
+
+| Deprecated                      | Modern Alternative                                           |
+| ------------------------------- | ------------------------------------------------------------ |
+| `foregroundColor()`             | `foregroundStyle()`                                          |
+| `cornerRadius()`                | `clipShape(.rect(cornerRadius:))`                            |
+| `tabItem()`                     | `Tab` API                                                    |
+| `onTapGesture()`                | `Button` (unless need location/count)                        |
+| `NavigationView`                | `NavigationStack`                                            |
+| `onChange(of:) { value in }`    | `onChange(of:) { old, new in }` or `onChange(of:) { }`       |
+| `fontWeight(.bold)`             | `bold()`                                                     |
+| `GeometryReader`                | `containerRelativeFrame()` or `visualEffect()`               |
+| `showsIndicators: false`        | `.scrollIndicators(.hidden)`                                 |
+| `String(format: "%.2f", value)` | `Text(value, format: .number.precision(.fractionLength(2)))` |
+| `string.contains(search)`       | `string.localizedStandardContains(search)` (for user input)  |
+
+### Liquid Glass Patterns
+
+```swift
+// Basic glass effect with fallback
+if #available(iOS 26, *) {
+    content
+        .padding()
+        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
+} else {
+    content
+        .padding()
+        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
+}
+
+// Grouped glass elements
+GlassEffectContainer(spacing: 24) {
+    HStack(spacing: 24) {
+        GlassButton1()
+        GlassButton2()
+    }
+}
+
+// Glass buttons
+Button("Confirm") { }
+    .buttonStyle(.glassProminent)
+```
+
+## Review Checklist
+
+### State Management
+
+- [ ] Using `@Observable` instead of `ObservableObject` for new code
+- [ ] `@Observable` classes marked with `@MainActor` (if needed)
+- [ ] Using `@State` with `@Observable` classes (not `@StateObject`)
+- [ ] `@State` and `@StateObject` properties are `private`
+- [ ] Passed values NOT declared as `@State` or `@StateObject`
+- [ ] `@Binding` only where child modifies parent state
+- [ ] `@Bindable` for injected `@Observable` needing bindings
+- [ ] Nested `ObservableObject` avoided (or passed directly to child views)
+
+### Modern APIs (see `references/modern-apis.md`)
+
+- [ ] Using `foregroundStyle()` instead of `foregroundColor()`
+- [ ] Using `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
+- [ ] Using `Tab` API instead of `tabItem()`
+- [ ] Using `Button` instead of `onTapGesture()` (unless need location/count)
+- [ ] Using `NavigationStack` instead of `NavigationView`
+- [ ] Avoiding `UIScreen.main.bounds`
+- [ ] Using alternatives to `GeometryReader` when possible
+- [ ] Button images include text labels for accessibility
+
+### Sheets & Navigation (see `references/sheet-navigation-patterns.md`)
+
+- [ ] Using `.sheet(item:)` for model-based sheets
+- [ ] Sheets own their actions and dismiss internally
+- [ ] Using `navigationDestination(for:)` for type-safe navigation
+
+### ScrollView (see `references/scroll-patterns.md`)
+
+- [ ] Using `ScrollViewReader` with stable IDs for programmatic scrolling
+- [ ] Using `.scrollIndicators(.hidden)` instead of initializer parameter
+
+### Text & Formatting (see `references/text-formatting.md`)
+
+- [ ] Using modern Text formatting (not `String(format:)`)
+- [ ] Using `localizedStandardContains()` for search filtering
+
+### View Structure (see `references/view-structure.md`)
+
+- [ ] Using modifiers instead of conditionals for state changes
+- [ ] Complex views extracted to separate subviews
+- [ ] Views kept small for performance
+- [ ] Container views use `@ViewBuilder let content: Content`
+
+### Performance (see `references/performance-patterns.md`)
+
+- [ ] View `body` kept simple and pure (no side effects)
+- [ ] Passing only needed values (not large config objects)
+- [ ] Eliminating unnecessary dependencies
+- [ ] State updates check for value changes before assigning
+- [ ] Hot paths minimize state updates
+- [ ] No object creation in `body`
+- [ ] Heavy computation moved out of `body`
+
+### List Patterns (see `references/list-patterns.md`)
+
+- [ ] ForEach uses stable identity (not `.indices`)
+- [ ] Constant number of views per ForEach element
+- [ ] No inline filtering in ForEach
+- [ ] No `AnyView` in list rows
+
+### Layout (see `references/layout-best-practices.md`)
+
+- [ ] Avoiding layout thrash (deep hierarchies, excessive GeometryReader)
+- [ ] Gating frequent geometry updates by thresholds
+- [ ] Business logic separated into testable models
+- [ ] Action handlers reference methods (not inline logic)
+- [ ] Using relative layout (not hard-coded constants)
+- [ ] Views work in any context (context-agnostic)
+
+### Animations (see `references/animation-basics.md`, `references/animation-transitions.md`, `references/animation-advanced.md`)
+
+- [ ] Using `.animation(_:value:)` with value parameter
+- [ ] Using `withAnimation` for event-driven animations
+- [ ] Transitions paired with animations outside conditional structure
+- [ ] Custom `Animatable` has explicit `animatableData` implementation
+- [ ] Preferring transforms over layout changes for animation performance
+- [ ] Phase animations for multi-step sequences (iOS 17+)
+- [ ] Keyframe animations for precise timing (iOS 17+)
+- [ ] Completion handlers use `.transaction(value:)` for reexecution
+
+### Liquid Glass (iOS 26+)
+
+- [ ] `#available(iOS 26, *)` with fallback for Liquid Glass
+- [ ] Multiple glass views wrapped in `GlassEffectContainer`
+- [ ] `.glassEffect()` applied after layout/appearance modifiers
+- [ ] `.interactive()` only on user-interactable elements
+- [ ] Shapes and tints consistent across related elements
+
+## References
+
+- `references/state-management.md` - Property wrappers and data flow (prefer `@Observable`)
+- `references/view-structure.md` - View composition, extraction, and container patterns
+- `references/performance-patterns.md` - Performance optimization techniques and anti-patterns
+- `references/list-patterns.md` - ForEach identity, stability, and list best practices
+- `references/layout-best-practices.md` - Layout patterns, context-agnostic views, and testability
+- `references/modern-apis.md` - Modern API usage and deprecated replacements
+- `references/animation-basics.md` - Core animation concepts, implicit/explicit animations, timing, performance
+- `references/animation-transitions.md` - Transitions, custom transitions, Animatable protocol
+- `references/animation-advanced.md` - Transactions, phase/keyframe animations (iOS 17+), completion handlers (iOS 17+)
+- `references/sheet-navigation-patterns.md` - Sheet presentation and navigation patterns
+- `references/scroll-patterns.md` - ScrollView patterns and programmatic scrolling
+- `references/text-formatting.md` - Modern text formatting and string operations
+- `references/image-optimization.md` - AsyncImage, image downsampling, and optimization
+- `references/liquid-glass.md` - iOS 26+ Liquid Glass API
+
+## Philosophy
+
+This skill focuses on **facts and best practices**, not architectural opinions:
+
+- We don't enforce specific architectures (e.g., MVVM, VIPER)
+- We do encourage separating business logic for testability
+- We prioritize modern APIs over deprecated ones
+- We emphasize thread safety with `@MainActor` and `@Observable`
+- We optimize for performance and maintainability
+- We follow Apple's Human Interface Guidelines and API design patterns

package/.codex/skills/swiftui-expert-skill/references/animation-advanced.md

@@ -0,0 +1,351 @@
+# SwiftUI Advanced Animations
+
+Transactions, phase animations (iOS 17+), keyframe animations (iOS 17+), and completion handlers (iOS 17+).
+
+## Table of Contents
+- [Transactions](#transactions)
+- [Phase Animations (iOS 17+)](#phase-animations-ios-17)
+- [Keyframe Animations (iOS 17+)](#keyframe-animations-ios-17)
+- [Animation Completion Handlers (iOS 17+)](#animation-completion-handlers-ios-17)
+
+---
+
+## Transactions
+
+The underlying mechanism for all animations in SwiftUI.
+
+### Basic Usage
+
+```swift
+// withAnimation is shorthand for withTransaction
+withAnimation(.default) { flag.toggle() }
+
+// Equivalent explicit transaction
+var transaction = Transaction(animation: .default)
+withTransaction(transaction) { flag.toggle() }
+```
+
+### The .transaction Modifier
+
+```swift
+Rectangle()
+    .frame(width: flag ? 100 : 50, height: 50)
+    .transaction { t in
+        t.animation = .default
+    }
+```
+
+**Note:** This behaves like the deprecated `.animation(_:)` without value parameter - it animates on every state change.
+
+### Animation Precedence
+
+**Implicit animations override explicit animations** (later in view tree wins).
+
+```swift
+Button("Tap") {
+    withAnimation(.linear) { flag.toggle() }
+}
+.animation(.bouncy, value: flag)  // .bouncy wins!
+```
+
+### Disabling Animations
+
+```swift
+// Prevent implicit animations from overriding
+.transaction { t in
+    t.disablesAnimations = true
+}
+
+// Remove animation entirely
+.transaction { $0.animation = nil }
+```
+
+### Custom Transaction Keys (iOS 17+)
+
+Pass metadata through transactions.
+
+```swift
+struct ChangeSourceKey: TransactionKey {
+    static let defaultValue: String = "unknown"
+}
+
+extension Transaction {
+    var changeSource: String {
+        get { self[ChangeSourceKey.self] }
+        set { self[ChangeSourceKey.self] = newValue }
+    }
+}
+
+// Set source
+var transaction = Transaction(animation: .default)
+transaction.changeSource = "server"
+withTransaction(transaction) { flag.toggle() }
+
+// Read in view tree
+.transaction { t in
+    if t.changeSource == "server" {
+        t.animation = .smooth
+    } else {
+        t.animation = .bouncy
+    }
+}
+```
+
+---
+
+## Phase Animations (iOS 17+)
+
+Cycle through discrete phases automatically. Each phase change is a separate animation.
+
+### Basic Usage
+
+```swift
+// GOOD - triggered phase animation
+Button("Shake") { trigger += 1 }
+    .phaseAnimator(
+        [0.0, -10.0, 10.0, -5.0, 5.0, 0.0],
+        trigger: trigger
+    ) { content, offset in
+        content.offset(x: offset)
+    }
+
+// Infinite loop (no trigger)
+Circle()
+    .phaseAnimator([1.0, 1.2, 1.0]) { content, scale in
+        content.scaleEffect(scale)
+    }
+```
+
+### Enum Phases (Recommended for Clarity)
+
+```swift
+// GOOD - enum phases are self-documenting
+enum BouncePhase: CaseIterable {
+    case initial, up, down, settle
+
+    var scale: CGFloat {
+        switch self {
+        case .initial: 1.0
+        case .up: 1.2
+        case .down: 0.9
+        case .settle: 1.0
+        }
+    }
+}
+
+Circle()
+    .phaseAnimator(BouncePhase.allCases, trigger: trigger) { content, phase in
+        content.scaleEffect(phase.scale)
+    }
+```
+
+### Custom Timing Per Phase
+
+```swift
+.phaseAnimator([0, -20, 20], trigger: trigger) { content, offset in
+    content.offset(x: offset)
+} animation: { phase in
+    switch phase {
+    case -20: .bouncy
+    case 20: .linear
+    default: .smooth
+    }
+}
+```
+
+### Good vs Bad
+
+```swift
+// GOOD - use phaseAnimator for multi-step sequences
+.phaseAnimator([0, -10, 10, 0], trigger: trigger) { content, offset in
+    content.offset(x: offset)
+}
+
+// BAD - manual DispatchQueue sequencing
+Button("Animate") {
+    withAnimation(.easeOut(duration: 0.1)) { offset = -10 }
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
+        withAnimation { offset = 10 }
+    }
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
+        withAnimation { offset = 0 }
+    }
+}
+```
+
+---
+
+## Keyframe Animations (iOS 17+)
+
+Precise timing control with exact values at specific times.
+
+### Basic Usage
+
+```swift
+Button("Bounce") { trigger += 1 }
+    .keyframeAnimator(
+        initialValue: AnimationValues(),
+        trigger: trigger
+    ) { content, value in
+        content
+            .scaleEffect(value.scale)
+            .offset(y: value.verticalOffset)
+    } keyframes: { _ in
+        KeyframeTrack(\.scale) {
+            SpringKeyframe(1.2, duration: 0.15)
+            SpringKeyframe(0.9, duration: 0.1)
+            SpringKeyframe(1.0, duration: 0.15)
+        }
+        KeyframeTrack(\.verticalOffset) {
+            LinearKeyframe(-20, duration: 0.15)
+            LinearKeyframe(0, duration: 0.25)
+        }
+    }
+
+struct AnimationValues {
+    var scale: CGFloat = 1.0
+    var verticalOffset: CGFloat = 0
+}
+```
+
+### Keyframe Types
+
+| Type | Behavior |
+|------|----------|
+| `CubicKeyframe` | Smooth interpolation |
+| `LinearKeyframe` | Straight-line interpolation |
+| `SpringKeyframe` | Spring physics |
+| `MoveKeyframe` | Instant jump (no interpolation) |
+
+### Multiple Synchronized Tracks
+
+Tracks run **in parallel**, each animating one property.
+
+```swift
+// GOOD - bell shake with synchronized rotation and scale
+struct BellAnimation {
+    var rotation: Double = 0
+    var scale: CGFloat = 1.0
+}
+
+Image(systemName: "bell.fill")
+    .keyframeAnimator(
+        initialValue: BellAnimation(),
+        trigger: trigger
+    ) { content, value in
+        content
+            .rotationEffect(.degrees(value.rotation))
+            .scaleEffect(value.scale)
+    } keyframes: { _ in
+        KeyframeTrack(\.rotation) {
+            CubicKeyframe(15, duration: 0.1)
+            CubicKeyframe(-15, duration: 0.1)
+            CubicKeyframe(10, duration: 0.1)
+            CubicKeyframe(-10, duration: 0.1)
+            CubicKeyframe(0, duration: 0.1)
+        }
+        KeyframeTrack(\.scale) {
+            CubicKeyframe(1.1, duration: 0.25)
+            CubicKeyframe(1.0, duration: 0.25)
+        }
+    }
+
+// BAD - manual timer-based animation
+Image(systemName: "bell.fill")
+    .onTapGesture {
+        withAnimation(.easeOut(duration: 0.1)) { rotation = 15 }
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
+            withAnimation { rotation = -15 }
+        }
+        // ... more manual timing - error prone
+    }
+```
+
+### KeyframeTimeline (iOS 17+)
+
+Query animation values directly for testing or non-SwiftUI use.
+
+```swift
+let timeline = KeyframeTimeline(initialValue: AnimationValues()) {
+    KeyframeTrack(\.scale) {
+        CubicKeyframe(1.2, duration: 0.25)
+        CubicKeyframe(1.0, duration: 0.25)
+    }
+}
+
+let midpoint = timeline.value(time: 0.25)
+print(midpoint.scale)  // Value at 0.25 seconds
+```
+
+---
+
+## Animation Completion Handlers (iOS 17+)
+
+Execute code when animations finish.
+
+### With withAnimation
+
+```swift
+// GOOD - completion with withAnimation
+Button("Animate") {
+    withAnimation(.spring) {
+        isExpanded.toggle()
+    } completion: {
+        showNextStep = true
+    }
+}
+```
+
+### With Transaction (For Reexecution)
+
+```swift
+// GOOD - completion fires on every trigger change
+Circle()
+    .scaleEffect(bounceCount % 2 == 0 ? 1.0 : 1.2)
+    .transaction(value: bounceCount) { transaction in
+        transaction.animation = .spring
+        transaction.addAnimationCompletion {
+            message = "Bounce \(bounceCount) complete"
+        }
+    }
+
+// BAD - completion only fires ONCE (no value parameter)
+Circle()
+    .scaleEffect(bounceCount % 2 == 0 ? 1.0 : 1.2)
+    .animation(.spring, value: bounceCount)
+    .transaction { transaction in  // No value!
+        transaction.addAnimationCompletion {
+            completionCount += 1  // Only fires once, ever
+        }
+    }
+```
+
+---
+
+## Quick Reference
+
+### Transactions (All iOS versions)
+- `withTransaction` is the explicit form of `withAnimation`
+- Implicit animations override explicit (later in view tree wins)
+- Use `disablesAnimations` to prevent override
+- Use `.transaction { $0.animation = nil }` to remove animation
+
+### Custom Transaction Keys (iOS 17+)
+- Pass metadata through animation system via `TransactionKey`
+
+### Phase Animations (iOS 17+)
+- Use for multi-step sequences returning to start
+- Prefer enum phases for clarity
+- Each phase change is a separate animation
+- Use `trigger` parameter for one-shot animations
+
+### Keyframe Animations (iOS 17+)
+- Use for precise timing control
+- Tracks run in parallel
+- Use `KeyframeTimeline` for testing/advanced use
+- Prefer over manual DispatchQueue timing
+
+### Completion Handlers (iOS 17+)
+- Use `withAnimation(.animation) { } completion: { }` for one-shot completion handlers
+- Use `.transaction(value:)` for handlers that should refire on every value change
+- Without `value:` parameter, completion only fires once