@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/swiftui-view-refactor/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: swiftui-view-refactor
+description: Refactor SwiftUI views into smaller components with stable, explicit data flow.
+risk: safe
+source: "Dimillian/Skills (MIT)"
+date_added: "2026-03-25"
+---
+
+# SwiftUI View Refactor
+
+## Overview
+Refactor SwiftUI views toward small, explicit, stable view types. Default to vanilla SwiftUI: local state in the view, shared dependencies in the environment, business logic in services/models, and view models only when the request or existing code clearly requires one.
+
+## When to Use
+
+- When cleaning up a large SwiftUI view or splitting long `body` implementations.
+- When you need smaller subviews, explicit dependency injection, or better Observation usage.
+
+## Core Guidelines
+
+### 1) View ordering (top → bottom)
+- Enforce this ordering unless the existing file has a stronger local convention you must preserve.
+- Environment
+- `private`/`public` `let`
+- `@State` / other stored properties
+- computed `var` (non-view)
+- `init`
+- `body`
+- computed view builders / other view helpers
+- helper / async functions
+
+### 2) Default to MV, not MVVM
+- Views should be lightweight state expressions and orchestration points, not containers for business logic.
+- Favor `@State`, `@Environment`, `@Query`, `.task`, `.task(id:)`, and `onChange` before reaching for a view model.
+- Inject services and shared models via `@Environment`; keep domain logic in services/models, not in the view body.
+- Do not introduce a view model just to mirror local view state or wrap environment dependencies.
+- If a screen is getting large, split the UI into subviews before inventing a new view model layer.
+
+### 3) Strongly prefer dedicated subview types over computed `some View` helpers
+- Flag `body` properties that are longer than roughly one screen or contain multiple logical sections.
+- Prefer extracting dedicated `View` types for non-trivial sections, especially when they have state, async work, branching, or deserve their own preview.
+- Keep computed `some View` helpers rare and small. Do not build an entire screen out of `private var header: some View`-style fragments.
+- Pass small, explicit inputs (data, bindings, callbacks) into extracted subviews instead of handing down the entire parent state.
+- If an extracted subview becomes reusable or independently meaningful, move it to its own file.
+
+Prefer:
+
+```swift
+var body: some View {
+    List {
+        HeaderSection(title: title, subtitle: subtitle)
+        FilterSection(
+            filterOptions: filterOptions,
+            selectedFilter: $selectedFilter
+        )
+        ResultsSection(items: filteredItems)
+        FooterSection()
+    }
+}
+
+private struct HeaderSection: View {
+    let title: String
+    let subtitle: String
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text(title).font(.title2)
+            Text(subtitle).font(.subheadline)
+        }
+    }
+}
+
+private struct FilterSection: View {
+    let filterOptions: [FilterOption]
+    @Binding var selectedFilter: FilterOption
+
+    var body: some View {
+        ScrollView(.horizontal, showsIndicators: false) {
+            HStack {
+                ForEach(filterOptions, id: \.self) { option in
+                    FilterChip(option: option, isSelected: option == selectedFilter)
+                        .onTapGesture { selectedFilter = option }
+                }
+            }
+        }
+    }
+}
+```
+
+Avoid:
+
+```swift
+var body: some View {
+    List {
+        header
+        filters
+        results
+        footer
+    }
+}
+
+private var header: some View {
+    VStack(alignment: .leading, spacing: 6) {
+        Text(title).font(.title2)
+        Text(subtitle).font(.subheadline)
+    }
+}
+```
+
+### 3b) Extract actions and side effects out of `body`
+- Do not keep non-trivial button actions inline in the view body.
+- Do not bury business logic inside `.task`, `.onAppear`, `.onChange`, or `.refreshable`.
+- Prefer calling small private methods from the view, and move real business logic into services/models.
+- The body should read like UI, not like a view controller.
+
+```swift
+Button("Save", action: save)
+    .disabled(isSaving)
+
+.task(id: searchText) {
+    await reload(for: searchText)
+}
+
+private func save() {
+    Task { await saveAsync() }
+}
+
+private func reload(for searchText: String) async {
+    guard !searchText.isEmpty else {
+        results = []
+        return
+    }
+    await searchService.search(searchText)
+}
+```
+
+### 4) Keep a stable view tree (avoid top-level conditional view swapping)
+- Avoid `body` or computed views that return completely different root branches via `if/else`.
+- Prefer a single stable base view with conditions inside sections/modifiers (`overlay`, `opacity`, `disabled`, `toolbar`, etc.).
+- Root-level branch swapping causes identity churn, broader invalidation, and extra recomputation.
+
+Prefer:
+
+```swift
+var body: some View {
+    List {
+        documentsListContent
+    }
+    .toolbar {
+        if canEdit {
+            editToolbar
+        }
+    }
+}
+```
+
+Avoid:
+
+```swift
+var documentsListView: some View {
+    if canEdit {
+        editableDocumentsList
+    } else {
+        readOnlyDocumentsList
+    }
+}
+```
+
+### 5) View model handling (only if already present or explicitly requested)
+- Treat view models as a legacy or explicit-need pattern, not the default.
+- Do not introduce a view model unless the request or existing code clearly calls for one.
+- If a view model exists, make it non-optional when possible.
+- Pass dependencies to the view via `init`, then create the view model in the view's `init`.
+- Avoid `bootstrapIfNeeded` patterns and other delayed setup workarounds.
+
+Example (Observation-based):
+
+```swift
+@State private var viewModel: SomeViewModel
+
+init(dependency: Dependency) {
+    _viewModel = State(initialValue: SomeViewModel(dependency: dependency))
+}
+```
+
+### 6) Observation usage
+- For `@Observable` reference types on iOS 17+, store them as `@State` in the owning view.
+- Pass observables down explicitly; avoid optional state unless the UI genuinely needs it.
+- If the deployment target includes iOS 16 or earlier, use `@StateObject` at the owner and `@ObservedObject` when injecting legacy observable models.
+
+## Workflow
+
+1. Reorder the view to match the ordering rules.
+2. Remove inline actions and side effects from `body`; move business logic into services/models and keep only thin orchestration in the view.
+3. Shorten long bodies by extracting dedicated subview types; avoid rebuilding the screen out of many computed `some View` helpers.
+4. Ensure stable view structure: avoid top-level `if`-based branch swapping; move conditions to localized sections/modifiers.
+5. If a view model exists or is explicitly required, replace optional view models with a non-optional `@State` view model initialized in `init`.
+6. Confirm Observation usage: `@State` for root `@Observable` models on iOS 17+, legacy wrappers only when the deployment target requires them.
+7. Keep behavior intact: do not change layout or business logic unless requested.
+
+## Notes
+
+- Prefer small, explicit view types over large conditional blocks and large computed `some View` properties.
+- Keep computed view builders below `body` and non-view computed vars above `init`.
+- A good SwiftUI refactor should make the view read top-to-bottom as data flow plus layout, not as mixed layout and imperative logic.
+- For MV-first guidance and rationale, see `references/mv-patterns.md`.
+
+## Large-view handling
+
+When a SwiftUI view file exceeds ~300 lines, split it aggressively. Extract meaningful sections into dedicated `View` types instead of hiding complexity in many computed properties. Use `private` extensions with `// MARK: -` comments for actions and helpers, but do not treat extensions as a substitute for breaking a giant screen into smaller view types. If an extracted subview is reused or independently meaningful, move it into its own file.

