@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/swiftui-navigation/references/deeplinks.md

@@ -0,0 +1,207 @@
+# Deep links and navigation
+
+## Intent
+
+Route external URLs into in-app destinations while falling back to system handling when needed.
+
+## 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.
+
+## Example: router entry points
+
+```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
+    }
+    return urlHandler?(url) ?? .systemAction
+  }
+
+  func handleDeepLink(url: URL) -> OpenURLAction.Result {
+    // Resolve federated URLs, then navigate.
+    navigate(to: .status(id: url.lastPathComponent))
+    return .handled
+  }
+}
+```
+
+## Example: attach to a root view
+
+```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)
+      }
+  }
+}
+```
+
+## 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
+
+- Don’t assume the URL is internal; validate first.
+- Avoid blocking UI while resolving remote links; use `Task`.
+
+## 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.
+
+### 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`):
+
+```json
+{
+  "applinks": {
+    "details": [
+      {
+        "appIDs": ["TEAMID.com.example.app"],
+        "components": [
+          { "/": "/items/*", "comment": "Match item detail paths" },
+          { "/": "/profile/*" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+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"
+]
+```
+
+For development/testing, prefix with `applinks:example.com?mode=developer` to bypass the CDN cache.
+
+### 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)
+                }
+        }
+    }
+}
+```
+
+> **Docs:** [Supporting universal links](https://sosumi.ai/documentation/xcode/supporting-universal-links-in-your-app)
+
+## Custom URL Schemes
+
+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.
+
+### Registering in Info.plist
+
+Add `CFBundleURLTypes` to your target's Info.plist:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>myapp</string>
+    </array>
+    <key>CFBundleURLName</key>
+    <string>com.example.myapp</string>
+  </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)
+}
+```
+
+Prefer universal links over custom schemes for publicly shared links — they provide a better UX (web fallback) and are more secure (domain-verified).
+
+## NSUserActivity Continuation (Handoff)
+
+Handoff lets users start an activity on one device and continue it on another. SwiftUI provides `.onContinueUserActivity` and `.userActivity` modifiers.
+
+### Advertising an activity
+
+```swift
+struct ItemDetailView: View {
+    let item: Item
+
+    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)")
+            }
+    }
+}
+```
+
+### Receiving a continued activity
+
+```swift
+.onContinueUserActivity("com.example.viewItem") { activity in
+    guard let id = activity.targetContentIdentifier else { return }
+    router.navigate(to: .item(id: id))
+}
+```
+
+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.

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/swiftui-navigation/references/navigationstack.md

