@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-webkit/references/local-content-and-custom-schemes.md

@@ -1,95 +1,98 @@
-# Local Content and Custom URL Schemes
+# Local content and custom URL schemes
 
-## Contents
-- When to use custom schemes
-- Registering a scheme handler
-- Returning responses and data
-- Loading bundled content
-- Cancellation behavior
+Part of the `swiftui-webkit` skill ([../SKILL.md](../SKILL.md)).
 
-## When to use custom schemes
+## Where a custom scheme fits
 
-Use `URLSchemeHandler` when the app owns the content source and needs WebKit to resolve resources under a custom scheme.
+Good candidates:
 
-Good fits:
-- bundled HTML, CSS, and JavaScript assets
-- offline documentation
-- app-owned rich content assembled on device
+- HTML, CSS and JavaScript shipped inside the app bundle
+- documentation that must work offline
+- rich content the app assembles on the device
 
-Do not use custom schemes for ordinary server-hosted pages that should just load over HTTPS.
+Ordinary pages that live on a server are not candidates; load those over
+HTTPS.
 
-## Registering a scheme handler
+## Registering the handler
+
+Put the registration in one main-actor factory so every screen gets the same
+setup.
 
 ```swift
-import Foundation
 import WebKit
 
 @MainActor
-func makeDocsPage() -> WebPage {
-    var configuration = WebPage.Configuration()
-    configuration.urlSchemeHandlers[URLScheme("docs")!] = DocsSchemeHandler(bundle: .main)
-    return WebPage(configuration: configuration)
+func makeManualPage() -> WebPage {
+    var setup = WebPage.Configuration()
+    if let scheme = URLScheme("manual") {
+        setup.urlSchemeHandlers[scheme] = ManualFiles()
+    }
+    return WebPage(configuration: setup)
 }
 ```
 
-If WebKit already owns a scheme, `URLScheme("https")` style registration does not work. Use a genuinely custom scheme.
+Schemes WebKit already owns cannot be taken over: registering
+`URLScheme("https")` has no effect. Pick a name that is really yours.
 
-## Returning responses and data
+## Producing the response
 
-A handler replies with an async sequence of intermixed response and data values.
+A handler implements `reply(for:)` and returns an async sequence of
+`URLSchemeTaskResult` values. Send a `.response(_:)` first, then one or more
+`.data(_:)` chunks; for multi-part content the two can alternate.
 
 ```swift
-struct DocsSchemeHandler: URLSchemeHandler {
-    let bundle: Bundle
-
-    func reply(for request: URLRequest) -> some AsyncSequence<URLSchemeTaskResult> {
-        AsyncStream { continuation in
-            guard let url = request.url,
-                  let fileURL = bundle.url(forResource: url.host, withExtension: "html", subdirectory: "Docs")
-            else {
-                continuation.finish()
+import Foundation
+import WebKit
+
+struct ManualFiles: URLSchemeHandler {
+    func reply(for request: URLRequest) -> AsyncThrowingStream<URLSchemeTaskResult, any Error> {
+        AsyncThrowingStream { continuation in
+            guard let address = request.url,
+                  let chapter = address.host(),
+                  let file = Bundle.main.url(forResource: chapter,
+                                             withExtension: "html",
+                                             subdirectory: "Manual"),
+                  let body = try? Data(contentsOf: file) else {
+                continuation.finish(throwing: URLError(.fileDoesNotExist))
                 return
             }
 
-            do {
-                let data = try Data(contentsOf: fileURL)
-                let response = URLResponse(
-                    url: url,
-                    mimeType: "text/html",
-                    expectedContentLength: data.count,
-                    textEncodingName: "utf-8"
-                )
-                continuation.yield(.response(response))
-                continuation.yield(.data(data))
-                continuation.finish()
-            } catch {
-                continuation.finish()
-            }
+            let head = URLResponse(url: address,
+                                   mimeType: "text/html",
+                                   expectedContentLength: body.count,
+                                   textEncodingName: "utf-8")
+            continuation.yield(.response(head))
+            continuation.yield(.data(body))
+            continuation.finish()
         }
     }
 }
 ```
 
-Keep MIME type and encoding aligned with the actual content you serve.
+Keep `mimeType` and `textEncodingName` truthful: a stylesheet served as
+`text/html` or UTF-16 labelled as UTF-8 renders wrongly. The protocol
+requires a sequence whose failure type is `any Error`, so a throwing stream
+is the natural choice and lets a missing file surface as an error.
 
