@mmerterden/multi-agent-pipeline 20.17.1 → 20.17.2

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

@@ -0,0 +1,185 @@
+# Scroll-driven effects: scrollTransition and visualEffect
+
+Companion to `../SKILL.md` for the `swiftui-animation` skill. Both APIs ship
+in iOS 17 (macOS 14, tvOS 17, watchOS 10, visionOS 1).
+
+## Contents
+
+1. [Which one](#1-which-one)
+2. [scrollTransition](#2-scrolltransition)
+3. [Configurations and thresholds](#3-configurations-and-thresholds)
+4. [visualEffect](#4-visualeffect)
+5. [What a VisualEffect can do](#5-what-a-visualeffect-can-do)
+6. [Concurrency: the closures are Sendable](#6-concurrency-the-closures-are-sendable)
+7. [Reduce Motion](#7-reduce-motion)
+8. [Mistakes](#8-mistakes)
+
+## 1. Which one
+
+| Need | API |
+|---|---|
+| Items fade, scale or tilt as they enter and leave the visible area of a scroll view | `scrollTransition(_:axis:transition:)` |
+| An effect that is a continuous function of the view's position or size (parallax, a header that shrinks, a stretch at the top) | `visualEffect(_:)` with the `GeometryProxy` |
+| React to scroll position in state (show a button after 300 pt) | `onScrollGeometryChange(for:of:action:)` (iOS 18), not an effect |
+
+Both apply effects that do not change layout, so they are cheap to run every
+frame and safe inside lazy stacks.
+
+## 2. scrollTransition
+
+```swift
+ScrollView {
+    LazyVStack(spacing: 16) {
+        ForEach(destinations) { destination in
+            DestinationCard(destination: destination)
+                .scrollTransition { content, phase in
+                    content
+                        .opacity(phase.isIdentity ? 1 : 0.4)
+                        .scaleEffect(phase.isIdentity ? 1 : 0.92)
+                }
+        }
+    }
+    .padding(.horizontal)
+}
+```
+
+`ScrollTransitionPhase` has three cases:
+
+- `.topLeading`: the view is entering or leaving at the top (vertical) or
+  leading (horizontal) edge.
+- `.identity`: the view is in the visible region.
+- `.bottomTrailing`: entering or leaving at the bottom or trailing edge.
+
+`phase.value` is -1 at `.topLeading`, 0 at `.identity` and 1 at
+`.bottomTrailing`, interpolated in between, so effects can scale with it:
+
+```swift
+.scrollTransition(axis: .horizontal) { content, phase in
+    content
+        .rotation3DEffect(.degrees(phase.value * -25), axis: (x: 0, y: 1, z: 0))
+        .offset(x: phase.value * -20)
+}
+```
+
+In the `.identity` phase the transition should leave the view unchanged,
+because whatever it applies there stays on for as long as the view is visible.
+
+Different behaviour per edge:
+
+```swift
+.scrollTransition(topLeading: .interactive, bottomTrailing: .animated(.smooth)) { content, phase in
+    content.opacity(phase.isIdentity ? 1 : 0)
+}
+```
+
+## 3. Configurations and thresholds
+
+| `ScrollTransitionConfiguration` | Behaviour |
+|---|---|
+| `.interactive` (default) | Tracks the scroll position directly |
+| `.interactive(timingCurve:)` | Same, with a `UnitCurve` shaping the progress |
+| `.animated`, `.animated(_:)` | Animates to the new phase when the threshold is crossed |
+| `.identity` | No transition |
+
+`.threshold(_:)` decides when a view counts as visible:
+`.visible` (any part visible), `.visible(0.9)` (90% visible), `.centered`,
+`.hidden`, and `.inset(by:)` or `.interpolated(towards:amount:)` to adjust.
+
+```swift
+.scrollTransition(.interactive.threshold(.visible(0.9))) { content, phase in
+    content.blur(radius: phase.isIdentity ? 0 : 6)
+}
+```
+
+## 4. visualEffect
+
+`visualEffect(_:)` hands the closure an empty effect and the view's
+`GeometryProxy`. Read position in the scroll view's coordinate space
+(`.scrollView`, iOS 17) and return effects:
+
+```swift
+struct ParallaxHeader: View {
+    let image: Image
+
+    var body: some View {
+        image
+            .resizable()
+            .scaledToFill()
+            .frame(height: 280)
+            .clipped()
+            .visualEffect { content, proxy in
+                let minY = proxy.frame(in: .scrollView).minY
+                let stretch = minY > 0 ? 1 + minY / 600 : 1
+                return content
+                    .offset(y: minY > 0 ? -minY / 2 : 0)
+                    .scaleEffect(x: stretch, y: stretch, anchor: .bottom)
+            }
+    }
+}
+```
+
+The same pattern fades a title as it reaches the top bar, or dims rows that
+sit under a floating control.
+
+## 5. What a VisualEffect can do
+
+Effects returned from either closure: `offset`, `scaleEffect`,
+`rotationEffect`, `rotation3DEffect`, `opacity`, `blur(radius:opaque:)`,
+`brightness`, `contrast`, `saturation`, `grayscale`, `hueRotation`,
+`blendMode`, and the shader effects `colorEffect`, `distortionEffect` and
+`layerEffect`. Frames, padding and other layout modifiers are not available,
+by design.
+
+## 6. Concurrency: the closures are Sendable
+
+Both closures are `@Sendable`. Do not read main-actor state or non-Sendable
+properties inside them; capture plain values first:
+
+```swift
+let strength = isEmphasized ? 1.0 : 0.5
+Card()
+    .scrollTransition { content, phase in
+        content.scaleEffect(1 - abs(phase.value) * 0.1 * strength)
+    }
+```
+
+## 7. Reduce Motion
+
+Scroll-linked motion is still motion. With
+`@Environment(\.accessibilityReduceMotion)` set, keep opacity changes and drop
+movement, rotation and parallax, or pass `.identity`:
+
+```swift
+@Environment(\.accessibilityReduceMotion) private var reduceMotion
+
+var body: some View {
+    let configuration: ScrollTransitionConfiguration = reduceMotion ? .identity : .interactive
+    PosterCard(poster: poster)
+        .scrollTransition(configuration) { content, phase in
+            content
+                .opacity(phase.isIdentity ? 1 : 0.5)
+                .scaleEffect(phase.isIdentity ? 1 : 0.9)
+        }
+}
+```
+
+For `visualEffect` parallax, return `content` unchanged when the setting is on;
+capture `reduceMotion` in a local constant before the closure (see section 6).
+
+## 8. Mistakes
+
+1. **Layout work in the closure.** It runs every frame; compute constants
+   outside.
+2. **A visible change in the `.identity` phase.** It stays on permanently.
+3. **Reaching for `GeometryReader` plus `@State` offsets** to build parallax.
+   `visualEffect` does it without invalidating the view on every scroll tick.
+4. **Effects that hide content or make text unreadable** at rest; transitions
+   belong to the edges.
+5. **Ignoring Reduce Motion** for 3D rotation and parallax.
+
+Sources:
+[scrollTransition(_:axis:transition:)](https://developer.apple.com/documentation/swiftui/view/scrolltransition(_:axis:transition:)),
+[ScrollTransitionPhase](https://developer.apple.com/documentation/swiftui/scrolltransitionphase),
+[ScrollTransitionConfiguration](https://developer.apple.com/documentation/swiftui/scrolltransitionconfiguration),
+[visualEffect(_:)](https://developer.apple.com/documentation/swiftui/view/visualeffect(_:)),
+[VisualEffect](https://developer.apple.com/documentation/swiftui/visualeffect).

package/pipeline/skills/shared/external/swiftui-expert-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: swiftui-expert-skill
-description: "Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, macOS-specific APIs, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns; for a findings-only review use swiftui-pro."
+description: "Write, review, or improve SwiftUI code following best practices for state, view composition, performance, macOS APIs, and iOS 26+ Liquid Glass adoption. Use when building SwiftUI features, refactoring views, reviewing code, or adopting modern patterns; for a findings-only review use swiftui-pro; for Liquid Glass APIs use swiftui-liquid-glass."
 metadata:
   source: "AvdLee/SwiftUI-Agent-Skill (MIT)"
 ---
@@ -14,7 +14,7 @@ metadata:
 - Focus on correctness and performance; do not enforce specific architectures (MVVM, VIPER, etc.)
 - Encourage separating business logic from views for testability without mandating how
 - Follow Apple's Human Interface Guidelines and API design patterns
-- Only adopt Liquid Glass when explicitly requested by the user (see `references/liquid-glass.md`)
+- Only adopt Liquid Glass when explicitly requested by the user (see `references/liquid-glass.md`; the API itself is in the `swiftui-liquid-glass` skill)
 - Present performance optimizations as suggestions, not requirements
 - Use `#available` gating with sensible fallbacks for version-specific APIs
 
@@ -60,7 +60,7 @@ Consult the reference file for each topic relevant to the current task:
 | Swift Charts | `references/charts.md` |
 | Charts accessibility | `references/charts-accessibility.md` |
 | Image optimization | `references/image-optimization.md` |
-| Liquid Glass (iOS 26+) | `references/liquid-glass.md` |
+| Liquid Glass (iOS 26+) | `references/liquid-glass.md`, then the `swiftui-liquid-glass` skill |
 | macOS scenes | `references/macos-scenes.md` |
 | macOS window styling | `references/macos-window-styling.md` |
 | macOS views | `references/macos-views.md` |
@@ -91,14 +91,14 @@ These are hard rules -- violations are always bugs:
 - `references/layout-best-practices.md` -- Layout patterns, GeometryReader alternatives
 - `references/accessibility-patterns.md` -- VoiceOver, Dynamic Type, grouping, traits
 - `references/animation-basics.md` -- Implicit/explicit animations, timing, performance
-- `references/animation-transitions.md` -- View transitions, `matchedGeometryEffect`, `Animatable`
-- `references/animation-advanced.md` -- Phase/keyframe animations (iOS 17+), `@Animatable` macro (iOS 26+)
+- `references/animation-transitions.md` -- Transition animation context, identity, `Animatable` (transition catalog: `swiftui-animation`)
+- `references/animation-advanced.md` -- Transactions, completion handlers (phase, keyframe and `@Animatable`: `swiftui-animation`)
 - `references/charts.md` -- Swift Charts marks, axes, selection, styling, Chart3D (iOS 26+)
 - `references/charts-accessibility.md` -- Charts VoiceOver, Audio Graph, fallback strategies
 - `references/sheet-navigation-patterns.md` -- Sheets, NavigationSplitView, Inspector
 - `references/scroll-patterns.md` -- ScrollViewReader, programmatic scrolling
 - `references/image-optimization.md` -- AsyncImage, downsampling, caching
-- `references/liquid-glass.md` -- iOS 26+ Liquid Glass effects and fallback patterns
+- `references/liquid-glass.md` -- When to adopt Liquid Glass; the API, fallbacks and checklist live in `swiftui-liquid-glass`
 - `references/macos-scenes.md` -- Settings, MenuBarExtra, WindowGroup, multi-window
 - `references/macos-window-styling.md` -- Toolbar styles, window sizing, Commands
 - `references/macos-views.md` -- HSplitView, Table, PasteButton, AppKit interop

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

@@ -1,13 +1,12 @@
 # SwiftUI Advanced Animations
 
-Transactions, phase animations (iOS 17+), keyframe animations (iOS 17+), completion handlers (iOS 17+), and `@Animatable` macro (iOS 26+).
+Transactions and completion handlers (iOS 17+).
+
+> Local trim: phase animations, keyframe animations and the `@Animatable` macro are maintained in the `swiftui-animation` skill, which owns SwiftUI motion. This file keeps transactions and completion handlers.
 
 ## 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)
-- [@Animatable Macro (iOS 26+)](#animatable-macro-ios-26)
 
 ---
 
@@ -94,192 +93,6 @@ withTransaction(transaction) { flag.toggle() }
 
 ---
 
-## 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.
@@ -323,52 +136,6 @@ Circle()
 
 ---
 
-## @Animatable Macro (iOS 26+)
-
-The `@Animatable` macro auto-synthesizes `animatableData` from all animatable stored properties, eliminating verbose manual conformance. Use `@AnimatableIgnored` to exclude properties that should not animate.
-
-### Before (Manual)
-
-```swift
-struct Wedge: Shape {
-    var startAngle: Angle
-    var endAngle: Angle
-    var drawClockwise: Bool
-
-    var animatableData: AnimatablePair<Double, Double> {
-        get { AnimatablePair(startAngle.radians, endAngle.radians) }
-        set {
-            startAngle = .radians(newValue.first)
-            endAngle = .radians(newValue.second)
-        }
-    }
-
-    func path(in rect: CGRect) -> Path { /* ... */ }
-}
-```
-
-### After (@Animatable)
-
-```swift
-@Animatable
-struct Wedge: Shape {
-    var startAngle: Angle
-    var endAngle: Angle
-    @AnimatableIgnored var drawClockwise: Bool
-
-    func path(in rect: CGRect) -> Path { /* ... */ }
-}
-```
-
-### When to Use
-- **Prefer `@Animatable`** for any custom `Shape`, `AnimatableModifier`, or type conforming to `Animatable` with multiple properties
-- **Use `@AnimatableIgnored`** for properties that control behavior but should not interpolate (e.g., directions, flags, identifiers)
-- The macro works with any type conforming to `Animatable`, not just `Shape`
-
-> Source: "What's new in SwiftUI" (WWDC25, session 256)
-
----
-
 ## Quick Reference
 
 ### Transactions (All iOS versions)
@@ -380,24 +147,7 @@ struct Wedge: Shape {
 ### 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
-
-### @Animatable Macro (iOS 26+)
-- Use `@Animatable` to auto-synthesize `animatableData` from stored properties
-- Use `@AnimatableIgnored` to exclude non-animatable properties
-- Replaces verbose manual `animatableData` getters/setters

package/pipeline/skills/shared/external/swiftui-expert-skill/references/animation-basics.md

@@ -1,6 +1,8 @@
 # SwiftUI Animation Basics
 
-Core animation concepts, implicit vs explicit animations, timing curves, and performance patterns.
+Core animation concepts, implicit vs explicit animations, and performance patterns.
+
+> Local trim: Timing curves and springs are maintained in the `swiftui-animation` skill, which owns SwiftUI motion. This file keeps placement, selective animation, performance and debugging.
 
 ## Table of Contents
 - [Core Concepts](#core-concepts)
@@ -8,7 +10,6 @@ Core animation concepts, implicit vs explicit animations, timing curves, and per
 - [Explicit Animations](#explicit-animations)
 - [Animation Placement](#animation-placement)
 - [Selective Animation](#selective-animation)
-- [Timing Curves](#timing-curves)
 - [Animation Performance](#animation-performance)
 - [Disabling Animations](#disabling-animations)
 - [Debugging](#debugging)
@@ -115,50 +116,6 @@ Rectangle()
 
 ---
 
-## Timing Curves
-
-### Built-in Curves
-
-| Curve | Use Case |
-|-------|----------|
-| `.spring` | Interactive elements, most UI |
-| `.easeInOut` | Appearance changes |
-| `.bouncy` | Playful feedback (iOS 17+) |
-| `.linear` | Progress indicators only |
-
-### Modifiers
-
-```swift
-.animation(.default.speed(2.0), value: flag)  // 2x faster
-.animation(.default.delay(0.5), value: flag)  // Delayed start
-.animation(.default.repeatCount(3, autoreverses: true), value: flag)
-```
-
-### Good vs Bad Timing
-
-```swift
-// GOOD - appropriate timing for interaction type
-Button("Tap") {
-    withAnimation(.spring(response: 0.3, dampingFraction: 0.7)) {
-        isActive.toggle()
-    }
-}
-.scaleEffect(isActive ? 0.95 : 1.0)
-
-// BAD - too slow for button feedback
-Button("Tap") {
-    withAnimation(.easeInOut(duration: 1.0)) {  // Way too slow!
-        isActive.toggle()
-    }
-}
-
-// BAD - linear feels robotic
-Rectangle()
-    .animation(.linear(duration: 0.5), value: isActive)  // Mechanical
-```
-
----
-
 ## Animation Performance
 
 ### Prefer Transforms Over Layout
@@ -274,7 +231,7 @@ struct AnimationDebugModifier: ViewModifier, Animatable {
 - Use `withAnimation` for event-driven animations
 - Prefer transforms over layout changes
 - Scope animations narrowly
-- Choose appropriate timing curves
+- Choose appropriate timing curves (see `swiftui-animation`)
 
 ### Don't
 - Use deprecated `.animation(_:)` without value