@@ -0,0 +1,177 @@
+# NavigationStack
+
+## Contents
+
+- [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)
+
+## Intent
+
+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
+
+```swift
+@MainActor
+@Observable
+final class RouterPath {
+  var path: [Route] = []
+  var presentedSheet: SheetDestination?
+
+  func navigate(to route: Route) {
+    path.append(route)
+  }
+
+  func reset() {
+    path = []
+  }
+}
+
+enum Route: Hashable {
+  case account(id: String)
+  case status(id: String)
+}
+
+@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)
+          }
+        }
+    }
+    .environment(routerPath)
+  }
+}
+```
+
+## Example: centralized destination mapping
+
+Use a shared view modifier to avoid duplicating route switches across screens.
+
+```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)
+      }
+    }
+  }
+}
+```
+
+Then apply it once per stack:
+
+```swift
+NavigationStack(path: $routerPath.path) {
+  TimelineView()
+    .withAppRouter()
+}
+```
+
+## Example: binding per tab (tabs with independent history)
+
+```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)
+      }
+    }
+  }
+}
+```
+
+## Example: generic tabs with per-tab NavigationStack
+
+Use this when tabs are built from data and each needs its own path without hard-coded names.
+
+```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 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 })
+  }
+}
+
+## Design choices to keep
+
+- 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.
+
+## 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.

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/swiftui-navigation/references/sheets.md

@@ -0,0 +1,169 @@
+# Sheets
+
+## Contents
+
+- [Intent](#intent)
+- [Core architecture](#core-architecture)
+- [Example: SheetDestination enum](#example-sheetdestination-enum)
+- [Example: withSheetDestinations modifier](#example-withsheetdestinations-modifier)
+- [Example: presenting from a child view](#example-presenting-from-a-child-view)
+- [Required wiring](#required-wiring)
+- [Example: sheets that need their own navigation](#example-sheets-that-need-their-own-navigation)
+- [Design choices to keep](#design-choices-to-keep)
+- [iOS 26 Presentation Sizing](#ios-26-presentation-sizing)
+- [Pitfalls](#pitfalls)
+
+## Intent
+
+Use a centralized sheet routing pattern so any view can present modals without prop-drilling. This keeps sheet state in one place and scales as the app grows.
+
+## Core architecture
+
+- Define a `SheetDestination` enum that describes every modal and is `Identifiable`.
+- Store the current sheet in a router object (`presentedSheet: SheetDestination?`).
+- Create a view modifier like `withSheetDestinations(...)` that maps the enum to concrete sheet views.
+- Inject the router into the environment so child views can set `presentedSheet` directly.
+
+## Example: SheetDestination enum
+
+```swift
+enum SheetDestination: Identifiable, Hashable {
+  case composer
+  case editProfile
+  case settings
+  case report(itemID: String)
+
+  var id: String {
+    switch self {
+    case .composer, .editProfile:
+      // Use the same id to ensure only one editor-like sheet is active at a time.
+      return "editor"
+    case .settings:
+      return "settings"
+    case .report:
+      return "report"
+    }
+  }
+}
+```
+
+## Example: withSheetDestinations modifier
+
+```swift
+extension View {
+  func withSheetDestinations(
+    sheet: Binding<SheetDestination?>
+  ) -> some View {
+    sheet(item: sheet) { destination in
+      Group {
+        switch destination {
+        case .composer:
+          ComposerView()
+        case .editProfile:
+          EditProfileView()
+        case .settings:
+          SettingsView()
+        case .report(let itemID):
+          ReportView(itemID: itemID)
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: presenting from a child view
+
+```swift
+struct StatusRow: View {
+  @Environment(RouterPath.self) private var router
+
+  var body: some View {
+    Button("Report") {
+      router.presentedSheet = .report(itemID: "123")
+    }
+  }
+}
+```
+
+## Required wiring
+
+For the child view to work, a parent view must:
+- own the router instance,
+- attach `withSheetDestinations(sheet: $router.presentedSheet)` (or an equivalent `sheet(item:)` handler), and
+- inject it with `.environment(router)` after the sheet modifier so the modal content inherits it.
+
+This makes the child assignment to `router.presentedSheet` drive presentation at the root.
+
+## Example: sheets that need their own navigation
+
+Wrap sheet content in a `NavigationStack` so it can push within the modal.
+
+```swift
+struct NavigationSheet<Content: View>: View {
+  var content: () -> Content
+
+  var body: some View {
+    NavigationStack {
+      content()
+        .toolbar { CloseToolbarItem() }
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Centralize sheet routing so features can present modals without wiring bindings through many layers.
+- Use `sheet(item:)` to guarantee a single sheet is active and to drive presentation from the enum.
+- Group related sheets under the same `id` when they are mutually exclusive (e.g., editor flows).
+- Keep sheet views lightweight and composed from smaller views; avoid large monoliths.
+
+## iOS 26 Presentation Sizing
+
+Control sheet dimensions with `presentationSizing(_:)` (iOS 18+):
+
+```swift
+.sheet(item: $selectedItem) { item in
+    EditItemSheet(item: item)
+        .presentationSizing(.form)
+}
+```
+
+`PresentationSizing` values:
+- `.automatic` -- platform default
+- `.page` -- roughly paper size, for informational content
+- `.form` -- slightly narrower than page, for form-style UI
+- `.fitted` -- sized by the content's ideal size
+
+Modifier methods for fine-tuning:
+- `.fitted(horizontal:vertical:)` -- constrain fitting to specific axes
+- `.sticky(horizontal:vertical:)` -- grow but do not shrink in specified dimensions
+
+### Dismissal Confirmation (macOS 15+ / iOS 26+)
+
+Show a confirmation dialog when the user tries to dismiss a sheet with unsaved changes:
+
+```swift
+.sheet(item: $selectedItem) { item in
+    EditItemSheet(item: item)
+        .dismissalConfirmationDialog(
+            "Discard changes?",
+            shouldPresent: hasUnsavedChanges
+        ) {
+            Button("Discard", role: .destructive) { discardChanges() }
+        }
+}
+```
+
+- Cancel action is included automatically and prevents dismissal
+- All other action buttons allow dismissal to proceed
+- Use `.keyboardShortcut(.defaultAction)` to set the default button
+
+## Pitfalls
+
+- Avoid mixing `sheet(isPresented:)` and `sheet(item:)` for the same concern; prefer a single enum.
+- Do not store heavy state inside `SheetDestination`; pass lightweight identifiers or models.
+- If multiple sheets can appear from the same screen, give them distinct `id` values.
+- Use `presentationSizing(.form)` for form sheets instead of hard-coding frame dimensions.
+- Always pair `dismissalConfirmationDialog` with a `shouldPresent` condition; showing it when there are no changes is confusing.