-## Loading bundled content
+## Loading bundled pages
 
-Once registered, load the custom URL like any other page.
+A custom-scheme URL loads like any other address:
 
 ```swift
-let page = makeDocsPage()
-for try await _ in page.load(URL(string: "docs://welcome")!) {
+@MainActor
+func openChapter(_ name: String, in page: WebPage) async throws {
+    guard let address = URL(string: "manual://\(name)") else { return }
+    for try await _ in page.load(address) { }
 }
-
 ```
 
-This works well when the HTML references other assets with the same custom scheme.
-
-## Cancellation behavior
+Relative references inside the HTML (images, stylesheets, scripts) resolve
+against the same scheme, so they come back through the same handler.
 
-If WebKit no longer needs the resource, it cancels the task producing the async sequence. Treat cancellation as normal behavior when:
-- the user navigates away
-- the page reloads before the previous request completes
-- the resource is no longer needed by the page
+## Cancellation
 
-Do not build logic that assumes every scheme-handled request runs to completion.
+WebKit stops consuming a reply when the resource is no longer wanted: the
+user navigated away, the page reloaded, or the load became unnecessary. The
+task producing the sequence is cancelled at that point. Treat that as a normal
+outcome, clean up in an `onTermination` handler if you hold resources, and do
+not assume every request runs to completion.

package/pipeline/skills/shared/external/swiftui-webkit/references/migration-and-fallbacks.md

@@ -1,165 +1,97 @@
-# Migration and Fallbacks
+# Migration and fallbacks
 
-## Contents
-- Migration goal
-- Decision guide
-- Migrating from `WKWebView` wrappers
-- Incremental migration pattern
-- When `SFSafariViewController` is still the right choice
-- When `ASWebAuthenticationSession` is required
-- When `WKWebView` remains justified
-- Testing the migration
-- Review checklist
+Part of the `swiftui-webkit` skill ([../SKILL.md](../SKILL.md)).
 
-## Migration goal
+## What the migration is for
 
-For SwiftUI apps targeting iOS 26+, the default should be native SwiftUI WebKit
-APIs (`WebView`, `WebPage`) instead of a custom `UIViewRepresentable` wrapper
-around `WKWebView`.
+In a SwiftUI app targeting iOS 26 or later, `WebView` and `WebPage` are the
+starting point for embedded web content. The aim is to move everyday screens
+onto them and keep only the fallbacks that still earn their place, not to
+delete every `WKWebView` in one sweep.
 
-The goal is not "delete every `WKWebView` immediately." The goal is to move
-routine embedded web content to the new native surface and keep legacy fallback
-paths only where they are still justified.
+## Choosing a container
 
-## Decision guide
-
-| Use case | Best default |
+| Need | Choice |
 |---|---|
-| Embedded app-owned web content in a SwiftUI screen | `WebView` + `WebPage` |
+| App-owned web content inside SwiftUI | `WebView` + `WebPage` |
 | OAuth or third-party sign-in | `ASWebAuthenticationSession` |
-| External public site with Safari behavior | `SFSafariViewController` |
-| Back-deploying below iOS 26 or missing required capability | `WKWebView` fallback |
-
-## Migrating from `WKWebView` wrappers
+| An outside site that should behave like Safari | `SFSafariViewController` |
+| Older deployment target, or a capability the new API lacks | `WKWebView` |
 
-For SwiftUI apps targeting iOS 26+, start from `WebView` and `WebPage` instead
-of a `UIViewRepresentable` wrapper around `WKWebView`.
+## Mapping the old pieces
 
-Typical mapping:
-
-| Older pattern | Modern default |
+| `WKWebView` era | SwiftUI WebKit |
 |---|---|
