@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-navigation/references/deeplinks.md

@@ -1,99 +1,95 @@
-# Deep links and navigation
+# Incoming Links and Handoff
 
-## Contents
+Part of the `swiftui-navigation` skill. The aim is to send external URLs to
+the right screen inside the app, and to let the system handle anything the app
+does not own.
 
-- [Intent](#intent)
-- [Core patterns](#core-patterns)
-- [Example: router entry points](#example-router-entry-points)
-- [Example: attach to a root view](#example-attach-to-a-root-view)
-- [Design choices to keep](#design-choices-to-keep)
-- [Pitfalls](#pitfalls)
-- [Universal Links](#universal-links)
-- [Custom URL Schemes](#custom-url-schemes)
-- [NSUserActivity Continuation (Handoff)](#nsuseractivity-continuation-handoff)
+## Shape of the solution
 
-## Intent
+- All URL handling lives in router methods, here `handle(url:)` and
+  `handleDeepLink(url:)`.
+- The environment's `openURL` is replaced by an `OpenURLAction` that asks the
+  router first.
+- `.onOpenURL` receives app-scheme links and turns them into web URLs when the
+  router expects those.
+- The router alone decides between navigating in the app and opening the URL
+  outside it.
 
-Route external URLs into in-app destinations while falling back to system handling when needed.
+## Router entry points
 
-## Core patterns
-
-- Centralize URL handling in the router (`handle(url:)`, `handleDeepLink(url:)`).
-- Inject an `OpenURLAction` handler that delegates to the router.
-- Use `.onOpenURL` for app scheme links and convert them to web URLs if needed.
-- Let the router decide whether to navigate or open externally.
+```swift
+@MainActor @Observable
+final class Router {
+    var fallback: ((URL) -> OpenURLAction.Result)?
+    var path: [Route] = []
 
-## Example: router entry points
+    func push(_ next: Route) { path.append(next) }
 
-```swift
-@MainActor
-final class RouterPath {
-  var path: [Route] = []
-  var urlHandler: ((URL) -> OpenURLAction.Result)?
-
-  func handle(url: URL) -> OpenURLAction.Result {
-    if isInternal(url) {
-      navigate(to: .status(id: url.lastPathComponent))
-      return .handled
+    func handle(url: URL) -> OpenURLAction.Result {
+        guard let route = Route(url: url) else {
+            return fallback.map { $0(url) } ?? .systemAction
+        }
+        path.append(route)
+        return .handled
     }
-    return urlHandler?(url) ?? .systemAction
-  }
 
-  func handleDeepLink(url: URL) -> OpenURLAction.Result {
-    // Resolve federated URLs, then navigate.
-    navigate(to: .status(id: url.lastPathComponent))
-    return .handled
-  }
+    func handleDeepLink(url: URL) -> OpenURLAction.Result {
+        Task {
+            guard let resolved = await LinkResolver.shared.canonical(for: url),
+                  let route = Route(url: resolved) else { return }
+            path.append(route)
+        }
+        return .handled
+    }
 }
 ```
 
-## Example: attach to a root view
+`handle(url:)` navigates for URLs the app understands and otherwise passes the
+URL on, ending with the system default. `handleDeepLink(url:)` first resolves
+links that point at another server (for example a federated or shortened URL),
+then navigates. Resolution runs in a `Task` so the UI never waits on the
+network.
+
+## Installing it once at the top
 
 ```swift
 extension View {
-  func withLinkRouter(_ router: RouterPath) -> some View {
-    self
-      .environment(
-        \.openURL,
-        OpenURLAction { url in
-          router.handle(url: url)
-        }
-      )
-      .onOpenURL { url in
-        router.handleDeepLink(url: url)
-      }
-  }
+    func withLinkRouter(_ links: Router) -> some View {
+        onOpenURL { incoming in _ = links.handleDeepLink(url: incoming) }
+            .environment(\.openURL, OpenURLAction(handler: links.handle(url:)))
+    }
 }
 ```
 
-## Design choices to keep
-
-- Keep URL parsing and decision logic inside the router.
-- Avoid handling deep links in multiple places; one entry point is enough.
-- Always provide a fallback to `@Environment(\.openURL)` via `OpenURLAction`.
-
-## Pitfalls
+## Rules and pitfalls
 
-- Don't assume the URL is internal; validate first.
-- Avoid blocking UI while resolving remote links; use `Task`.
+- Parsing and the decision to navigate live in the router, behind one entry
+  point.
+- Always fall back to the environment's `openURL` behaviour through
+  `OpenURLAction` so unknown links still open.
+- Check that a URL really belongs to the app before treating it as internal.
+- Never block the interface while a remote link resolves; use a `Task`.
 
-## Universal Links
+## Universal links
 
-Universal links let iOS open your app when a user taps a standard HTTPS URL, with no custom scheme required. They require server-side configuration and an Associated Domains entitlement.
+Universal links need server configuration plus the Associated Domains
+entitlement, and no custom scheme.
 
-### Apple App Site Association (AASA)
-
-Host a JSON file at `https://example.com/.well-known/apple-app-site-association` (no file extension, served with `Content-Type: application/json`):
+Put the association file under the domain's `.well-known` folder, at
+`https://yourdomain.example/.well-known/apple-app-site-association`. The name
+has no extension, and the response header should say JSON
+(`Content-Type: application/json`):
 
 ```json
 {
   "applinks": {
+    "defaults": { "caseSensitive": false },
     "details": [
       {
-        "appIDs": ["TEAMID.com.example.app"],
+        "appIDs": ["A1B2C3D4E5.org.sample.hiker"],
         "components": [
-          { "/": "/items/*", "comment": "Match item detail paths" },
-          { "/": "/profile/*" }
+          { "/": "/trail/*", "comment": "Trail pages" },
+          { "/": "/ranger/*" }
         ]
       }
     ]
@@ -101,119 +97,100 @@ Host a JSON file at `https://example.com/.well-known/apple-app-site-association`
 }
 ```
 
-Key rules:
-- AASA must be served over HTTPS with a valid certificate  -  no redirects.
-- Apple's CDN caches the file; updates can take 24-48 hours. Use `https://app-site-association.cdn-apple.com/a/v1/example.com` to verify the cached version.
-- Use `components` (modern) over the legacy `paths` array.
-
-### Associated Domains entitlement
-
-In your app's `.entitlements` file (or Signing & Capabilities in Xcode), add:
-
-```text
-com.apple.developer.associated-domains = [
-    "applinks:example.com",
-    "applinks:www.example.com"
-]
-```
+- HTTPS only, a certificate that validates, and no redirect on the way.
+- The system fetches the file through a CDN cache, so changes can take 24 to 48
+  hours to arrive. To see what devices currently get, open
+  `https://app-site-association.cdn-apple.com/a/v1/yourdomain.example`.
+- Write rules with `components`; the older `paths` key is legacy.
 
-For development/testing, prefix with `applinks:example.com?mode=developer` to bypass the CDN cache.
+Entitlement (`com.apple.developer.associated-domains`):
 
-### Handling Universal Links in SwiftUI
-
-Use `.onOpenURL` for link-based launches and `onContinueUserActivity` for `NSUserActivity`-based handoff:
-
-```swift
-@main
-struct MyApp: App {
-    @State private var router = Router()
-
-    var body: some Scene {
-        WindowGroup {
-            ContentView()
-                .environment(router)
-                .onOpenURL { url in
-                    router.handle(url: url)
-                }
-                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
-                    guard let url = activity.webpageURL else { return }
-                    router.handle(url: url)
-                }
-        }
-    }
-}
+```xml
+<key>com.apple.developer.associated-domains</key>
+<array>
+    <string>applinks:yourdomain.example</string>
+    <string>applinks:www.yourdomain.example</string>
+</array>
 ```
 
-> **Docs:** [Supporting universal links](https://sosumi.ai/documentation/xcode/supporting-universal-links-in-your-app)
-
-## Custom URL Schemes
+While developing, `applinks:yourdomain.example?mode=developer` skips the CDN
+cache.
 
-Custom URL schemes (e.g., `myapp://`) let other apps or websites open your app. They do not require server configuration but offer no fallback if the app is not installed.
+Reference: [universal links setup guide](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app)
 
-### Registering in Info.plist
+## Custom URL schemes
 
-Add `CFBundleURLTypes` to your target's Info.plist:
+A scheme such as `hiker://` needs no server, but if the app is missing the link
+simply fails.
 
 ```xml
 <key>CFBundleURLTypes</key>
 <array>
-  <dict>
-    <key>CFBundleURLSchemes</key>
-    <array>
-      <string>myapp</string>
-    </array>
-    <key>CFBundleURLName</key>
-    <string>com.example.myapp</string>
-  </dict>
+    <dict>
+        <key>CFBundleTypeRole</key>
+        <string>Viewer</string>
+        <key>CFBundleURLName</key>
+        <string>org.sample.hiker</string>
+        <key>CFBundleURLSchemes</key>
+        <array>
+            <string>hiker</string>
+        </array>
+    </dict>
 </array>
 ```
 
-### Handling with .onOpenURL
-
 ```swift
 .onOpenURL { url in
-    // url.scheme == "myapp"
-    // url.host == "items", url.pathComponents for routing
-    guard url.scheme == "myapp" else { return }
-    router.handle(url: url)
+    guard url.scheme == "hiker" else { return }
+    switch url.host {
+    case "trail":
+        if let id = url.pathComponents.dropFirst().first {
+            router.push(.trail(id: id))
+        }
+    default:
+        break
+    }
 }
 ```
 
-Prefer universal links over custom schemes for publicly shared links  -  they provide a better UX (web fallback) and are more secure (domain-verified).
+For links people share in public, universal links are the better experience,
+because they fall back to the website, and the safer one, because the domain
+is verified.
 
-## NSUserActivity Continuation (Handoff)
+## Handoff with NSUserActivity
 
-Handoff lets users start an activity on one device and continue it on another. SwiftUI provides `.onContinueUserActivity` and `.userActivity` modifiers.
-
-### Advertising an activity
+Handoff lets someone start on one device and carry on from another.
 
 ```swift
-struct ItemDetailView: View {
-    let item: Item
+struct TrailDetailView: View {
+    @Environment(Router.self) private var router
+    let trail: Trail
 
     var body: some View {
-        ScrollView { /* content */ }
-            .userActivity("com.example.viewItem") { activity in
-                activity.title = item.title
-                activity.isEligibleForHandoff = true
-                activity.isEligibleForSearch = true
-                activity.targetContentIdentifier = item.id.uuidString
-                activity.webpageURL = URL(string: "https://example.com/items/\(item.id)")
+        TrailSummary(trail: trail)
+            .userActivity("org.sample.hiker.viewTrail") { current in
+                current.title = trail.name
+                current.targetContentIdentifier = trail.id
+                current.webpageURL = URL(string: "https://yourdomain.example/trail/\(trail.id)")
+                current.isEligibleForSearch = true
+                current.isEligibleForHandoff = true
             }
     }
 }
-```
 
-### Receiving a continued activity
+struct RootView: View {
+    @Environment(Router.self) private var nav
 
-```swift
-.onContinueUserActivity("com.example.viewItem") { activity in
-    guard let id = activity.targetContentIdentifier else { return }
-    router.navigate(to: .item(id: id))
+    var body: some View {
+        MainTabs()
+            .onContinueUserActivity("org.sample.hiker.viewTrail") { resumed in
+                guard let trailID = resumed.targetContentIdentifier else { return }
+                nav.push(.trail(id: trailID))
+            }
+    }
 }
 ```
 
-Key rules:
-- Activity types must be declared in `Info.plist` under `NSUserActivityTypes`.
-- Set `isEligibleForHandoff = true` and optionally `isEligibleForSearch` / `isEligibleForPrediction`.
-- Provide a `webpageURL` as fallback when the app is not installed on the receiving device.
+- List every activity type in the Info.plist `NSUserActivityTypes` array.
+- `isEligibleForSearch` and `isEligibleForPrediction` are optional extras.
+- `webpageURL` is where the other device goes when it does not have the app.

package/pipeline/skills/shared/external/swiftui-navigation/references/navigationstack.md

@@ -1,177 +1,176 @@
-# NavigationStack
+# NavigationStack and Routers
 
-## Contents
+Part of the `swiftui-navigation` skill. Use this when navigation is driven from
+code or from deep links and every tab needs a history of its own: one
+`NavigationStack` per tab, each bound to its own path and router.
 
-- [Intent](#intent)
-- [Core architecture](#core-architecture)
-- [Example: custom router with per-tab stack](#example-custom-router-with-per-tab-stack)
-- [Example: centralized destination mapping](#example-centralized-destination-mapping)
-- [Example: binding per tab (tabs with independent history)](#example-binding-per-tab-tabs-with-independent-history)
-- [Example: generic tabs with per-tab NavigationStack](#example-generic-tabs-with-per-tab-navigationstack)
-- [Design choices to keep](#design-choices-to-keep)
-- [Pitfalls](#pitfalls)
+## Building blocks
 
-## Intent
+- A `Hashable` route enum that names every screen you can push.
+- A small router object holding both the navigation path and any sheet state. A packaged
+  router such as AppRouter (https://github.com/Dimillian/AppRouter) works the
+  same way.
+- One router per tab, with `NavigationStack(path:)` bound to that router.
+- The router placed in the environment, so any child can navigate.
+- Destinations mapped once: one `navigationDestination(for:)` switch, or the
+  same switch wrapped in a `withAppRouter()` modifier.
 
-Use this pattern for programmatic navigation and deep links, especially when each tab needs an independent navigation history. The key idea is one `NavigationStack` per tab, each with its own path binding and router object.
-
-## Core architecture
-
-- Define a route enum that is `Hashable` and represents all destinations.
-- Create a lightweight router (or use a library such as `https://github.com/Dimillian/AppRouter`) that owns the `path` and any sheet state.
-- Each tab owns its own router instance and binds `NavigationStack(path:)` to it.
-- Inject the router into the environment so child views can navigate programmatically.
-- Centralize destination mapping with a single `navigationDestination(for:)` block (or a `withAppRouter()` modifier).
-
-## Example: custom router with per-tab stack
+## A router with a per-tab stack
 
 ```swift
-@MainActor
-@Observable
-final class RouterPath {
-  var path: [Route] = []
-  var presentedSheet: SheetDestination?
-
-  func navigate(to route: Route) {
-    path.append(route)
-  }
-
-  func reset() {
-    path = []
-  }
-}
+import SwiftUI
+import Observation
 
 enum Route: Hashable {
-  case account(id: String)
-  case status(id: String)
+    case trail(id: Trail.ID)
+    case ranger(id: Ranger.ID)
+    case photos(trailID: Trail.ID)
+}
+
+@MainActor @Observable
+final class Router {
+    var presentedSheet: SheetDestination?
+    var path: [Route] = []
+
+    func popToRoot() { path.removeAll() }
+    func push(_ next: Route) { path.append(next) }
 }
 
-@MainActor
-struct TimelineTab: View {
-  @State private var routerPath = RouterPath()
-
-  var body: some View {
-    NavigationStack(path: $routerPath.path) {
-      TimelineView()
-        .navigationDestination(for: Route.self) { route in
-          switch route {
-          case .account(let id): AccountView(id: id)
-          case .status(let id): StatusView(id: id)
-          }
+struct ExploreTab: View {
+    @State private var nav = Router()
+
+    var body: some View {
+        NavigationStack(path: $nav.path) {
+            ExploreHome()
+                .navigationDestination(for: Route.self) { target in
+                    switch target {
+                    case .trail(let id): TrailDetailView(trailID: id)
+                    case .ranger(let id): RangerView(rangerID: id)
+                    case .photos(let id): PhotoGridView(trailID: id)
+                    }
+                }
         }
+        .environment(nav)
     }
-    .environment(routerPath)
-  }
 }
 ```
 
-## Example: centralized destination mapping
+The path here is a plain `[Route]` array. That is often simpler than a
+`NavigationPath` when every destination is the same enum.
+
+## Mapping destinations once
 
-Use a shared view modifier to avoid duplicating route switches across screens.
+Put the switch in a modifier and apply it at the root of each stack, so no
+screen repeats it.
 
 ```swift
 extension View {
-  func withAppRouter() -> some View {
-    navigationDestination(for: Route.self) { route in
-      switch route {
-      case .account(let id):
-        AccountView(id: id)
-      case .status(let id):
-        StatusView(id: id)
-      }
+    func withAppRouter() -> some View {
+        navigationDestination(for: Route.self) { target in
+            switch target {
+            case .trail(let id): TrailDetailView(trailID: id)
+            case .ranger(let id): RangerView(rangerID: id)
+            case .photos(let id): PhotoGridView(trailID: id)
+            }
+        }
     }
-  }
 }
 ```
 
-Then apply it once per stack:
+## One router per tab
+
+The tab container keeps a separate router in `@State` for each tab and hands
+each one to its tab.
 
 ```swift
-NavigationStack(path: $routerPath.path) {
-  TimelineView()
-    .withAppRouter()
+enum LibraryTab: Hashable { case explore, saved }
+
+struct MainTabs: View {
+    @State private var exploreRouter = Router()
+    @State private var savedRouter = Router()
+    @State private var tab: LibraryTab = .explore
+
+    var body: some View {
+        TabView(selection: $tab) {
+            Tab("Explore", systemImage: "map", value: LibraryTab.explore) {
+                ExploreStack(router: exploreRouter)
+            }
+            Tab("Saved", systemImage: "bookmark", value: LibraryTab.saved) {
+                SavedStack(router: savedRouter)
+            }
+        }
+    }
 }
-```
 
-## Example: binding per tab (tabs with independent history)
+struct ExploreStack: View {
+    @Bindable var router: Router
 
-```swift
-@MainActor
-struct TabsView: View {
-  @State private var selectedTab: AppTab = .timeline
-  @State private var timelineRouter = RouterPath()
-  @State private var notificationsRouter = RouterPath()
-
-  var body: some View {
-    TabView(selection: $selectedTab) {
-      Tab("Timeline", systemImage: "text.bubble", value: .timeline) {
-        TimelineTab(router: timelineRouter)
-      }
-      Tab("Notifications", systemImage: "bell", value: .notifications) {
-        NotificationsTab(router: notificationsRouter)
-      }
+    var body: some View {
+        NavigationStack(path: $router.path) { ExploreHome().withAppRouter() }
+            .environment(router)
     }
-  }
 }
 ```
 
-## Example: generic tabs with per-tab NavigationStack
+## Data-driven tabs, each with its own stack
 
-Use this when tabs are built from data and each needs its own path without hard-coded names.
+When the tab list comes from data, a `TabRouter` creates a `Router` for a tab
+the first time it is asked, caches it, and builds path bindings on demand.
 
 ```swift
-@MainActor
-struct TabsView: View {
-  @State private var selectedTab: AppTab = .timeline
-  @State private var tabRouter = TabRouter()
-
-  var body: some View {
-    TabView(selection: $selectedTab) {
-      ForEach(AppTab.allCases) { tab in
-        Tab(value: tab) {
-          NavigationStack(path: tabRouter.binding(for: tab)) {
-            tab.makeContentView()
-          }
-          .environment(tabRouter.router(for: tab))
-        } label: {
-          tab.label
-        }
-      }
+@MainActor @Observable
+final class TabRouter {
+    private var cache: [AppTab: Router] = [:]
+
+    func router(for key: AppTab) -> Router {
+        if let known = cache[key] { return known }
+        let made = Router()
+        cache[key] = made
+        return made
+    }
+
+    func binding(for key: AppTab) -> Binding<[Route]> {
+        let owner = router(for: key)
+        return Binding(get: { owner.path }, set: { owner.path = $0 })
     }
-  }
 }
-```
 
-`@MainActor`
-`@Observable`
-final class TabRouter {
-  private var routers: [AppTab: RouterPath] = [:]
-
-  func router(for tab: AppTab) -> RouterPath {
-    if let router = routers[tab] { return router }
-    let router = RouterPath()
-    routers[tab] = router
-    return router
-  }
-
-  func binding(for tab: AppTab) -> Binding<[Route]> {
-    let router = router(for: tab)
-    return Binding(get: { router.path }, set: { router.path = $0 })
-  }
+struct DynamicTabs: View {
+    @State private var selected: AppTab = .home
+    @State private var routers = TabRouter()
+
+    var body: some View {
+        TabView(selection: $selected) {
+            ForEach(AppTab.allCases) { item in
+                Tab(value: item) {
+                    NavigationStack(path: routers.binding(for: item)) {
+                        item.rootView.withAppRouter()
+                    }
+                    .environment(routers.router(for: item))
+                } label: {
+                    item.label
+                }
+            }
+        }
+    }
 }
+```
 
-## Design choices to keep
+## Rules worth keeping
 
-- One `NavigationStack` per tab to preserve independent history.
-- A single source of truth for navigation state (`RouterPath` or library router).
-- Use `navigationDestination(for:)` to map routes to views.
-- Reset the path when app context changes (account switch, logout, etc.).
-- Inject the router into the environment so child views can navigate and present sheets without prop-drilling.
-- Keep sheet presentation state on the router if you want a single place to manage modals.
+- One stack per tab, so each tab remembers where the user was.
+- One owner of navigation state: your router or the packaged one, never both.
+- Push through route values mapped by `navigationDestination(for:)`.
+- Clear the path when the app context changes, such as switching accounts or
+  signing out.
+- Put the router in the environment so navigation and sheets need no bindings
+  passed through intermediate views.
+- Sheet state may also live on the router, so modals have one home.
 
 ## Pitfalls
 
-- Do not share one path across all tabs unless you want global history.
-- Ensure route identifiers are stable and `Hashable`.
-- Avoid storing view instances in the path; store lightweight route data instead.
-- If using a router object, keep it outside other `@Observable` objects to avoid nested observation.
+- A path shared across tabs, unless you really want one global history.
+- Route identifiers that are not stable or not `Hashable`.
+- View instances stored in the path instead of route data.
+- A router stored inside another `@Observable` object; keep it standalone to
+  avoid nested observation.