package/pipeline/skills/shared/external/swiftui-webkit/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: swiftui-webkit
+description: "Embeds and controls web content in SwiftUI with WebKit for SwiftUI, including WebView, WebPage, navigation policies, JavaScript execution, observable page state, link interception, local HTML or data loading, and custom URL schemes. Use when building iOS 26+ article/detail views, help centers, in-app documentation, or other embedded web experiences backed by HTML, CSS, and JavaScript."
+---
+
+# SwiftUI WebKit
+
+Embed and manage web content in SwiftUI using the native WebKit-for-SwiftUI APIs introduced for iOS 26, iPadOS 26, macOS 26, and visionOS 26. Use this skill when the app needs an integrated web surface, app-owned HTML content, JavaScript-backed page interaction, or custom navigation policy control.
+
+## Contents
+
+- [Choose the Right Web Container](#choose-the-right-web-container)
+- [Displaying Web Content](#displaying-web-content)
+- [Loading and Observing with WebPage](#loading-and-observing-with-webpage)
+- [Navigation Policies](#navigation-policies)
+- [JavaScript Integration](#javascript-integration)
+- [Local Content and Custom URL Schemes](#local-content-and-custom-url-schemes)
+- [WebView Customization](#webview-customization)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+## Choose the Right Web Container
+
+Use the narrowest tool that matches the job.
+
+| Need | Default choice |
+|---|---|
+| Embedded app-owned web content in SwiftUI | `WebView` + `WebPage` |
+| Simple external site presentation with Safari behavior | `SFSafariViewController` |
+| OAuth or third-party sign-in | `ASWebAuthenticationSession` |
+| Back-deploy below iOS 26 or use missing legacy-only WebKit features | `WKWebView` fallback |
+
+Prefer `WebView` and `WebPage` for modern SwiftUI apps targeting iOS 26+. Apple’s WWDC25 guidance explicitly recommends migrating SwiftUI apps away from UIKit/AppKit WebKit wrappers when possible.
+
+Do not use embedded web views for OAuth. That stays an `ASWebAuthenticationSession` flow.
+
+## Displaying Web Content
+
+Use the simple `WebView(url:)` form when the app only needs to render a URL and SwiftUI state drives navigation.
+
+```swift
+import SwiftUI
+import WebKit
+
+struct ArticleView: View {
+    let url: URL
+
+    var body: some View {
+        WebView(url: url)
+    }
+}
+```
+
+Create a `WebPage` when the app needs to load requests directly, observe state, call JavaScript, or customize navigation behavior.
+
+```swift
+@Observable
+@MainActor
+final class ArticleModel {
+    let page = WebPage()
+
+    func load(_ url: URL) async throws {
+        for try await _ in page.load(URLRequest(url: url)) {
+        }
+    }
+}
+
+struct ArticleDetailView: View {
+    @State private var model = ArticleModel()
+    let url: URL
+
+    var body: some View {
+        WebView(model.page)
+            .task {
+                try? await model.load(url)
+            }
+    }
+}
+```
+
+See `references/loading-and-observation.md` for full examples.
+
+## Loading and Observing with WebPage
+
+`WebPage` is an `@MainActor` observable type. Use it when you need page state in SwiftUI.
+
+Common loading entry points:
+- `load(URLRequest)`
+- `load(URL)`
+- `load(html:baseURL:)`
+- `load(_:mimeType:characterEncoding:baseURL:)`
+
+Common observable properties:
+- `title`
+- `url`
+- `isLoading`
+- `estimatedProgress`
+- `currentNavigationEvent`
+- `backForwardList`
+
+```swift
+struct ReaderView: View {
+    @State private var page = WebPage()
+
+    var body: some View {
+        WebView(page)
+            .navigationTitle(page.title ?? "Loading")
+            .overlay {
+                if page.isLoading {
+                    ProgressView(value: page.estimatedProgress)
+                }
+            }
+            .task {
+                do {
+                    for try await _ in page.load(URLRequest(url: URL(string: "https://example.com")!)) {
+                    }
+                } catch {
+                    // Handle load failure.
+                }
+            }
+    }
+}
+```
+
+When you need to react to every navigation, observe the navigation sequence rather than only checking a single property.
+
+```swift
+Task {
+    for await event in page.navigations {
+        // Handle finish, redirect, or failure events.
+    }
+}
+```
+
+See `references/loading-and-observation.md` for stronger patterns and the load-sequence examples.
+
+## Navigation Policies
+
+Use `WebPage.NavigationDeciding` to allow, cancel, or customize navigations based on the request or response.
+
+Typical uses:
+- keep app-owned domains inside the embedded web view
+- cancel external domains and hand them off with `openURL`
+- intercept special callback URLs
+- tune `NavigationPreferences`
+
+```swift
+@MainActor
+final class ArticleNavigationDecider: WebPage.NavigationDeciding {
+    var urlToOpenExternally: URL?
+
+    func decidePolicy(
+        for action: WebPage.NavigationAction,
+        preferences: inout WebPage.NavigationPreferences
+    ) async -> WKNavigationActionPolicy {
+        guard let url = action.request.url else { return .allow }
+
+        if url.host == "example.com" {
+            return .allow
+        }
+
+        urlToOpenExternally = url
+        return .cancel
+    }
+}
+```
+
+Keep app-level deep-link routing in the navigation skill. This skill owns navigation that happens inside embedded web content.
+
+See `references/navigation-and-javascript.md` for complete patterns.
+
+## JavaScript Integration
+
+Use `callJavaScript(_:arguments:in:contentWorld:)` to evaluate JavaScript functions against the page.
+
+```swift
+let script = """
+const headings = [...document.querySelectorAll('h1, h2')];
+return headings.map(node => ({
+    id: node.id,
+    text: node.textContent?.trim()
+}));
+"""
+
+let result = try await page.callJavaScript(script)
+let headings = result as? [[String: Any]] ?? []
+```
+
+You can pass values through the `arguments` dictionary and cast the returned `Any` into the Swift type you actually need.
+
+```swift
+let result = try await page.callJavaScript(
+    "return document.getElementById(sectionID)?.getBoundingClientRect().top ?? null;",
+    arguments: ["sectionID": selectedSectionID]
+)
+```
+
+Important boundary: the native SwiftUI WebKit API clearly supports Swift-to-JavaScript calls, but it does not expose an obvious direct replacement for `WKScriptMessageHandler`. If you need coarse JS-to-native signaling, a custom navigation or callback-URL pattern can work, but document it as a workaround pattern, not a guaranteed one-to-one replacement.
+
+See `references/navigation-and-javascript.md`.
+
+## Local Content and Custom URL Schemes
+
+Use `WebPage.Configuration` and `URLSchemeHandler` when the app needs bundled HTML, offline documents, or app-provided resources under a custom scheme.
+
+```swift
+var configuration = WebPage.Configuration()
+configuration.urlSchemeHandlers[URLScheme("docs")!] = DocsSchemeHandler(bundle: .main)
+
+let page = WebPage(configuration: configuration)
+for try await _ in page.load(URL(string: "docs://article/welcome")!) {
+}
+
+```
+
+Use this for:
+- bundled documentation or article content
+- offline HTML/CSS/JS assets
+- app-owned resource loading under a custom scheme
+
+Do not overuse custom schemes for normal remote content. Prefer standard HTTPS for server-hosted pages.
+
+See `references/local-content-and-custom-schemes.md`.
+
+## WebView Customization
+
+Use WebView modifiers to match the intended browsing experience.
+
+Useful modifiers and related APIs:
+- `webViewBackForwardNavigationGestures(_:)`
+- `findNavigator(isPresented:)`
+- `webViewScrollPosition(_:)`
+- `webViewOnScrollGeometryChange(...)`
+
+Apply them only when the user experience needs them.
+
+- Enable back/forward gestures when people are likely to visit multiple pages.
+- Add Find in Page when the content is document-like.
+- Sync scroll position only when the app has a sidebar, table of contents, or other explicit navigation affordance.
+
+Apple’s HIG also applies here: support back/forward navigation when appropriate, but do not turn an app web view into a general-purpose browser.
+
+## Common Mistakes
+
+- Using `WKWebView` wrappers by default in an iOS 26+ SwiftUI app instead of starting with `WebView` and `WebPage`
+- Using embedded web views for OAuth instead of `ASWebAuthenticationSession`
+- Reaching for `WebPage` only after building a plain `WebView(url:)` path that now needs state, JS, or navigation control
+- Treating `callJavaScript` as a direct replacement for `WKScriptMessageHandler`
+- Keeping all links inside the app when external domains should open outside the embedded surface
+- Building a browser-style app shell around WebView instead of a focused embedded experience
+- Using custom URL schemes for content that should just load over HTTPS
+- Forgetting that `WebPage` is main-actor-isolated
+
+## Review Checklist
+
+- [ ] `WebView` and `WebPage` are the default path for iOS 26+ SwiftUI web content
+- [ ] `ASWebAuthenticationSession` is used for auth flows instead of embedded web views
+- [ ] `WebPage` is used whenever the app needs state observation, JS calls, or policy control
+- [ ] Navigation policies only intercept the URLs the app actually owns or needs to reroute
+- [ ] External domains open externally when appropriate
+- [ ] JavaScript return values are cast defensively to concrete Swift types
+- [ ] Custom URL schemes are used only for real app-owned resources
+- [ ] Back/forward gestures or controls are enabled when multi-page browsing is expected
+- [ ] The web experience adds focused native value instead of behaving like a thin browser shell
+- [ ] Fallback to `WKWebView` is justified by deployment target or missing API needs
+
+## References
+
+- Loading and observation: `references/loading-and-observation.md`
+- Navigation and JavaScript: `references/navigation-and-javascript.md`
+- Local content and custom schemes: `references/local-content-and-custom-schemes.md`
+- Migration and fallbacks: `references/migration-and-fallbacks.md`

package/pipeline/skills/shared/external/swiftui-webkit/references/loading-and-observation.md

@@ -0,0 +1,151 @@
+# Loading and Observation
+
+## Contents
+- Simple `WebView(url:)`
+- Controlled `WebPage` loading
+- Observing progress and title
+- Observing navigation events
+- Ephemeral pages and custom user agents
+
+## Simple `WebView(url:)`
+
+Use `WebView(url:)` when the app only needs to display a URL and does not need explicit page control.
+
+```swift
+import SwiftUI
+import WebKit
+
+struct MarketingPageView: View {
+    let url: URL
+
+    var body: some View {
+        WebView(url: url)
+            .webViewBackForwardNavigationGestures(.enabled)
+    }
+}
+```
+
+This is the lowest-friction path for embedded content.
+
+## Controlled `WebPage` loading
+
+Create a `WebPage` when the app needs to drive loading itself.
+
+```swift
+@Observable
+@MainActor
+final class ArticleModel {
+    let page = WebPage()
+    var lastError: String?
+
+    func load(_ url: URL) async {
+        do {
+            for try await _ in page.load(URLRequest(url: url)) {
+            }
+        } catch {
+            lastError = error.localizedDescription
+        }
+    }
+}
+```
+
+```swift
+struct ArticleDetailView: View {
+    @State private var model = ArticleModel()
+    let url: URL
+
+    var body: some View {
+        WebView(model.page)
+            .task {
+                await model.load(url)
+            }
+    }
+}
+```
+
+You can also load:
+- `for try await _ in page.load(url) { }`
+- `for try await _ in page.load(html: htmlString, baseURL: baseURL) { }`
+- `for try await _ in page.load(data, mimeType: "text/html", characterEncoding: "utf-8", baseURL: baseURL) { }`
+
+## Observing progress and title
+
+`WebPage` is observable, so SwiftUI can bind directly to its state.
+
+```swift
+struct ReaderView: View {
+    @State private var page = WebPage()
+
+    var body: some View {
+        WebView(page)
+            .navigationTitle(page.title ?? "Loading")
+            .overlay(alignment: .top) {
+                if page.isLoading {
+                    ProgressView(value: page.estimatedProgress)
+                        .padding()
+                }
+            }
+            .task {
+                do {
+                    for try await _ in page.load(URLRequest(url: URL(string: "https://example.com/docs")!)) {
+                    }
+                } catch {
+                    // Handle load failure.
+                }
+            }
+    }
+}
+```
+
+Useful properties:
+- `title`
+- `url`
+- `isLoading`
+- `estimatedProgress`
+- `themeColor`
+- `hasOnlySecureContent`
+- `backForwardList`
+
+## Observing navigation events
+
+Use `currentNavigationEvent` for a lightweight current-state view. Use `navigations` to observe the full sequence of navigation events.
+
+```swift
+@MainActor
+func observeNavigations(for page: WebPage) {
+    Task {
+        for await event in page.navigations {
+            switch event {
+            case .finished:
+                print("Navigation finished")
+            case .failed(let error), .failedProvisionalNavigation(let error):
+                print("Navigation failed: \(error)")
+            default:
+                break
+            }
+        }
+    }
+}
+```
+
+This is the right place to trigger follow-up work like parsing headings after a finished navigation.
+
+## Ephemeral pages and custom user agents
+
+Use `WebPage.Configuration` when you need a nonpersistent page, custom user agent, or tighter loading rules.
+
+```swift
+@MainActor
+func makeMetadataPage() -> WebPage {
+    var configuration = WebPage.Configuration()
+    configuration.loadsSubresources = false
+    configuration.defaultNavigationPreferences.allowsContentJavaScript = false
+    configuration.websiteDataStore = .nonPersistent()
+
+    let page = WebPage(configuration: configuration)
+    page.customUserAgent = "MetadataBot/1.0"
+    return page
+}
+```
+
+Use nonpersistent pages when you want an isolated web session or metadata fetch path without shared cookies or long-lived website data.