-| `UIViewRepresentable` wrapper for `WKWebView` | `WebView(url:)` or `WebView(page)` |
-| `WKNavigationDelegate` policy handling | `WebPage.NavigationDeciding` |
-| KVO for `title`, `url`, or loading state | observable `WebPage` properties |
-| `evaluateJavaScript` | `callJavaScript` |
-| custom `WKWebViewConfiguration` usage | `WebPage.Configuration` |
-
-Migrate first when the app is already SwiftUI-native and only kept `WKWebView`
-because there was no native view before.
-
-## Incremental migration pattern
-
-A clean migration is usually screen-by-screen, not all-at-once.
-
-### Start by separating page ownership from view ownership
-
-If the current wrapper mixes:
-
-- page state
-- navigation policy
-- JS calls
-- UI embedding
-
-split those concerns first. Once page logic is no longer trapped inside the
-wrapper, moving to `WebPage` gets much easier.
-
-### Move the simplest screens first
-
-Best first migrations:
-
-- static help center content
-- app-owned account or legal pages
-- embedded flows that only need URL loading, title, and progress
-
-Leave these for later:
-
-- auth flows
-- highly customized legacy UIKit screens
-- surfaces relying on a capability you have not yet mapped to the new API set
-
-### Keep fallback boundaries explicit
-
-Use availability and architecture boundaries instead of mixing two approaches in
-one view body.
+| `UIViewRepresentable` wrapping `WKWebView` | `WebView(url:)` or `WebView(page)` |
+| `WKNavigationDelegate` policy methods | `WebPage.NavigationDeciding` |
+| KVO on `title`, `url`, `isLoading` | observable properties on `WebPage` |
+| `evaluateJavaScript(_:)` | `callJavaScript(_:arguments:in:contentWorld:)` |
+| `WKWebViewConfiguration` | `WebPage.Configuration` |
+
+The strongest case for moving first is a SwiftUI-native app that kept a
+`WKWebView` wrapper only because no SwiftUI view existed.
+
+## Moving one screen at a time
+
+1. Inside the old wrapper, separate four concerns: page state, navigation
+   policy, JavaScript calls and the view embedding.
+2. Move the screens with the least risk first: a static help center, account
+   or legal pages the app owns, flows that only need URL, title and progress.
+3. Leave for later: sign-in flows, heavily customised UIKit screens, and
+   anything that depends on a capability the new API does not map.
+4. Keep remaining fallbacks in their own wrapper type instead of scattering
+   `if #available` checks through screen logic.
 
 ```swift
-struct HelpCenterScreen: View {
-    let page = WebPage()
+struct EmbeddedDocument: View {
+    let address: URL
 
     var body: some View {
-        WebView(page)
-            .task {
-                try? await page.load(URLRequest(url: helpCenterURL))
-            }
+        if #available(iOS 26.0, *) {
+            WebView(url: address)
+        } else {
+            LegacyDocumentView(address: address)   // the one place WKWebView lives
+        }
     }
 }
 ```
 
-If a fallback is still needed, isolate it in a separate type rather than
-sprinkling `if #available` checks through the screen's core logic.
-
-## When `SFSafariViewController` is still the right choice
-
-Use `SFSafariViewController` when the app just needs to show an external site
-with Safari behavior and does not need page-level control.
-
-Good fits:
-
-- help center article from a public website
-- a legal page or blog post
-- a temporary browse-out flow that should keep Safari chrome and reader behavior
-
-Do not use `SFSafariViewController` when the app needs to:
-
-- observe page state
-- run JavaScript
-- intercept navigation
-- coordinate in-app page history
-
-## When `ASWebAuthenticationSession` is required
-
-Use `ASWebAuthenticationSession` for OAuth and third-party sign-in.
-
-This remains true even if the rest of the app uses `WebView` for embedded
-content.
+## When SFSafariViewController is still right
 
-Do not replace auth sessions with embedded web views. The authentication skill
-owns that flow because the product requirement is secure sign-in, not generic
-web content.
+Use it to send people to an outside site while keeping Safari's chrome and
+Reader: a public help article, a legal page hosted elsewhere, a blog post.
+It is the wrong tool once the app needs page state, JavaScript, navigation
+interception or its own history handling.
 
-## When `WKWebView` remains justified
+## When ASWebAuthenticationSession is required
 
-A fallback `WKWebView` path can still make sense when:
+Every OAuth or third-party sign-in flow goes through it, even when the rest
+of the feature uses `WebView`. The `authentication` skill covers the flow
+itself.
 
-- the app must back-deploy below iOS 26
-- the codebase is still UIKit-first and not ready to move the surface into
-  native SwiftUI WebKit APIs
-- a required legacy-only WebKit capability is not yet available through the new
-  SwiftUI-facing API surface
-- a heavily customized existing surface would create churn without product value
+## When WKWebView still makes sense
 
-When you keep `WKWebView`, treat it as a deliberate fallback, not the default
-architecture for a modern iOS 26+ SwiftUI feature.
+- the deployment target is below iOS 26
+- a UIKit-first codebase is not ready to move
+- a capability exists only on the old API
+- the screen is so customised that migrating it costs more than it returns
 
-## Testing the migration
+Keep such cases as a conscious fallback, documented where the wrapper lives.
 
