@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/swiftui-layout-components/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: swiftui-layout-components
+description: "Build SwiftUI layouts using stacks, grids, lists, scroll views, forms, and controls. Covers VStack/HStack/ZStack, LazyVGrid/LazyHGrid, List with sections and swipe actions, ScrollView with ScrollViewReader, Form with validation, Toggle/Picker/Slider, .searchable, and overlay patterns. Use when building data-driven layouts, collection views, settings screens, search interfaces, or transient overlay UI."
+---
+
+# SwiftUI Layout & Components
+
+Layout and component patterns for SwiftUI apps targeting iOS 26+ with Swift 6.2. Covers stack and grid layouts, list patterns, scroll views, forms, controls, search, and overlays. Patterns are backward-compatible to iOS 17 unless noted.
+
+## Contents
+
+- [Layout Fundamentals](#layout-fundamentals)
+- [Grid Layouts](#grid-layouts)
+- [List Patterns](#list-patterns)
+- [ScrollView](#scrollview)
+- [Form and Controls](#form-and-controls)
+- [Searchable](#searchable)
+- [Overlay and Presentation](#overlay-and-presentation)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+## Layout Fundamentals
+
+### Standard Stacks
+
+Use `VStack`, `HStack`, and `ZStack` for small, fixed-size content. They render all children immediately.
+
+```swift
+VStack(alignment: .leading, spacing: 8) {
+    Text(title).font(.headline)
+    Text(subtitle).font(.subheadline).foregroundStyle(.secondary)
+}
+```
+
+### Lazy Stacks
+
+Use `LazyVStack` and `LazyHStack` inside `ScrollView` for large or dynamic collections. They create child views on demand as they scroll into view.
+
+```swift
+ScrollView {
+    LazyVStack(spacing: 12) {
+        ForEach(items) { item in
+            ItemRow(item: item)
+        }
+    }
+    .padding(.horizontal)
+}
+```
+
+**When to use which:**
+- **Non-lazy stacks:** Small, fixed content (headers, toolbars, forms with few fields)
+- **Lazy stacks:** Large or unknown-size collections, feeds, chat messages
+
+## Grid Layouts
+
+Use `LazyVGrid` for icon pickers, media galleries, and dense visual selections. Use `.adaptive` columns for layouts that scale across device sizes, or `.flexible` columns for a fixed column count.
+
+```swift
+// Adaptive grid -- columns adjust to fit
+let columns = [GridItem(.adaptive(minimum: 120, maximum: 1024))]
+
+LazyVGrid(columns: columns, spacing: 6) {
+    ForEach(items) { item in
+        ThumbnailView(item: item)
+            .aspectRatio(1, contentMode: .fit)
+    }
+}
+```
+
+```swift
+// Fixed 3-column grid
+let columns = Array(repeating: GridItem(.flexible(minimum: 100), spacing: 4), count: 3)
+
+LazyVGrid(columns: columns, spacing: 4) {
+    ForEach(items) { item in
+        ThumbnailView(item: item)
+    }
+}
+```
+
+Use `.aspectRatio` for cell sizing. Never place `GeometryReader` inside lazy containers -- it forces eager measurement and defeats lazy loading. Use `.onGeometryChange` (iOS 18+) if you need to read dimensions.
+
+See `references/grids.md` for full grid patterns and design choices.
+
+## List Patterns
+
+Use `List` for feed-style content and settings rows where built-in row reuse, selection, and accessibility matter.
+
+```swift
+List {
+    Section("General") {
+        NavigationLink("Display") { DisplaySettingsView() }
+        NavigationLink("Haptics") { HapticsSettingsView() }
+    }
+    Section("Account") {
+        Button("Sign Out", role: .destructive) { }
+    }
+}
+.listStyle(.insetGrouped)
+```
+
+**Key patterns:**
+- `.listStyle(.plain)` for feed layouts, `.insetGrouped` for settings
+- `.scrollContentBackground(.hidden)` + custom background for themed surfaces
+- `.listRowInsets(...)` and `.listRowSeparator(.hidden)` for spacing and separator control
+- Pair with `ScrollViewReader` for scroll-to-top or jump-to-id
+- Use `.refreshable { }` for pull-to-refresh feeds
+- Use `.contentShape(Rectangle())` on rows that should be tappable end-to-end
+
+**iOS 26:** Apply `.scrollEdgeEffectStyle(.soft, for: .top)` for modern scroll edge effects.
+
+See `references/list.md` for full list patterns including feed lists with scroll-to-top.
+
+## ScrollView
+
+Use `ScrollView` with lazy stacks when you need custom layout, mixed content, or horizontal scrolling.
+
+```swift
+ScrollView(.horizontal, showsIndicators: false) {
+    LazyHStack(spacing: 8) {
+        ForEach(chips) { chip in
+            ChipView(chip: chip)
+        }
+    }
+}
+```
+
+**ScrollViewReader:** Enables programmatic scrolling to specific items.
+
+```swift
+ScrollViewReader { proxy in
+    ScrollView {
+        LazyVStack {
+            ForEach(messages) { message in
+                MessageRow(message: message).id(message.id)
+            }
+        }
+    }
+    .onChange(of: messages.last?.id) { _, newValue in
+        if let id = newValue {
+            withAnimation { proxy.scrollTo(id, anchor: .bottom) }
+        }
+    }
+}
+```
+
+**`safeAreaInset(edge:)`** pins content (input bars, toolbars) above the keyboard without affecting scroll layout.
+
+**iOS 26 additions:**
+- `.scrollEdgeEffectStyle(.soft, for: .top)` -- fading edge effect
+- `.backgroundExtensionEffect()` -- mirror/blur at safe area edges (use sparingly, one per screen)
+- `.safeAreaBar(edge:)` -- attach bar views that integrate with scroll effects
+
+See `references/scrollview.md` for full scroll patterns and iOS 26 edge effects.
+
+## Form and Controls
+
+### Form
+
+Use `Form` for structured settings and input screens. Group related controls into `Section` blocks.
+
+```swift
+Form {
+    Section("Notifications") {
+        Toggle("Mentions", isOn: $prefs.mentions)
+        Toggle("Follows", isOn: $prefs.follows)
+    }
+    Section("Appearance") {
+        Picker("Theme", selection: $theme) {
+            ForEach(Theme.allCases, id: \.self) { Text($0.title).tag($0) }
+        }
+        Slider(value: $fontScale, in: 0.5...1.5, step: 0.1)
+    }
+}
+.formStyle(.grouped)
+.scrollContentBackground(.hidden)
+```
+
+Use `@FocusState` to manage keyboard focus in input-heavy forms. Wrap in `NavigationStack` only when presented standalone or in a sheet.
+
+### Controls
+
+| Control | Usage |
+|---------|-------|
+| `Toggle` | Boolean preferences |
+| `Picker` | Discrete choices; `.segmented` for 2-4 options |
+| `Slider` | Numeric ranges with visible value label |
+| `DatePicker` | Date/time selection |
+| `TextField` | Text input with `.keyboardType`, `.textInputAutocapitalization` |
+
+Bind controls directly to `@State`, `@Binding`, or `@AppStorage`. Group related controls in `Form` sections. Use `.disabled(...)` to reflect locked or inherited settings. Use `Label` inside toggles to combine icon + text when it adds clarity.
+
+```swift
+// Toggle sections
+Form {
+  Section("Notifications") {
+    Toggle("Mentions", isOn: $preferences.notificationsMentionsEnabled)
+    Toggle("Follows", isOn: $preferences.notificationsFollowsEnabled)
+  }
+}
+
+// Slider with value text
+Section("Font Size") {
+  Slider(value: $fontSizeScale, in: 0.5...1.5, step: 0.1)
+  Text("Scale: \(String(format: "%.1f", fontSizeScale))")
+}
+
+// Picker for enums
+Picker("Default Visibility", selection: $visibility) {
+  ForEach(Visibility.allCases, id: \.self) { option in
+    Text(option.title).tag(option)
+  }
+}
+```
+
+Avoid `.pickerStyle(.segmented)` for large sets; use menu or inline styles. Don't hide labels for sliders; always show context.
+
+See `references/form.md` for full form examples.
+
+## Searchable
+
+Add native search UI with `.searchable`. Use `.searchScopes` for multiple modes and `.task(id:)` for debounced async results.
+
+```swift
+@MainActor
+struct ExploreView: View {
+  @State private var searchQuery = ""
+  @State private var searchScope: SearchScope = .all
+  @State private var isSearching = false
+  @State private var results: [SearchResult] = []
+
+  var body: some View {
+    List {
+      if isSearching {
+        ProgressView()
+      } else {
+        ForEach(results) { result in
+          SearchRow(result: result)
+        }
+      }
+    }
+    .searchable(
+      text: $searchQuery,
+      placement: .navigationBarDrawer(displayMode: .always),
+      prompt: Text("Search")
+    )
+    .searchScopes($searchScope) {
+      ForEach(SearchScope.allCases, id: \.self) { scope in
+        Text(scope.title)
+      }
+    }
+    .task(id: searchQuery) {
+      await runSearch()
+    }
+  }
+
+  private func runSearch() async {
+    guard !searchQuery.isEmpty else {
+      results = []
+      return
+    }
+    isSearching = true
+    defer { isSearching = false }
+    try? await Task.sleep(for: .milliseconds(250))
+    results = await fetchResults(query: searchQuery, scope: searchScope)
+  }
+}
+```
+
+Show a placeholder when search is empty. Debounce input to avoid overfetching. Keep search state local to the view. Avoid running searches for empty strings.
+
+## Overlay and Presentation
+
+Use `.overlay(alignment:)` for transient UI (toasts, banners) without affecting layout.
+
+```swift
+struct AppRootView: View {
+  @State private var toast: Toast?
+
+  var body: some View {
+    content
+      .overlay(alignment: .top) {
+        if let toast {
+          ToastView(toast: toast)
+            .transition(.move(edge: .top).combined(with: .opacity))
+            .onAppear {
+              Task {
+                try? await Task.sleep(for: .seconds(2))
+                withAnimation { self.toast = nil }
+              }
+            }
+        }
+      }
+  }
+}
+```
+
+Prefer overlays for transient UI rather than embedding in layout stacks. Use transitions and short auto-dismiss timers. Keep overlays aligned to a clear edge (`.top` or `.bottom`). Avoid overlays that block all interaction unless explicitly needed. Don't stack many overlays; use a queue or replace the current toast.
+
+**fullScreenCover:** Use `.fullScreenCover(item:)` for immersive presentations that cover the entire screen (media viewers, onboarding flows).
+
+## Common Mistakes
+
+1. Using non-lazy stacks for large collections -- causes all children to render immediately
+2. Placing `GeometryReader` inside lazy containers -- defeats lazy loading
+3. Using array indices as `ForEach` IDs -- causes incorrect diffing and UI bugs
+4. Nesting scroll views of the same axis -- causes gesture conflicts
+5. Heavy custom layouts inside `List` rows -- use `ScrollView` + `LazyVStack` instead
+6. Missing `.contentShape(Rectangle())` on tappable rows -- tap area is text-only
+7. Hard-coding frame dimensions for sheets -- use `.presentationSizing` instead
+8. Running searches on empty strings -- always guard against empty queries
+9. Mixing `List` and `ScrollView` in the same hierarchy -- gesture conflicts
+10. Using `.pickerStyle(.segmented)` for large option sets -- use menu or inline styles
+
+## Review Checklist
+
+- [ ] `LazyVStack`/`LazyHStack` used for large or dynamic collections
+- [ ] Stable `Identifiable` IDs on all `ForEach` items (not array indices)
+- [ ] No `GeometryReader` inside lazy containers
+- [ ] `List` style matches context (`.plain` for feeds, `.insetGrouped` for settings)
+- [ ] `Form` used for structured input screens (not custom stacks)
+- [ ] `.searchable` debounces input with `.task(id:)`
+- [ ] `.refreshable` added where data source supports pull-to-refresh
+- [ ] Overlays use transitions and auto-dismiss timers
+- [ ] `.contentShape(Rectangle())` on tappable rows
+- [ ] `@FocusState` manages keyboard focus in forms
+
+## References
+
+- Grid patterns: `references/grids.md`
+- List and section patterns: `references/list.md`
+- ScrollView and lazy stacks: `references/scrollview.md`
+- Form patterns: `references/form.md`
+- Architecture and state management: see `swiftui-patterns` skill
+- Navigation patterns: see `swiftui-navigation` skill

package/pipeline/skills/shared/external/swiftui-layout-components/references/form.md

@@ -0,0 +1,97 @@
+# Form
+
+## Intent
+
+Use `Form` for structured settings, grouped inputs, and action rows. This pattern keeps layout, spacing, and accessibility consistent for data entry screens.
+
+## Core patterns
+
+- Wrap the form in a `NavigationStack` only when it is presented in a sheet or standalone view without an existing navigation context.
+- Group related controls into `Section` blocks.
+- Use `.scrollContentBackground(.hidden)` plus a custom background color when you need design-system colors.
+- Apply `.formStyle(.grouped)` for grouped styling when appropriate.
+- Use `@FocusState` to manage keyboard focus in input-heavy forms.
+
+## Example: settings-style form
+
+```swift
+@MainActor
+struct SettingsView: View {
+  @Environment(Theme.self) private var theme
+
+  var body: some View {
+    NavigationStack {
+      Form {
+        Section("General") {
+          NavigationLink("Display") { DisplaySettingsView() }
+          NavigationLink("Haptics") { HapticsSettingsView() }
+        }
+
+        Section("Account") {
+          Button("Edit profile") { /* open sheet */ }
+            .buttonStyle(.plain)
+        }
+        .listRowBackground(theme.primaryBackgroundColor)
+      }
+      .navigationTitle("Settings")
+      .navigationBarTitleDisplayMode(.inline)
+      .scrollContentBackground(.hidden)
+      .background(theme.secondaryBackgroundColor)
+    }
+  }
+}
+```
+
+## Example: modal form with validation
+
+```swift
+@MainActor
+struct AddRemoteServerView: View {
+  @Environment(\.dismiss) private var dismiss
+  @Environment(Theme.self) private var theme
+
+  @State private var server: String = ""
+  @State private var isValid = false
+  @FocusState private var isServerFieldFocused: Bool
+
+  var body: some View {
+    NavigationStack {
+      Form {
+        TextField("Server URL", text: $server)
+          .keyboardType(.URL)
+          .textInputAutocapitalization(.never)
+          .autocorrectionDisabled()
+          .focused($isServerFieldFocused)
+          .listRowBackground(theme.primaryBackgroundColor)
+
+        Button("Add") {
+          guard isValid else { return }
+          dismiss()
+        }
+        .disabled(!isValid)
+        .listRowBackground(theme.primaryBackgroundColor)
+      }
+      .formStyle(.grouped)
+      .navigationTitle("Add Server")
+      .navigationBarTitleDisplayMode(.inline)
+      .scrollContentBackground(.hidden)
+      .background(theme.secondaryBackgroundColor)
+      .scrollDismissesKeyboard(.immediately)
+      .toolbar { CancelToolbarItem() }
+      .onAppear { isServerFieldFocused = true }
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Prefer `Form` over custom stacks for settings and input screens.
+- Keep rows tappable by using `.contentShape(Rectangle())` and `.buttonStyle(.plain)` on row buttons.
+- Use list row backgrounds to keep section styling consistent with your theme.
+
+## Pitfalls
+
+- Avoid heavy custom layouts inside a `Form`; it can lead to spacing issues.
+- If you need highly custom layouts, prefer `ScrollView` + `VStack`.
+- Don’t mix multiple background strategies; pick either default Form styling or custom colors.

package/pipeline/skills/shared/external/swiftui-layout-components/references/grids.md

@@ -0,0 +1,69 @@
+# Grids
+
+## Intent
+
+Use `LazyVGrid` for icon pickers, media galleries, and dense visual selections where items align in columns.
+
+## Core patterns
+
+- Use `.adaptive` columns for layouts that should scale across device sizes.
+- Use multiple `.flexible` columns when you want a fixed column count.
+- Keep spacing consistent and small to avoid uneven gutters.
+- Use `.aspectRatio(1, contentMode: .fit)` on grid cells for square thumbnails. Avoid `GeometryReader` inside lazy containers (it defeats lazy layout and causes performance issues).
+
+## Example: adaptive icon grid
+
+```swift
+let columns = [GridItem(.adaptive(minimum: 120, maximum: 1024))]
+
+LazyVGrid(columns: columns, spacing: 6) {
+  ForEach(icons) { icon in
+    Button {
+      select(icon)
+    } label: {
+      ZStack(alignment: .bottomTrailing) {
+        Image(icon.previewName)
+          .resizable()
+          .aspectRatio(contentMode: .fit)
+          .cornerRadius(6)
+        if icon.isSelected {
+          Image(systemName: "checkmark.seal.fill")
+            .padding(4)
+            .tint(.green)
+        }
+      }
+    }
+    .buttonStyle(.plain)
+  }
+}
+```
+
+## Example: fixed 3-column media grid
+
+```swift
+LazyVGrid(
+  columns: [
+    .init(.flexible(minimum: 100), spacing: 4),
+    .init(.flexible(minimum: 100), spacing: 4),
+    .init(.flexible(minimum: 100), spacing: 4),
+  ],
+  spacing: 4
+) {
+  ForEach(items) { item in
+    ThumbnailView(item: item)
+      .aspectRatio(1, contentMode: .fit)
+  }
+}
+```
+
+## Design choices to keep
+
+- Use `LazyVGrid` for large collections; avoid non-lazy grids for big sets.
+- Keep tap targets full-bleed using `.contentShape(Rectangle())` when needed.
+- Prefer adaptive grids for settings pickers and flexible layouts.
+
+## Pitfalls
+
+- Avoid heavy overlays in every grid cell; it can be expensive.
+- Don’t nest grids inside other grids without a clear reason.
+- **Never place `GeometryReader` inside lazy containers** (`LazyVGrid`, `LazyHGrid`, `LazyVStack`, `LazyHStack`). It forces eager measurement and defeats lazy loading. Use `.aspectRatio` for sizing, or `.onGeometryChange` (iOS 18+) if you need to read dimensions.

package/pipeline/skills/shared/external/swiftui-layout-components/references/list.md

@@ -0,0 +1,99 @@
+# List and Section
+
+## Intent
+
+Use `List` for feed-style content and settings-style rows where built-in row reuse, selection, and accessibility matter.
+
+## Core patterns
+
+- Prefer `List` for long, vertically scrolling content with repeated rows.
+- Use `Section` headers to group related rows.
+- Pair with `ScrollViewReader` when you need scroll-to-top or jump-to-id.
+- Use `.listStyle(.plain)` for modern feed layouts.
+- Use `.listStyle(.grouped)` for multi-section discovery/search pages where section grouping helps.
+- Apply `.scrollContentBackground(.hidden)` + a custom background when you need a themed surface.
+- Use `.listRowInsets(...)` and `.listRowSeparator(.hidden)` to tune row spacing and separators.
+- Use `.environment(\\.defaultMinListRowHeight, ...)` to control dense list layouts.
+
+## Example: feed list with scroll-to-top
+
+```swift
+@MainActor
+struct TimelineListView: View {
+  @Environment(\.selectedTabScrollToTop) private var selectedTabScrollToTop
+  @State private var scrollToId: String?
+
+  var body: some View {
+    ScrollViewReader { proxy in
+      List {
+        ForEach(items) { item in
+          TimelineRow(item: item)
+            .id(item.id)
+            .listRowInsets(.init(top: 12, leading: 16, bottom: 6, trailing: 16))
+            .listRowSeparator(.hidden)
+        }
+      }
+      .listStyle(.plain)
+      .environment(\\.defaultMinListRowHeight, 1)
+      .onChange(of: scrollToId) { _, newValue in
+        if let newValue {
+          proxy.scrollTo(newValue, anchor: .top)
+          scrollToId = nil
+        }
+      }
+      .onChange(of: selectedTabScrollToTop) { _, newValue in
+        if newValue == 0 {
+          withAnimation {
+            proxy.scrollTo(ScrollToView.Constants.scrollToTop, anchor: .top)
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: settings-style list
+
+```swift
+@MainActor
+struct SettingsView: View {
+  var body: some View {
+    List {
+      Section("General") {
+        NavigationLink("Display") { DisplaySettingsView() }
+        NavigationLink("Haptics") { HapticsSettingsView() }
+      }
+      Section("Account") {
+        Button("Sign Out", role: .destructive) {}
+      }
+    }
+    .listStyle(.insetGrouped)
+  }
+}
+```
+
+## Design choices to keep
+
+- Use `List` for dynamic feeds, settings, and any UI where row semantics help.
+- Use stable IDs for rows to keep animations and scroll positioning reliable.
+- Prefer `.contentShape(Rectangle())` on rows that should be tappable end-to-end.
+- Use `.refreshable` for pull-to-refresh feeds when the data source supports it.
+
+## iOS 26 Scroll Edge Effects
+
+Apply edge effects to lists for modern scroll behavior:
+
+```swift
+List {
+    // rows
+}
+.scrollEdgeEffectStyle(.soft, for: .top)
+```
+
+See `scrollview.md` for the full scroll edge effect and `backgroundExtensionEffect()` API reference.
+
+## Pitfalls
+
+- Avoid heavy custom layouts inside a `List` row; use `ScrollView` + `LazyVStack` instead.
+- Be careful mixing `List` and nested `ScrollView`; it can cause gesture conflicts.