@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/skills/shared/external/swiftui-patterns/references/architecture-patterns.md

@@ -14,7 +14,9 @@ Default to Model-View (MV) in SwiftUI. Views are lightweight state expressions;
 - [Core Principles](#core-principles)
 - [Why Not MVVM](#why-not-mvvm)
 - [MV Pattern in Practice](#mv-pattern-in-practice)
-- [When a View Model Already Exists](#when-a-view-model-already-exists)
+- [When a ViewModel Already Exists](#when-a-viewmodel-already-exists)
+- [When a New ViewModel Is Justified](#when-a-new-viewmodel-is-justified)
+- [Environment vs. Initializer Injection](#environment-vs-initializer-injection)
 - [Testing Strategy](#testing-strategy)
 - [Source](#source)
 
@@ -148,11 +150,11 @@ struct BookListView: View {
 
 Forcing a ViewModel here means manual fetching, manual refresh, and boilerplate everywhere.
 
-### When a View Model Already Exists
+### When a ViewModel Already Exists
 
-If a view model exists in the codebase:
+If a ViewModel exists in the codebase:
 - Make it non-optional when possible
-- Pass dependencies via `init`, then forward them into the view model in the view's `init`
+- Pass dependencies via `init`, then forward them into the ViewModel in the view's `init`
 - Store as `@State` in the root view that owns it
 - Avoid `bootstrapIfNeeded` patterns
 
@@ -164,6 +166,76 @@ init(dependency: Dependency) {
 }
 ```
 
+Modern `@Observable` ViewModel with child-view binding:
+
+```swift
+@MainActor @Observable final class ProfileViewModel {
+    var name: String = ""
+    var isSaving: Bool = false
+
+    private let client: ProfileClient
+
+    init(client: ProfileClient) {
+        self.client = client
+    }
+
+    func save() async throws {
+        isSaving = true
+        defer { isSaving = false }
+        try await client.update(name: name)
+    }
+}
+
+// Owner view creates via @State
+struct ProfileScreen: View {
+    @State private var viewModel: ProfileViewModel
+
+    init(client: ProfileClient) {
+        _viewModel = State(initialValue: ProfileViewModel(client: client))
+    }
+
+    var body: some View {
+        ProfileForm(viewModel: viewModel)
+    }
+}
+
+// Child view receives and binds
+struct ProfileForm: View {
+    @Bindable var viewModel: ProfileViewModel
+
+    var body: some View {
+        TextField("Name", text: $viewModel.name)
+        Button("Save") { Task { try? await viewModel.save() } }
+            .disabled(viewModel.isSaving)
+    }
+}
+```
+
+### When a New ViewModel Is Justified
+
+The MV pattern is the default. Introduce a ViewModel only when the view would be hard to read or test without one:
+
+- **Multi-step workflows**  -  onboarding, checkout, or wizard flows where each step mutates shared draft state
+- **Non-trivial business logic**  -  validation chains, derived state from multiple sources, or transformation pipelines that don't belong in a lightweight client
+- **Coordinated async streams**  -  the view orchestrates multiple publishers or `AsyncSequence` values with interdependent state transitions
+- **Existing test surface**  -  the codebase already tests against a ViewModel interface and rewriting to MV would be high cost, low reward
+
+The bar is "this view would be hard to read and test without a ViewModel," not "I'm used to MVVM."
+
+### Environment vs. Initializer Injection
+
+**Use `@Environment` when** the dependency is shared across many views at different depths. Threading it through every intermediate initializer adds noise:
+- App-wide services: auth, network client, theme, router
+- SwiftData `ModelContext`
+- Feature-scoped stores injected at a navigation root
+
+**Use initializer parameters when** the data is specific to this view instance. Makes the view's requirements explicit and keeps previews simple:
+- The selected item, filter mode, or configuration
+- Parent-to-child data that only one view needs
+- Values known at call site that don't change
+
+Rule of thumb: if three or more intermediate views would need to accept and forward a parameter just to reach a deeply nested consumer, move it to the environment.
+
 ### Testing Strategy
 
 - Unit test services and business logic
@@ -482,5 +554,5 @@ struct MyApp: App {
 - If you need multiple variants (mock/stub), add `static func mock(...)`.
 
 ### Pitfalls
-- Don’t put UI state in the client; keep state in the store.
-- Don’t capture `self` or view state in the client closures.
+- Don't put UI state in the client; keep state in the store.
+- Don't capture `self` or view state in the client closures.

package/pipeline/skills/shared/external/swiftui-patterns/references/deprecated-migration.md

@@ -1,17 +1,18 @@
 # Deprecated API Migration Guide
 
-A comprehensive mapping of deprecated-to-modern SwiftUI and iOS APIs from iOS 15 through iOS 26. Each section shows the old pattern, the modern replacement, and migration notes. Target iOS 26 with Swift 6.2; backward-compatible to iOS 16 unless noted.
+A comprehensive mapping of deprecated-to-modern SwiftUI and iOS APIs from iOS 15 through iOS 26. Each section shows the old pattern, the modern replacement, and migration notes. Target iOS 26 with Swift 6.3; backward-compatible to iOS 16 unless noted.
 
 ## Contents
 - NavigationView to NavigationStack
 - NavigationView Sidebar to NavigationSplitView
-- ObservableObject / @Published / @StateObject to @Observable / @State
-- @ObservedObject to let / @Bindable
-- @EnvironmentObject to @Environment
+- ObservableObject / `@Published` / `@StateObject` to `@Observable` / `@State`
+- `@ObservedObject` to let / `@Bindable`
+- `@EnvironmentObject` to `@Environment`
+- foregroundColor to foregroundStyle
 - .onChange single-value to two-value
 - ActionSheet to confirmationDialog
 - Alert (Legacy) to modern .alert
-- AnyView to @ViewBuilder
+- AnyView to `@ViewBuilder`
 - .onAppear + Task to .task
 - presentationMode to dismiss
 - GeometryReader to Layout / containerRelativeFrame
@@ -19,7 +20,7 @@ A comprehensive mapping of deprecated-to-modern SwiftUI and iOS APIs from iOS 15
 - XCTest to Swift Testing
 - EditButton/.onDelete to .swipeActions
 - UIApplication.shared.open to openURL
-- @FetchRequest to @Query (SwiftData)
+- `@FetchRequest` to @Query (SwiftData)
 - some vs any return types
 - .sheet(item:) for sheet presentation
 - Color.resolve(in:) usage
@@ -132,7 +133,7 @@ NavigationSplitView explicitly models two-column and three-column layouts. Colum
 
 ---
 
-## ObservableObject / @Published / @StateObject to @Observable / @State
+## ObservableObject / `@Published` / `@StateObject` to `@Observable` / `@State`
 
 The Observation framework (iOS 17+) replaces Combine-based observation. Classes annotated with `@Observable` track property access automatically -- no `@Published` wrappers needed.
 
@@ -212,7 +213,7 @@ struct SettingsView: View {
 
 ---
 
-## @ObservedObject to let / @Bindable
+## `@ObservedObject` to let / `@Bindable`
 
 ### Before (Superseded)
 
@@ -261,7 +262,7 @@ With `@Observable`, you no longer need `@ObservedObject` to subscribe to changes
 
 ---
 
-## @EnvironmentObject to @Environment
+## `@EnvironmentObject` to `@Environment`
 
 ### Before (Superseded)
 
@@ -322,6 +323,45 @@ struct ContentView: View {
 
 ---
 
+## foregroundColor(_:) to foregroundStyle(_:)
+
+`foregroundColor(_:)` was deprecated in iOS 17. Its replacement, `foregroundStyle(_:)`, accepts any `ShapeStyle` -- not just `Color` -- enabling gradients, hierarchical styles, and materials directly.
+
+### Before (Deprecated)
+
+```swift
+Text("Hello")
+    .foregroundColor(.red)
+
+Text("Secondary")
+    .foregroundColor(.secondary)
+```
+
+### After (Modern)
+
+```swift
+Text("Hello")
+    .foregroundStyle(.red)
+
+Text("Secondary")
+    .foregroundStyle(.secondary)
+
+// Gradient -- not possible with foregroundColor
+Text("Gradient")
+    .foregroundStyle(
+        .linearGradient(colors: [.blue, .purple],
+                        startPoint: .leading, endPoint: .trailing)
+    )
+```
+
+### Migration Notes
+
+`foregroundStyle(_:)` is a drop-in replacement when passing a `Color`. The broader `ShapeStyle` conformance also accepts gradients, `.tint`, `.selection`, and hierarchical styles (`.primary`, `.secondary`, `.tertiary`, `.quaternary`). Multi-level variants `foregroundStyle(_:_:)` and `foregroundStyle(_:_:_:)` set hierarchical styles for child content in one call.
+
+**Not to be confused with** `NSAttributedString.Key.foregroundColor` -- that is a UIKit/Foundation attributed-string key used for Core Text, `NSAttributedString`, and PDF rendering. It is not deprecated and has no SwiftUI equivalent.
+
+---
+
 ## .onChange(of:perform:) to Two-Value onChange
 
 The single-value `onChange` closure was deprecated in iOS 17. The new signature provides both the old and new values.
@@ -442,7 +482,7 @@ The modern alert API accepts a `presenting` parameter to pass data directly into
 
 ---
 
-## AnyView to @ViewBuilder and Concrete Types
+## AnyView to `@ViewBuilder` and Concrete Types
 
 ### Before (Deprecated Pattern)
 
@@ -529,7 +569,7 @@ struct FeedView: View {
 
 ---
 
-## @Environment(\.presentationMode) to @Environment(\.dismiss)
+## `@Environment(\.presentationMode)` to `@Environment(\.dismiss)`
 
 ### Before (Deprecated)
 
@@ -829,7 +869,7 @@ struct ItemList: View {
 
 ---
 
-## UIApplication.shared.open to @Environment(\.openURL)
+## UIApplication.shared.open to `@Environment(\.openURL)`
 
 ### Before (Deprecated Pattern)
 
@@ -871,7 +911,7 @@ openURL(url) { accepted in
 
 ---
 
-## @FetchRequest to #Query (SwiftData)
+## `@FetchRequest` to #Query (SwiftData)
 
 Core Data's `@FetchRequest` is superseded by SwiftData's `@Query` macro when you migrate to SwiftData models.
 
@@ -963,10 +1003,13 @@ func display(_ view: some View) { ... }
 @State private var selectedItem: Item?
 @State private var showingSheet = false
 
-.onTapGesture {
+Button {
     selectedItem = item
     showingSheet = true
+} label: {
+    ItemRow(item: item)
 }
+.buttonStyle(.plain)
 .sheet(isPresented: $showingSheet) {
     if let item = selectedItem {
         DetailView(item: item)
@@ -979,9 +1022,12 @@ func display(_ view: some View) { ... }
 ```swift
 @State private var selectedItem: Item?
 
-.onTapGesture {
+Button {
     selectedItem = item
+} label: {
+    ItemRow(item: item)
 }
+.buttonStyle(.plain)
 .sheet(item: $selectedItem) { item in
     DetailView(item: item)
 }
@@ -1094,4 +1140,103 @@ Constant-range `ForEach(0..<n)` is only safe when the range never changes. For d
 
 ### Migration Notes
 
-`.navigationBarLeading` and `.navigationBarTrailing` are renamed to `.topBarLeading` and `.topBarTrailing` (iOS 16+). The new names work consistently across NavigationStack and NavigationSplitView contexts. The old names still compile but are deprecated.
+`.navigationBarLeading` and `.navigationBarTrailing` were renamed to `.topBarLeading` and `.topBarTrailing` (iOS 16+). The new names work consistently across NavigationStack and NavigationSplitView contexts. Prefer the new names for cross-platform consistency.
+
+---
+
+## cornerRadius to clipShape(.rect(cornerRadius:))
+
+`.cornerRadius(_:)` was deprecated in iOS 17.
+
+### Before (Deprecated)
+
+```swift
+RoundedRectangle(cornerRadius: 12)
+    .cornerRadius(12)
+
+Image("photo")
+    .cornerRadius(8)
+```
+
+### After (Modern)
+
+```swift
+RoundedRectangle(cornerRadius: 12)
+    .clipShape(.rect(cornerRadius: 12))
+
+Image("photo")
+    .clipShape(.rect(cornerRadius: 8))
+```
+
+### Migration Notes
+
+`clipShape(.rect(cornerRadius:))` uses `RoundedRectangle` under the hood and also supports `cornerRadii` for per-corner control (iOS 16+):
+
+```swift
+.clipShape(.rect(cornerRadii: .init(topLeading: 12, bottomTrailing: 12)))
+```
+
+---
+
+## tabItem to Tab (iOS 18+)
+
+The `tabItem` modifier approach was superseded by the `Tab` type inside `TabView` (iOS 18+).
+
+### Before (Legacy)
+
+```swift
+TabView {
+    HomeView()
+        .tabItem {
+            Label("Home", systemImage: "house")
+        }
+    SettingsView()
+        .tabItem {
+            Label("Settings", systemImage: "gear")
+        }
+}
+```
+
+### After (Modern  -  iOS 18+)
+
+```swift
+TabView {
+    Tab("Home", systemImage: "house") {
+        HomeView()
+    }
+    Tab("Settings", systemImage: "gear") {
+        SettingsView()
+    }
+}
+```
+
+### Migration Notes
+
+`Tab` provides a cleaner API and is required for the new tab sidebar on iPadOS 18+. The `tabItem` modifier still works but does not support the sidebar presentation. Use `Tab` with a `value` parameter and `@State` selection for programmatic tab switching. `TabSection` groups tabs in the sidebar.
+
+---
+
+## scrollIndicators(.hidden) Replaces showsIndicators Parameter
+
+The `showsIndicators` parameter on `ScrollView` is available but the `scrollIndicators` modifier (iOS 16+) is preferred for consistency.
+
+### Before
+
+```swift
+ScrollView(.vertical, showsIndicators: false) {
+    content
+}
+```
+
+### After (Modern)
+
+```swift
+ScrollView {
+    content
+}
+.scrollIndicators(.hidden)
+```
+
+### Migration Notes
+
+`.scrollIndicators(_:axes:)` accepts `.automatic`, `.visible`, `.hidden`, and `.never`. It also works on `List` and `TextEditor`. The `axes` parameter lets you control horizontal and vertical indicators independently.

package/pipeline/skills/shared/external/swiftui-patterns/references/design-polish.md

@@ -24,6 +24,38 @@ iOS Human Interface Guidelines patterns for layout, typography, color, accessibi
 
 ### Layout and Spacing
 
+#### Spacing Grid
+
+Omit `spacing:` on stacks to get SwiftUI's adaptive default. Only specify an explicit value when you need a deliberate departure from the default  -  and when you do, stick to the 4pt grid below.
+
+This is a common design convention, not an Apple-prescribed system, but it keeps layouts visually coherent. Avoid inventing values between grid stops.
+
+| Points | Token | Typical use |
+|--------|-------|-------------|
+| 4 | `.xxSmall` | Tight icon-to-label padding, inline badge offsets |
+| 8 | `.xSmall` | Related elements within a group, compact stack gaps |
+| 12 | `.small` | List row internal padding, label-to-secondary-text |
+| 16 | `.medium` | Standard margin, default section gap |
+| 20 | `.mediumLarge` | Comfortable breathing room between distinct controls |
+| 24 | `.large` | Section separators, card internal padding |
+| 32 | `.xLarge` | Major groupings, header-to-content gap |
+| 40 | `.xxLarge` | Large section breaks |
+| 48 | `.xxxLarge` | Hero/splash spacing, onboarding screens |
+
+```swift
+enum Spacing {
+    static let xxSmall: CGFloat = 4
+    static let xSmall: CGFloat = 8
+    static let small: CGFloat = 12
+    static let medium: CGFloat = 16
+    static let mediumLarge: CGFloat = 20
+    static let large: CGFloat = 24
+    static let xLarge: CGFloat = 32
+    static let xxLarge: CGFloat = 40
+    static let xxxLarge: CGFloat = 48
+}
+```
+
 #### Standard Margins
 
 ```swift
@@ -41,7 +73,7 @@ extension EdgeInsets {
 
 ```swift
 ScrollView {
-    LazyVStack(spacing: 16) {
+    LazyVStack {
         ForEach(items) { item in
             ItemRow(item: item)
         }
@@ -88,10 +120,10 @@ Use system font styles for automatic Dynamic Type support:
 
 | Style | Size | Weight | Usage |
 |-------|------|--------|-------|
-| `.largeTitle` | 34pt | Bold | Screen titles |
-| `.title` | 28pt | Semibold | Section headers |
-| `.title2` | 22pt | Semibold | Sub-section headers |
-| `.title3` | 20pt | Semibold | Group headers |
+| `.largeTitle` | 34pt | Regular | Screen titles |
+| `.title` | 28pt | Regular | Section headers |
+| `.title2` | 22pt | Regular | Sub-section headers |
+| `.title3` | 20pt | Regular | Group headers |
 | `.headline` | 17pt | Semibold | Row titles |
 | `.body` | 17pt | Regular | Primary content |
 | `.callout` | 16pt | Regular | Secondary content |
@@ -140,7 +172,7 @@ ContentView()
     .tint(.blue)
 ```
 
-Use `Color.accentColor` for interactive elements and `Color.red` for destructive actions.
+Use `.tint(...)` or `.foregroundStyle(.tint)` for interactive elements and `Color.red` for destructive actions.
 
 ### Navigation Patterns
 
@@ -201,17 +233,23 @@ Use `TabView` with a `NavigationStack` per tab. See the `swiftui-navigation` ski
 
 #### Haptic Feedback
 
-```swift
-// Impact
-UIImpactFeedbackGenerator(style: .medium).impactOccurred()
+Prefer SwiftUI's `sensoryFeedback(_:trigger:)` for state-driven feedback in SwiftUI views.
 
-// Notification
-UINotificationFeedbackGenerator().notificationOccurred(.success)
+```swift
+Button("Save") {
+    didSave.toggle()
+}
+.sensoryFeedback(.success, trigger: didSave)
 
-// Selection
-UISelectionFeedbackGenerator().selectionChanged()
+Picker("Sort", selection: $sortOrder) {
+    Text("Recent").tag(SortOrder.recent)
+    Text("Popular").tag(SortOrder.popular)
+}
+.sensoryFeedback(.selection, trigger: sortOrder)
 ```
 
+Use the UIKit generators only when you need imperative feedback from UIKit or non-SwiftUI integration points.
+
 See the Haptics section below for structured patterns.
 
 ### Accessibility
@@ -219,7 +257,7 @@ See the Haptics section below for structured patterns.
 #### VoiceOver Support
 
 ```swift
-VStack(alignment: .leading, spacing: 8) {
+VStack(alignment: .leading) {
     Text(item.title).font(.headline)
     Text(item.subtitle).font(.subheadline).foregroundStyle(.secondary)
     HStack {
@@ -243,7 +281,7 @@ Adapt layout for accessibility sizes:
 
 var body: some View {
     if dynamicTypeSize.isAccessibilitySize {
-        VStack(alignment: .leading, spacing: 12) {
+        VStack(alignment: .leading) {
             leadingContent
             trailingContent
         }
@@ -295,7 +333,7 @@ Provide a clean, scalable theming approach that keeps view code semantic and con
 - Inject theme at the app root and read it via `@Environment(Theme.self)` in views.
 - Prefer semantic colors (`primaryBackground`, `secondaryBackground`, `label`, `tint`) instead of raw colors.
 - Keep user-facing theme controls in a dedicated settings screen.
-- Apply Dynamic Type scaling through custom fonts or `.font(.scaled...)`.
+- Apply Dynamic Type scaling through text styles, `Font.custom(_:size:relativeTo:)`, or `@ScaledMetric` for numeric layout values.
 
 ### Example: Theme object
 
@@ -352,8 +390,8 @@ struct ProfileView: View {
 ### Pitfalls
 
 - Avoid sprinkling raw `Color` values in views; it breaks consistency.
-- Do not tie theme to a single view’s local state.
-- Avoid using `@Environment(\\.colorScheme)` as the only theme control; it should complement your theme.
+- Do not tie theme to a single view's local state.
+- Avoid using `@Environment(\.colorScheme)` as the only theme control; it should complement your theme.
 
 ## Haptics
 
@@ -363,11 +401,29 @@ Use haptics sparingly to reinforce user actions (tab selection, refresh, success
 
 ### Core patterns
 
-- Centralize haptic triggers in a `HapticManager` or similar utility.
+- Prefer `sensoryFeedback(_:trigger:)` in SwiftUI views for state-driven feedback.
+- Centralize imperative feedback in a `HapticManager` only when UIKit interop or non-view code requires it.
 - Gate haptics behind user preferences and hardware support.
 - Use distinct types for different UX moments (selection vs. notification vs. refresh).
+- Escalate to Core Haptics only for custom patterns that exceed SwiftUI's built-in feedback types.
+
+### SwiftUI-first pattern
+
+```swift
+struct SaveButton: View {
+  @State private var saveToken = 0
+
+  var body: some View {
+    Button("Save") {
+      persistChanges()
+      saveToken += 1
+    }
+    .sensoryFeedback(.success, trigger: saveToken)
+  }
+}
+```
 
-### Example: simple haptic manager
+### UIKit interop pattern
 
 ```swift
 @MainActor
@@ -481,8 +537,8 @@ final class CoreHapticManager {
 
 Key lifecycle rules:
 - Call `engine.start()` before playing any patterns.
-- Handle `stoppedHandler` — the system can stop the engine when your app moves to the background or during audio interruptions.
-- Handle `resetHandler` — restart the engine when the system resets it.
+- Handle `stoppedHandler`  -  the system can stop the engine when your app moves to the background or during audio interruptions.
+- Handle `resetHandler`  -  restart the engine when the system resets it.
 - Call `engine.stop()` when haptics are no longer needed to save battery.
 
 #### CHHapticPattern and CHHapticEvent
@@ -516,7 +572,7 @@ func playTransientTap() throws {
 | `.audioContinuous` | Sustained audio tone |
 | `.audioCustom` | Play a custom audio resource |
 
-**Common parameters:** `.hapticIntensity` (0–1), `.hapticSharpness` (0–1), `.attackTime`, `.decayTime`, `.releaseTime`.
+**Common parameters:** `.hapticIntensity` (0-1), `.hapticSharpness` (0-1), `.attackTime`, `.decayTime`, `.releaseTime`.
 
 #### Playing patterns with CHHapticPatternPlayer
 
@@ -645,7 +701,7 @@ struct ToggleBadge: View {
 
 ### Pitfalls
 
-- Don’t use unstable IDs; it breaks the transition.
+- Don't use unstable IDs; it breaks the transition.
 - Avoid mismatched shapes (e.g., square to circle) unless the design expects it.
 
 ## Loading and Placeholders
@@ -666,9 +722,9 @@ Use this when a view needs a consistent loading state (skeletons, redaction, emp
 
 ### Pitfalls
 
-- Don’t animate layout shifts during redaction; keep frames stable.
+- Don't animate layout shifts during redaction; keep frames stable.
 - Avoid nesting multiple spinners; use one loading indicator per section.
-- Keep placeholder count small (3–6) to reduce jank on low-end devices.
+- Keep placeholder count small (3-6) to reduce jank on low-end devices.
 
 ### Minimal usage
 
@@ -689,6 +745,8 @@ VStack {
 
 ## Focus Handling
 
+This file covers basic form-focus patterns only. For directional focus, focus sections, scene-focused values, and `UIFocusGuide`, see the `focus-engine` skill.
+
 ### Intent
 
 Use `@FocusState` to control keyboard focus, chain fields, and coordinate focus across complex forms.
@@ -776,5 +834,5 @@ struct PollView: View {
 
 ### Pitfalls
 
-- Don’t store focus state in shared objects; it is view-local.
+- Don't store focus state in shared objects; it is view-local.
 - Avoid aggressive focus changes during animation; delay if needed.