-For each migrated screen, verify:
+## Testing a migrated screen
 
-- title and URL state still update correctly
-- JavaScript calls still reach the page when needed
-- navigation policy behavior still matches product expectations
-- loading and error states still render at the right time
-- no auth flow accidentally moved from `ASWebAuthenticationSession` to an
-  embedded view
-- fallback `WKWebView` screens stay isolated instead of spreading wrapper logic
-  back into new screens
+- Title and URL update as the user navigates.
+- JavaScript calls reach the page and their results decode.
+- Policy decisions match the old delegate (same links stay in, same links leave).
+- Loading and error states appear at the right moments.
+- No sign-in flow ended up inside the embedded view.
+- Fallback wrappers are still confined to their own types.
 
-## Review checklist
+## Checklist
 
-- [ ] New SwiftUI-native screens default to `WebView` and `WebPage`
-- [ ] `SFSafariViewController` used only for browse-out Safari-style flows
-- [ ] `ASWebAuthenticationSession` retained for OAuth and sign-in
-- [ ] `WKWebView` kept only where back-deployment or capability gaps justify it
-- [ ] Fallback paths isolated to dedicated wrapper types
-- [ ] No new iOS 26+ feature starts from a `UIViewRepresentable` wrapper by default
+- [ ] New screens start with `WebView` and `WebPage`
+- [ ] `SFSafariViewController` is used only for browse-out
+- [ ] Sign-in stays on `ASWebAuthenticationSession`
+- [ ] `WKWebView` appears only where one of the reasons above applies
+- [ ] Fallbacks live in dedicated wrapper types
+- [ ] No new iOS 26+ feature begins life as a `UIViewRepresentable` web view wrapper

package/pipeline/skills/shared/external/swiftui-webkit/references/navigation-and-javascript.md

@@ -1,15 +1,11 @@
 # Navigation and JavaScript
 
-## Contents
-- Navigation policy decisions
-- Opening external links outside the embedded web view
-- Calling JavaScript
-- Passing arguments into JavaScript
-- Coarse JS-to-native signaling
+Part of the `swiftui-webkit` skill ([../SKILL.md](../SKILL.md)).
 
-## Navigation policy decisions
+## An observable navigation decider
 
-Use `WebPage.NavigationDeciding` when the app needs to allow only owned URLs inside the embedded page.
+Making the decider itself `@Observable` lets a view react when it cancels a
+navigation that should leave the app.
 
 ```swift
 import Observation
@@ -17,95 +13,127 @@ import WebKit
 
 @Observable
 @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 == "docs.example.com" {
-            return .allow
-        }
-
-        urlToOpenExternally = url
+final class LinkPolicy: WebPage.NavigationDeciding {
+    var outboundURL: URL?
+    private let ownedHosts: Set<String> = ["support.example.net", "status.example.net"]
+
+    func decidePolicy(for step: WebPage.NavigationAction,
+                      preferences prefs: inout WebPage.NavigationPreferences)
+        async -> WKNavigationActionPolicy {
+        guard let target = step.request.url else { return .allow }
+        if let host = target.host(), ownedHosts.contains(host) { return .allow }
+        if target.scheme == "about" { return .allow }
+        outboundURL = target
         return .cancel
     }
 }
 ```
 
-This keeps app-owned pages embedded while still letting the app hand off external destinations.
+## Sending outside links to the system
 
-## Opening external links outside the embedded web view
-
-Bridge the decider back into SwiftUI with `openURL`.
+Build the decider and the page once, in `init`, then open whatever the
+decider rejected with the environment's `openURL`.
 
 ```swift
-struct ArticleView: View {
+import SwiftUI
+import WebKit
+
+struct SupportScreen: View {
     @Environment(\.openURL) private var openURL
-    @State private var decider: ArticleNavigationDecider
+    @State private var policy: LinkPolicy
     @State private var page: WebPage
-
-    init() {
-        let decider = ArticleNavigationDecider()
-        _decider = State(initialValue: decider)
-        _page = State(initialValue: WebPage(configuration: .init(), navigationDecider: decider))
+    let entry: URL
+
+    init(entry: URL) {
+        self.entry = entry
+        let policy = LinkPolicy()
+        _policy = State(wrappedValue: policy)
+        let setup = WebPage.Configuration()
+        _page = State(wrappedValue: WebPage(configuration: setup, navigationDecider: policy))
     }
 
     var body: some View {
         WebView(page)
-            .onChange(of: decider.urlToOpenExternally) { _, url in
-                guard let url else { return }
-                openURL(url)
-                decider.urlToOpenExternally = nil
+            .task { _ = page.load(entry) }
+            .onChange(of: policy.outboundURL) { _, destination in
+                guard let destination else { return }
+                openURL(destination)
+                policy.outboundURL = nil
             }
     }
 }
 ```
 
