@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/natural-language/references/translation-patterns.md

@@ -0,0 +1,311 @@
+# NaturalLanguage + Translation Extended Patterns
+
+Overflow reference for the `natural-language` skill. Contains advanced patterns
+that exceed the main skill file's scope.
+
+## Contents
+
+- [Custom NLModel Integration](#custom-nlmodel-integration)
+- [Contextual Embeddings](#contextual-embeddings)
+- [Gazetteers for Domain Vocabulary](#gazetteers-for-domain-vocabulary)
+- [NLTagger with Multiple Schemes](#nltagger-with-multiple-schemes)
+- [Translation with Replacement Action](#translation-with-replacement-action)
+- [Translation Session Strategies](#translation-session-strategies)
+- [SwiftUI Integration Patterns](#swiftui-integration-patterns)
+- [Lemmatization](#lemmatization)
+
+## Custom NLModel Integration
+
+Load a Create ML text classifier or word tagger into `NLTagger` via `NLModel`.
+
+```swift
+import NaturalLanguage
+import CoreML
+
+func setupCustomTagger() throws -> NLTagger {
+    let mlModel = try MLModel(contentsOf: modelURL)
+    let nlModel = try NLModel(mlModel: mlModel)
+
+    let tagger = NLTagger(tagSchemes: [.nameType])
+    tagger.setModels([nlModel], forTagScheme: .nameType)
+    return tagger
+}
+
+// Direct prediction without a tagger
+func classifyText(_ text: String) throws -> String? {
+    let mlModel = try MLModel(contentsOf: modelURL)
+    let nlModel = try NLModel(mlModel: mlModel)
+    return nlModel.predictedLabel(for: text)
+}
+
+// Predictions with confidence scores
+func classifyWithConfidence(_ text: String) throws -> [String: Double] {
+    let mlModel = try MLModel(contentsOf: modelURL)
+    let nlModel = try NLModel(mlModel: mlModel)
+    return nlModel.predictedLabelHypotheses(for: text, maximumCount: 5)
+}
+```
+
+## Contextual Embeddings
+
+`NLContextualEmbedding` produces context-aware vectors where the same word
+gets different vectors based on surrounding text.
+
+```swift
+import NaturalLanguage
+
+func contextualVectors(for text: String) throws -> [([Double], Range<String.Index>)] {
+    guard let embedding = NLContextualEmbedding(language: .english) else {
+        return []
+    }
+
+    // Check and load assets
+    guard embedding.hasAvailableAssets else {
+        embedding.requestAssets { result, error in
+            // Handle download
+        }
+        return []
+    }
+
+    try embedding.load()
+    defer { embedding.unload() }
+
+    let result = try embedding.embeddingResult(for: text, language: .english)
+    var vectors: [([Double], Range<String.Index>)] = []
+
+    result.enumerateTokenVectors(in: text.startIndex..<text.endIndex) { vector, range in
+        vectors.append((vector, range))
+        return true
+    }
+    return vectors
+}
+```
+
+### Finding Available Contextual Embeddings
+
+```swift
+let embeddings = NLContextualEmbedding.contextualEmbeddings(forValues: [
+    .languages: [NLLanguage.english.rawValue]
+])
+
+for embedding in embeddings {
+    print("Model: \(embedding.modelIdentifier)")
+    print("Dimension: \(embedding.dimension)")
+    print("Max length: \(embedding.maximumSequenceLength)")
+}
+```
+
+## Gazetteers for Domain Vocabulary
+
+Override or supplement tagger results with custom term-to-label mappings.
+
+```swift
+func setupGazetteer() throws -> NLTagger {
+    let dictionary: [String: [String]] = [
+        "PRODUCT": ["iPhone", "MacBook Pro", "Apple Watch"],
+        "FEATURE": ["Dynamic Island", "ProMotion", "MagSafe"]
+    ]
+
+    let gazetteer = try NLGazetteer(dictionary: dictionary, language: .english)
+    let tagger = NLTagger(tagSchemes: [.nameType])
+    tagger.setGazetteers([gazetteer], for: .nameType)
+    return tagger
+}
+
+// Persist a gazetteer to disk
+func saveGazetteer(_ dictionary: [String: [String]], to url: URL) throws {
+    try NLGazetteer.write(dictionary, language: .english, to: url)
+}
+```
+
+## NLTagger with Multiple Schemes
+
+Request multiple tag schemes in a single tagger for efficient processing.
+
+```swift
+func analyzeText(_ text: String) {
+    let tagger = NLTagger(tagSchemes: [.lexicalClass, .nameType, .lemma])
+    tagger.string = text
+
+    let range = text.startIndex..<text.endIndex
+    let options: NLTagger.Options = [.omitWhitespace, .omitPunctuation, .joinNames]
+
+    tagger.enumerateTags(in: range, unit: .word, scheme: .nameTypeOrLexicalClass,
+                         options: options) { tag, tokenRange in
+        let word = String(text[tokenRange])
+        let (lemmaTag, _) = tagger.tag(at: tokenRange.lowerBound,
+                                        unit: .word, scheme: .lemma)
+        let lemma = lemmaTag?.rawValue ?? word
+        print("\(word) -> tag: \(tag?.rawValue ?? "?"), lemma: \(lemma)")
+        return true
+    }
+}
+```
+
+## Translation with Replacement Action
+
+Replace the source text in-place after translation using the replacement action.
+
+```swift
+import SwiftUI
+import Translation
+
+struct EditableTranslationView: View {
+    @State private var text = "Hello, how are you?"
+    @State private var showTranslation = false
+
+    var body: some View {
+        TextEditor(text: $text)
+            .toolbar {
+                Button("Translate") { showTranslation = true }
+            }
+            .translationPresentation(
+                isPresented: $showTranslation,
+                text: text,
+                replacementAction: { translated in
+                    text = translated
+                }
+            )
+    }
+}
+```
+
+## Translation Session Strategies
+
+Control whether translations prioritize quality or speed.
+
+```swift
+import Translation
+
+// High fidelity: best quality, may use server
+let highQualityConfig = TranslationSession.Configuration(
+    source: Locale.Language(identifier: "en"),
+    target: Locale.Language(identifier: "ja"),
+    preferredStrategy: .highFidelity
+)
+
+// Low latency: faster, prefers on-device models
+let fastConfig = TranslationSession.Configuration(
+    source: Locale.Language(identifier: "en"),
+    target: Locale.Language(identifier: "ja"),
+    preferredStrategy: .lowLatency
+)
+```
+
+### Preparing a Translation Session
+
+Pre-download models before translating to avoid UI delays.
+
+```swift
+.translationTask(configuration) { session in
+    try await session.prepareTranslation()
+    // Models are now ready, translate without delay
+    let response = try await session.translate(sourceText)
+    translatedText = response.targetText
+}
+```
+
+## SwiftUI Integration Patterns
+
+### Language Analysis View
+
+```swift
+import SwiftUI
+import NaturalLanguage
+
+@Observable
+@MainActor
+final class TextAnalyzer {
+    var tokens: [String] = []
+    var detectedLanguage: String = ""
+    var sentimentLabel: String = ""
+
+    func analyze(_ text: String) {
+        guard !text.isEmpty else { return }
+
+        // Tokenize
+        let tokenizer = NLTokenizer(unit: .word)
+        tokenizer.string = text
+        tokens = tokenizer.tokens(for: text.startIndex..<text.endIndex)
+            .map { String(text[$0]) }
+
+        // Language
+        detectedLanguage = NLLanguageRecognizer.dominantLanguage(for: text)?
+            .rawValue ?? "Unknown"
+
+        // Sentiment
+        let tagger = NLTagger(tagSchemes: [.sentimentScore])
+        tagger.string = text
+        let (tag, _) = tagger.tag(at: text.startIndex, unit: .paragraph,
+                                   scheme: .sentimentScore)
+        if let score = tag.flatMap({ Double($0.rawValue) }) {
+            sentimentLabel = score > 0.1 ? "Positive" :
+                             score < -0.1 ? "Negative" : "Neutral"
+        }
+    }
+}
+
+struct TextAnalysisView: View {
+    @State private var text = ""
+    @State private var analyzer = TextAnalyzer()
+
+    var body: some View {
+        Form {
+            TextField("Enter text", text: $text)
+                .onChange(of: text) { _, newValue in
+                    analyzer.analyze(newValue)
+                }
+            Section("Results") {
+                LabeledContent("Language", value: analyzer.detectedLanguage)
+                LabeledContent("Sentiment", value: analyzer.sentimentLabel)
+                LabeledContent("Words", value: "\(analyzer.tokens.count)")
+            }
+        }
+    }
+}
+```
+
+### Requesting NLTagger Assets
+
+Some tag schemes require downloadable assets. Request them before tagging.
+
+```swift
+NLTagger.requestAssets(for: .japanese, tagScheme: .nameType) { result, error in
+    switch result {
+    case .available:
+        // Assets loaded, safe to tag Japanese text
+        break
+    case .notAvailable:
+        // Assets not available for this language/scheme
+        break
+    case .error:
+        print("Asset request error: \(error?.localizedDescription ?? "")")
+    @unknown default:
+        break
+    }
+}
+```
+
+## Lemmatization
+
+Get the base form of words for indexing or search normalization.
+
+```swift
+func lemmatize(_ text: String) -> [String] {
+    let tagger = NLTagger(tagSchemes: [.lemma])
+    tagger.string = text
+
+    var lemmas: [String] = []
+    tagger.enumerateTags(
+        in: text.startIndex..<text.endIndex,
+        unit: .word,
+        scheme: .lemma,
+        options: [.omitPunctuation, .omitWhitespace]
+    ) { tag, range in
+        lemmas.append(tag?.rawValue ?? String(text[range]))
+        return true
+    }
+    return lemmas
+}
+// "The cats were running quickly" -> ["the", "cat", "be", "run", "quickly"]
+```

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/passkit-wallet/SKILL.md

@@ -0,0 +1,398 @@
+---
+name: passkit-wallet
+description: "Integrate Apple Pay payments and Wallet passes using PassKit. Use when adding Apple Pay buttons, creating payment requests, handling payment authorization, adding passes to Wallet, configuring merchant capabilities, managing shipping and contact fields, or working with PKPaymentRequest, PKPaymentAuthorizationController, PKPaymentButton, PKPass, PKAddPassesViewController, PKPassLibrary, or Apple Pay checkout flows."
+---
+
+# PassKit — Apple Pay & Wallet
+
+Accept Apple Pay payments for physical goods and services, and add passes to
+the user's Wallet. Covers payment buttons, payment requests, authorization,
+Wallet passes, and merchant configuration. Targets Swift 6.2 / iOS 26+.
+
+## Contents
+
+- [Setup](#setup)
+- [Displaying the Apple Pay Button](#displaying-the-apple-pay-button)
+- [Creating a Payment Request](#creating-a-payment-request)
+- [Presenting the Payment Sheet](#presenting-the-payment-sheet)
+- [Handling Payment Authorization](#handling-payment-authorization)
+- [Wallet Passes](#wallet-passes)
+- [Checking Pass Library](#checking-pass-library)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+## Setup
+
+### Project Configuration
+
+1. Enable the **Apple Pay** capability in Xcode
+2. Create a Merchant ID in the Apple Developer portal (format: `merchant.com.example.app`)
+3. Generate and install a Payment Processing Certificate for your merchant ID
+4. Add the merchant ID to your entitlements
+
+### Availability Check
+
+Always verify the device can make payments before showing Apple Pay UI.
+
+```swift
+import PassKit
+
+func canMakePayments() -> Bool {
+    // Check device supports Apple Pay at all
+    guard PKPaymentAuthorizationController.canMakePayments() else {
+        return false
+    }
+    // Check user has cards for the networks you support
+    return PKPaymentAuthorizationController.canMakePayments(
+        usingNetworks: [.visa, .masterCard, .amex, .discover],
+        capabilities: .threeDSecure
+    )
+}
+```
+
+## Displaying the Apple Pay Button
+
+### SwiftUI
+
+Use the built-in `PayWithApplePayButton` view in SwiftUI.
+
+```swift
+import SwiftUI
+import PassKit
+
+struct CheckoutView: View {
+    var body: some View {
+        PayWithApplePayButton(.buy) {
+            startPayment()
+        }
+        .payWithApplePayButtonStyle(.black)
+        .frame(height: 48)
+        .padding()
+    }
+}
+```
+
+### UIKit
+
+Use `PKPaymentButton` for UIKit-based interfaces.
+
+```swift
+let button = PKPaymentButton(
+    paymentButtonType: .buy,
+    paymentButtonStyle: .black
+)
+button.cornerRadius = 12
+button.addTarget(self, action: #selector(startPayment), for: .touchUpInside)
+```
+
+**Button types:** `.buy`, `.setUp`, `.inStore`, `.donate`, `.checkout`, `.book`, `.subscribe`, `.reload`, `.addMoney`, `.topUp`, `.order`, `.rent`, `.support`, `.contribute`, `.tip`
+
+## Creating a Payment Request
+
+Build a `PKPaymentRequest` with your merchant details and the items being purchased.
+
+```swift
+func createPaymentRequest() -> PKPaymentRequest {
+    let request = PKPaymentRequest()
+    request.merchantIdentifier = "merchant.com.example.app"
+    request.countryCode = "US"
+    request.currencyCode = "USD"
+    request.supportedNetworks = [.visa, .masterCard, .amex, .discover]
+    request.merchantCapabilities = .threeDSecure
+
+    request.paymentSummaryItems = [
+        PKPaymentSummaryItem(label: "Widget", amount: 9.99),
+        PKPaymentSummaryItem(label: "Shipping", amount: 4.99),
+        PKPaymentSummaryItem(label: "My Store", amount: 14.98) // Total (last item)
+    ]
+
+    return request
+}
+```
+
+The **last item** in `paymentSummaryItems` is treated as the total and its label appears as the merchant name on the payment sheet.
+
+### Requesting Shipping and Contact Info
+
+```swift
+request.requiredShippingContactFields = [.postalAddress, .emailAddress, .name]
+request.requiredBillingContactFields = [.postalAddress]
+
+request.shippingMethods = [
+    PKShippingMethod(label: "Standard", amount: 4.99),
+    PKShippingMethod(label: "Express", amount: 9.99),
+]
+request.shippingMethods?[0].identifier = "standard"
+request.shippingMethods?[0].detail = "5-7 business days"
+request.shippingMethods?[1].identifier = "express"
+request.shippingMethods?[1].detail = "1-2 business days"
+
+request.shippingType = .shipping // .delivery, .storePickup, .servicePickup
+```
+
+### Supported Networks
+
+| Network | Constant |
+|---|---|
+| Visa | `.visa` |
+| Mastercard | `.masterCard` |
+| American Express | `.amex` |
+| Discover | `.discover` |
+| China UnionPay | `.chinaUnionPay` |
+| JCB | `.JCB` |
+| Maestro | `.maestro` |
+| Electron | `.electron` |
+| Interac | `.interac` |
+
+Query available networks at runtime with `PKPaymentRequest.availableNetworks()`.
+
+## Presenting the Payment Sheet
+
+Use `PKPaymentAuthorizationController` (works in both SwiftUI and UIKit, no view controller needed).
+
+```swift
+@MainActor
+func startPayment() {
+    let request = createPaymentRequest()
+    let controller = PKPaymentAuthorizationController(paymentRequest: request)
+    controller.delegate = self
+    controller.present()
+}
+```
+
+## Handling Payment Authorization
+
+Implement `PKPaymentAuthorizationControllerDelegate` to process the payment token.
+
+```swift
+extension CheckoutCoordinator: PKPaymentAuthorizationControllerDelegate {
+    func paymentAuthorizationController(
+        _ controller: PKPaymentAuthorizationController,
+        didAuthorizePayment payment: PKPayment,
+        handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
+    ) {
+        // Send payment.token.paymentData to your payment processor
+        Task {
+            do {
+                try await paymentService.process(payment.token)
+                completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
+            } catch {
+                completion(PKPaymentAuthorizationResult(status: .failure, errors: [error]))
+            }
+        }
+    }
+
+    func paymentAuthorizationControllerDidFinish(
+        _ controller: PKPaymentAuthorizationController
+    ) {
+        controller.dismiss()
+    }
+}
+```
+
+### Handling Shipping Changes
+
+```swift
+func paymentAuthorizationController(
+    _ controller: PKPaymentAuthorizationController,
+    didSelectShippingMethod shippingMethod: PKShippingMethod,
+    handler completion: @escaping (PKPaymentRequestShippingMethodUpdate) -> Void
+) {
+    let updatedItems = recalculateItems(with: shippingMethod)
+    let update = PKPaymentRequestShippingMethodUpdate(paymentSummaryItems: updatedItems)
+    completion(update)
+}
+```
+
+## Wallet Passes
+
+### Adding a Pass to Wallet
+
+Load a `.pkpass` file and present `PKAddPassesViewController`.
+
+```swift
+func addPassToWallet(data: Data) {
+    guard let pass = try? PKPass(data: data) else { return }
+
+    if let addController = PKAddPassesViewController(pass: pass) {
+        addController.delegate = self
+        present(addController, animated: true)
+    }
+}
+```
+
+### SwiftUI Wallet Button
+
+```swift
+import PassKit
+import SwiftUI
+
+struct AddPassButton: View {
+    let passData: Data
+
+    var body: some View {
+        Button("Add to Wallet") {
+            addPass()
+        }
+    }
+
+    func addPass() {
+        guard let pass = try? PKPass(data: passData) else { return }
+        let library = PKPassLibrary()
+        library.addPasses([pass]) { status in
+            switch status {
+            case .shouldReviewPasses:
+                // Present review UI
+                break
+            case .didAddPasses:
+                // Passes added successfully
+                break
+            case .didCancelAddPasses:
+                break
+            @unknown default:
+                break
+            }
+        }
+    }
+}
+```
+
+## Checking Pass Library
+
+Use `PKPassLibrary` to inspect and manage passes the user already has.
+
+```swift
+let library = PKPassLibrary()
+
+// Check if a specific pass is already in Wallet
+let hasPass = library.containsPass(pass)
+
+// Retrieve passes your app can access
+let passes = library.passes()
+
+// Check if pass library is available
+guard PKPassLibrary.isPassLibraryAvailable() else { return }
+```
+
+## Common Mistakes
+
+### DON'T: Use StoreKit for physical goods
+
+Apple Pay (PassKit) is for **physical goods and services**. StoreKit is for digital
+content, subscriptions, and in-app purchases. Using the wrong framework leads to
+App Review rejection.
+
+```swift
+// WRONG: Using StoreKit to sell a physical product
+let product = try await Product.products(for: ["com.example.tshirt"])
+
+// CORRECT: Use Apple Pay for physical goods
+let request = PKPaymentRequest()
+request.paymentSummaryItems = [
+    PKPaymentSummaryItem(label: "T-Shirt", amount: 29.99),
+    PKPaymentSummaryItem(label: "My Store", amount: 29.99)
+]
+```
+
+### DON'T: Hardcode merchant ID in multiple places
+
+```swift
+// WRONG: Merchant ID scattered across the codebase
+let request1 = PKPaymentRequest()
+request1.merchantIdentifier = "merchant.com.example.app"
+// ...elsewhere:
+let request2 = PKPaymentRequest()
+request2.merchantIdentifier = "merchant.com.example.app" // easy to get out of sync
+
+// CORRECT: Centralize configuration
+enum PaymentConfig {
+    static let merchantIdentifier = "merchant.com.example.app"
+    static let countryCode = "US"
+    static let currencyCode = "USD"
+    static let supportedNetworks: [PKPaymentNetwork] = [.visa, .masterCard, .amex]
+}
+```
+
+### DON'T: Forget the total line item
+
+The last item in `paymentSummaryItems` is the total row. If you omit it, the
+payment sheet shows no merchant name or total.
+
+```swift
+// WRONG: No total item
+request.paymentSummaryItems = [
+    PKPaymentSummaryItem(label: "Widget", amount: 9.99)
+]
+
+// CORRECT: Last item is the total with your merchant name
+request.paymentSummaryItems = [
+    PKPaymentSummaryItem(label: "Widget", amount: 9.99),
+    PKPaymentSummaryItem(label: "My Store", amount: 9.99) // Total
+]
+```
+
+### DON'T: Skip the canMakePayments check
+
+```swift
+// WRONG: Show Apple Pay button without checking
+PayWithApplePayButton(.buy) { startPayment() }
+
+// CORRECT: Only show when available
+if PKPaymentAuthorizationController.canMakePayments(
+    usingNetworks: PaymentConfig.supportedNetworks
+) {
+    PayWithApplePayButton(.buy) { startPayment() }
+} else {
+    // Show alternative checkout or setup button
+    Button("Set Up Apple Pay") { /* guide user */ }
+}
+```
+
+### DON'T: Dismiss the controller before completing authorization
+
+```swift
+// WRONG: Dismissing inside didAuthorizePayment
+func paymentAuthorizationController(
+    _ controller: PKPaymentAuthorizationController,
+    didAuthorizePayment payment: PKPayment,
+    handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
+) {
+    controller.dismiss() // Too early -- causes blank sheet
+    completion(.init(status: .success, errors: nil))
+}
+
+// CORRECT: Dismiss only in paymentAuthorizationControllerDidFinish
+func paymentAuthorizationControllerDidFinish(
+    _ controller: PKPaymentAuthorizationController
+) {
+    controller.dismiss()
+}
+```
+
+## Review Checklist
+
+- [ ] Apple Pay capability enabled and merchant ID configured in Developer portal
+- [ ] Payment Processing Certificate generated and installed
+- [ ] `canMakePayments(usingNetworks:)` checked before showing Apple Pay button
+- [ ] Last item in `paymentSummaryItems` is the total with merchant display name
+- [ ] Payment token sent to server for processing (never decoded client-side)
+- [ ] `paymentAuthorizationControllerDidFinish` dismisses the controller
+- [ ] Shipping method changes recalculate totals via delegate callback
+- [ ] StoreKit used for digital goods; Apple Pay used for physical goods
+- [ ] Wallet passes loaded from signed `.pkpass` bundles
+- [ ] `PKPassLibrary.isPassLibraryAvailable()` checked before pass operations
+- [ ] Apple Pay button uses system-provided `PKPaymentButton` or `PayWithApplePayButton`
+- [ ] Error states handled in authorization result (network failures, declined cards)
+
+## References
+
+- Extended patterns (recurring payments, coupon codes, multi-merchant): `references/wallet-passes.md`
+- [PassKit framework](https://sosumi.ai/documentation/passkit)
+- [PKPaymentRequest](https://sosumi.ai/documentation/passkit/pkpaymentrequest)
+- [PKPaymentAuthorizationController](https://sosumi.ai/documentation/passkit/pkpaymentauthorizationcontroller)
+- [PKPaymentButton](https://sosumi.ai/documentation/passkit/pkpaymentbutton)
+- [PKPass](https://sosumi.ai/documentation/passkit/pkpass)
+- [PKAddPassesViewController](https://sosumi.ai/documentation/passkit/pkaddpassesviewcontroller)
+- [PKPassLibrary](https://sosumi.ai/documentation/passkit/pkpasslibrary)
+- [PKPaymentNetwork](https://sosumi.ai/documentation/passkit/pkpaymentnetwork)