-Use this for external links, legal pages, or routes that should leave the embedded surface.
-
-## Calling JavaScript
+## Running JavaScript
 
-`callJavaScript` executes an async JavaScript function and returns an optional `Any`.
+The string passed to `callJavaScript` becomes the body of an async function,
+and whatever it returns comes back as `Any?`. Convert it to the structure you
+expect immediately so the rest of the code stays typed.
 
 ```swift
-let script = """
-const headings = [...document.querySelectorAll('h1, h2')];
-return headings.map(node => ({
-    id: node.id,
-    title: node.textContent?.trim()
-}));
-"""
-
-let result = try await page.callJavaScript(script)
-let headings = result as? [[String: Any]] ?? []
-```
+struct Outline {
+    let anchor: String
+    let label: String
+}
 
-Cast immediately into the specific structure the app expects.
+@MainActor
+func readOutline(of page: WebPage) async throws -> [Outline] {
+    let outcome = try await page.callJavaScript("""
+        return Array.from(document.querySelectorAll('h2[id]'), el => ({ anchor: el.id, label: el.innerText }));
+        """)
+    guard let rows = outcome as? [[String: Any]] else { return [] }
+    return rows.compactMap { row in
+        guard let anchor = row["anchor"] as? String, let label = row["label"] as? String else { return nil }
+        return Outline(anchor: anchor, label: label)
+    }
+}
+```
 
-## Passing arguments into JavaScript
+## Handing values to the script
 
-Arguments become local variables inside the JavaScript function.
+Every key of the `arguments` dictionary turns into a local variable of that function. This is the
+safe way to feed in user text or other untrusted values; never splice them
+into the script string.
 
 ```swift
-let topOffset = try await page.callJavaScript(
-    "return document.getElementById(sectionID)?.getBoundingClientRect().top ?? null;",
-    arguments: ["sectionID": selectedSectionID]
-) as? Double
+@MainActor
+func highlightCount(of term: String, in page: WebPage) async throws -> Int {
+    let found = try await page.callJavaScript(
+        "return (document.body.innerText.match(new RegExp(needle, 'gi')) || []).length;",
+        arguments: ["needle": NSRegularExpression.escapedPattern(for: term)]
+    )
+    return (found as? Double).map(Int.init) ?? 0
+}
 ```
 
-This is cleaner than interpolating untrusted values into the script string.
+JavaScript numbers arrive as `Double` (or `NSNumber`), so cast accordingly.
+
+## Simple signals from the page to the app
 
-## Coarse JS-to-native signaling
+For a one-bit message such as "the form is done", the page can navigate to a
+custom URL that the decider recognises, reads and cancels:
 
-The native SwiftUI WebKit API clearly supports Swift-to-JavaScript calls, but it does not expose an obvious direct equivalent to `WKScriptMessageHandler`.
+```javascript
+window.location.href = "app-event://checkout-finished?order=A1942";
+```
 
-For coarse event handoff, a custom navigation pattern can work:
-- JavaScript navigates to a custom callback URL like `app-event://completed?id=123`
-- `NavigationDeciding` intercepts the URL
-- the decider extracts data and returns `.cancel`
+```swift
+@MainActor
+final class CheckoutWatcher: WebPage.NavigationDeciding {
+    var finishedOrder: String?
+
+    func decidePolicy(for step: WebPage.NavigationAction,
+                      preferences prefs: inout WebPage.NavigationPreferences)
+        async -> WKNavigationActionPolicy {
+        guard let target = step.request.url, target.scheme == "app-event" else { return .allow }
+        let parts = URLComponents(url: target, resolvingAgainstBaseURL: false)
+        finishedOrder = parts?.queryItems?.first { $0.name == "order" }?.value
+        return .cancel
+    }
+}
+```
 
-Use this for simple completion or routing signals. Do not present it as a full structured messaging replacement for legacy `WKUserContentController` script handlers.
+Keep this to simple completion or routing signals. It is not a structured
+substitute for script message handlers registered on a
+`WKUserContentController`; when you need real two-way messaging, use the
+`userContentController` that `WebPage.Configuration` exposes.