oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-mobile/variants/swift-ios/snippets.md

@@ -0,0 +1,1028 @@
+# Mobile Agent - Code Snippets (Swift iOS Native)
+
+Copy-paste ready patterns. Use these as starting points; adapt to the specific task.
+Always use the generated `Client` — never hand-roll `URLRequest`/`JSONDecoder` for API calls.
+
+---
+
+## 1. Package.swift with OpenAPI Build Plugin
+
+```swift
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "MyApp",
+    platforms: [.iOS(.v17)],
+    dependencies: [
+        // Code-generation build plugin (dev / build-time only)
+        .package(
+            url: "https://github.com/apple/swift-openapi-generator",
+            from: "1.3.0"
+        ),
+        // Runtime types used by the generated Client
+        .package(
+            url: "https://github.com/apple/swift-openapi-runtime",
+            from: "1.5.0"
+        ),
+        // URLSession transport
+        .package(
+            url: "https://github.com/apple/swift-openapi-urlsession",
+            from: "1.0.2"
+        ),
+        // Repository-layer response cache (hybrid memory + disk)
+        .package(
+            url: "https://github.com/hyperoslo/Cache",
+            from: "7.4.0"
+        ),
+    ],
+    targets: [
+        .target(
+            name: "MyApp",
+            dependencies: [
+                .product(name: "OpenAPIRuntime",  package: "swift-openapi-runtime"),
+                .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession"),
+                .product(name: "Cache",            package: "Cache"),
+            ],
+            // The generator discovers openapi.yaml + openapi-generator-config.yaml
+            // inside this target's source directory and runs at every `swift build`.
+            plugins: [
+                .plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator"),
+            ]
+        ),
+        .testTarget(
+            name: "MyAppTests",
+            dependencies: ["MyApp"]
+        ),
+    ]
+)
+```
+
+---
+
+## 2. openapi-generator-config.yaml
+
+```yaml
+# Core/Networking/openapi-generator-config.yaml
+# Placed alongside openapi.yaml inside the target source directory.
+generate:
+  - types
+  - client
+accessModifier: public
+```
+
+---
+
+## 3. @Observable View Model
+
+```swift
+// Features/Todos/TodosViewModel.swift
+import Foundation
+import Observation
+
+/// Possible states for the Todos screen.
+enum TodosViewState {
+    case idle
+    case loading
+    case loaded([Components.Schemas.Todo])
+    case empty
+    case error(String)
+}
+
+@MainActor
+@Observable
+final class TodosViewModel {
+    // MARK: - Published state (observed by the View automatically)
+    var viewState: TodosViewState = .idle
+
+    // MARK: - Private
+    // Depend on the protocol seam, not the concrete service — enables protocol-based
+    // mocking in tests without a third-party mock lib (see §8).
+    private let service: any TodoProviding
+    // Retained for cancellation; tests await load() directly (see §8).
+    private(set) var loadTask: Task<Void, Never>?
+
+    init(service: any TodoProviding) {
+        self.service = service
+    }
+
+    // MARK: - Intent
+
+    func load() async {
+        // Cancel any in-flight task before starting a new one.
+        loadTask?.cancel()
+        viewState = .loading
+
+        let task = Task { [weak self] in
+            guard let self else { return }
+            do {
+                // Stale-while-revalidate: the stream yields the cached list first
+                // (instant render), then the revalidated list. State updates per yield.
+                let stream = await self.service.todosStream()
+                for try await todos in stream {
+                    guard !Task.isCancelled else { return }
+                    self.viewState = todos.isEmpty ? .empty : .loaded(todos)
+                }
+            } catch is CancellationError {
+                // Silently ignore — another load will follow.
+            } catch {
+                guard !Task.isCancelled else { return }
+                self.viewState = .error(error.localizedDescription)
+            }
+        }
+        loadTask = task
+        await withTaskCancellationHandler {
+            await task.value
+        } onCancel: {
+            task.cancel()
+        }
+    }
+
+    func retry() async { await load() }
+
+    /// Cancels button/retry loads too; awaited .task forwards caller cancellation.
+    func cancelLoad() { loadTask?.cancel() }
+
+}
+```
+
+The async load waits for its task and forwards caller cancellation to that task.
+The view also cancels button/retry loads in `.onDisappear`. After `guard let self`,
+the task temporarily retains the view model; a weak capture or `deinit` does not
+stop an active request.
+
+---
+
+## 4. SwiftUI Feature View
+
+```swift
+// Features/Todos/TodosView.swift
+import SwiftUI
+
+struct TodosView: View {
+    // @State owns the view model; the View is the allocation site.
+    @State private var viewModel: TodosViewModel
+
+    init(service: any TodoProviding) {
+        _viewModel = State(wrappedValue: TodosViewModel(service: service))
+    }
+
+    var body: some View {
+        // The router owns the enclosing NavigationStack(path:) (see §9); a feature
+        // view assumes it is already inside one and never wraps itself in a stack.
+        content
+            .navigationTitle("Todos")
+            .task { await viewModel.load() }
+            .onDisappear { viewModel.cancelLoad() }
+    }
+
+    // MARK: - Content switch
+
+    @ViewBuilder
+    private var content: some View {
+        switch viewModel.viewState {
+        case .idle, .loading:
+            loadingView
+
+        case .loaded(let todos):
+            todoList(todos)
+
+        case .empty:
+            emptyView
+
+        case .error(let message):
+            errorView(message)
+        }
+    }
+
+    // MARK: - State views
+
+    private var loadingView: some View {
+        ProgressView("Loading…")
+            .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private func todoList(_ todos: [Components.Schemas.Todo]) -> some View {
+        List(todos, id: \.id) { todo in
+            Label(todo.title, systemImage: todo.completed ? "checkmark.circle.fill" : "circle")
+        }
+        .refreshable { await viewModel.load() }
+    }
+
+    private var emptyView: some View {
+        ContentUnavailableView(
+            "No Todos",
+            systemImage: "tray",
+            description: Text("Add your first todo to get started.")
+        )
+    }
+
+    private func errorView(_ message: String) -> some View {
+        VStack(spacing: 16) {
+            Image(systemName: "exclamationmark.triangle")
+                .font(.largeTitle)
+                .foregroundStyle(.red)
+            Text(message)
+                .multilineTextAlignment(.center)
+            Button("Retry") { Task { await viewModel.retry() } }
+                .buttonStyle(.borderedProminent)
+        }
+        .padding()
+    }
+}
+```
+
+---
+
+## 5. Core/Networking API Service (wrapping the generated Client)
+
+```swift
+// Core/Networking/APIClient.swift
+import Foundation
+import OpenAPIRuntime
+import OpenAPIURLSession
+
+/// Configures the generated Client with the server URL and auth middleware.
+/// Inject this as a singleton from App/AppDependencies.swift.
+public final class APIClient {
+    public let client: Client
+
+    public init(serverURL: URL, tokenProvider: @escaping () -> String?) {
+        let transport = URLSessionTransport()
+        let authMiddleware = BearerAuthMiddleware(tokenProvider: tokenProvider)
+        // The generated Client initialiser is non-throwing — no `try` needed.
+        self.client = Client(
+            serverURL: serverURL,
+            transport: transport,
+            middlewares: [authMiddleware]
+        )
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Core/Networking/BearerAuthMiddleware.swift
+// ---------------------------------------------------------------------------
+
+import OpenAPIRuntime
+import HTTPTypes
+
+/// Injects a bearer token into every outgoing request.
+public struct BearerAuthMiddleware: ClientMiddleware {
+    private let tokenProvider: () -> String?
+
+    public init(tokenProvider: @escaping () -> String?) {
+        self.tokenProvider = tokenProvider
+    }
+
+    public func intercept(
+        _ request: HTTPRequest,
+        body: HTTPBody?,
+        baseURL: URL,
+        operationID: String,
+        next: @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?)
+    ) async throws -> (HTTPResponse, HTTPBody?) {
+        var request = request
+        if let token = tokenProvider() {
+            request.headerFields[.authorization] = "Bearer \(token)"
+        }
+        return try await next(request, body, baseURL)
+    }
+}
+```
+
+---
+
+## 6. Generated-Client Call Pattern
+
+> Isolates the raw generated-`Client` call + response mapping — this is the **inner
+> call shape** only. The **production** service is the cached `TodoService` in §10
+> that wraps this shape with a `ResponseCache` (read-through + invalidation). Use the
+> cached form for real features; this type is named `TodoServiceUncached` so it never
+> collides with §10's `TodoService`.
+
+```swift
+// Core/Networking/TodoServiceUncached.swift  (excerpt showing call + response handling)
+import OpenAPIRuntime
+
+public final class TodoServiceUncached {
+    private let client: Client
+
+    public init(client: Client) {
+        self.client = client
+    }
+
+    /// List all todos for the authenticated user.
+    public func listTodos() async throws -> [Components.Schemas.Todo] {
+        // Use the generated operation initialiser — never construct URLRequest by hand.
+        let response = try await client.listTodos(.init())
+
+        switch response {
+        case .ok(let ok):
+            // Decode the typed body; the generator guarantees the shape.
+            return try ok.body.json
+        case .undocumented(let statusCode, _):
+            throw APIError.undocumented(statusCode: statusCode)
+        }
+    }
+
+    public enum APIError: Error {
+        case undocumented(statusCode: Int)
+    }
+}
+```
+
+---
+
+## 7. App Entry Point and Dependency Injection
+
+```swift
+// App/MyApp.swift
+import SwiftUI
+
+@main
+struct MyApp: App {
+    // Composition root: build the dependency graph once at launch.
+    private let dependencies = AppDependencies()
+
+    var body: some Scene {
+        WindowGroup {
+            // Pass the concrete service down; Views never import Core directly.
+            TodosView(service: dependencies.todoService)
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Core/Security/KeychainTokenStore.swift
+// ---------------------------------------------------------------------------
+import Foundation
+import Security
+
+/// Minimal Keychain-backed token store — no third-party dependency.
+/// Secrets (access tokens, refresh tokens) belong in the Keychain, never in
+/// `UserDefaults`, which is an unencrypted plist readable from a device backup.
+struct KeychainTokenStore {
+    let service: String   // e.g. Bundle.main.bundleIdentifier ?? "MyApp"
+
+    /// Read a stored token, or nil if absent.
+    func token(account: String = "accessToken") -> String? {
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+            kSecReturnData as String: true,
+            kSecMatchLimit as String: kSecMatchLimitOne,
+        ]
+        var result: AnyObject?
+        guard SecItemCopyMatching(query as CFDictionary, &result) == errSecSuccess,
+              let data = result as? Data else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+
+    /// Insert or overwrite a token (delete-then-add keeps it idempotent).
+    func setToken(_ value: String, account: String = "accessToken") {
+        let base: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+        ]
+        SecItemDelete(base as CFDictionary)
+        var add = base
+        add[kSecValueData as String] = Data(value.utf8)
+        add[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock
+        SecItemAdd(add as CFDictionary, nil)
+    }
+
+    /// Remove a stored token (e.g. on sign-out).
+    func deleteToken(account: String = "accessToken") {
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+        ]
+        SecItemDelete(query as CFDictionary)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// App/AppDependencies.swift
+// ---------------------------------------------------------------------------
+import Foundation
+import OSLog
+
+/// Builds and owns shared singletons. Constructed once in @main.
+final class AppDependencies {
+    let todoService: TodoService
+    init() {
+        let logger = Logger(
+            subsystem: Bundle.main.bundleIdentifier ?? "MyApp",
+            category: "ResponseCache"
+        )
+        let serverURL = URL(string: ProcessInfo.processInfo.environment["API_BASE_URL"]
+                           ?? "https://api.example.com")!
+        // Secrets come from the Keychain — never UserDefaults (see tech-stack.md).
+        let tokens = KeychainTokenStore(service: Bundle.main.bundleIdentifier ?? "MyApp")
+        let apiClient = APIClient(serverURL: serverURL, tokenProvider: {
+            tokens.token()
+        })
+        // `accountID` is a stable, non-secret server identifier, never a token or email.
+        let accountID = "current-account-id" // Obtain from validated auth/session claims.
+        let todoCache: ResponseCache<[Components.Schemas.Todo]>?
+        do {
+            todoCache = try ResponseCache(name: "todos-\(accountID)")
+        } catch {
+            // Caching is optional. Do not log the account ID, token, or storage path.
+            logger.notice("Response cache unavailable; continuing network-only")
+            todoCache = nil
+        }
+        self.todoService = TodoService(client: apiClient.client, cache: todoCache, accountID: accountID)
+    }
+}
+```
+
+```swift
+// App/AccountServiceController.swift
+// Publish a newly built service only after the old account has been closed.
+@MainActor
+final class AccountServiceController {
+    private(set) var todoService: TodoService?
+    private var transitionGeneration = 0
+
+    func switchAccount(to replacement: TodoService) async {
+        transitionGeneration += 1
+        let generation = transitionGeneration
+        let current = todoService
+        // Remove the old service from the UI before awaiting; another transition may begin.
+        todoService = nil
+        if let current {
+            await current.close() // cancels in-flight reads and purges this account's cache
+        }
+        guard generation == transitionGeneration else {
+            await replacement.close()
+            return
+        }
+        todoService = replacement // replacement has a new client and account-scoped cache
+    }
+
+    func signOut() async {
+        transitionGeneration += 1
+        let current = todoService
+        todoService = nil
+        if let current { await current.close() }
+    }
+}
+```
+
+Build `replacement` with the new account's credentials and non-secret account identifier. Do not
+reuse a service, token provider, or disk namespace across accounts.
+
+---
+
+## 8. XCTest Unit Test for the View Model
+
+```swift
+// Tests/TodosViewModelTests.swift
+import XCTest
+@testable import MyApp
+
+// MARK: - Mock (protocol-based — no subclassing, no third-party mock lib)
+
+final class MockTodoService: TodoProviding, @unchecked Sendable {
+    var stubbedTodos: [Components.Schemas.Todo] = []
+    var shouldThrow: Error?
+
+    func todosStream() async -> AsyncThrowingStream<[Components.Schemas.Todo], Error> {
+        AsyncThrowingStream { continuation in
+            if let error = shouldThrow {
+                continuation.finish(throwing: error)
+            } else {
+                continuation.yield(stubbedTodos)
+                continuation.finish()
+            }
+        }
+    }
+
+    func createTodo(title: String) async throws -> Components.Schemas.Todo {
+        if let shouldThrow { throw shouldThrow }
+        return .init(id: "new", title: title, completed: false)
+    }
+    func toggleTodo(id: String) async throws -> Components.Schemas.Todo {
+        if let shouldThrow { throw shouldThrow }
+        return .init(id: id, title: "", completed: true)
+    }
+    func deleteTodo(id: String) async throws {
+        if let shouldThrow { throw shouldThrow }
+    }
+}
+
+// MARK: - Tests
+
+// The view model is `@MainActor`, so the test methods are too. Instead of polling
+// with `Task.sleep`, await `load()`; assertions run after the load has finished.
+@MainActor
+final class TodosViewModelTests: XCTestCase {
+    // Test that a successful response transitions to .loaded.
+    func testLoad_success_transitionsToLoaded() async {
+        let mock = MockTodoService()
+        mock.stubbedTodos = [
+            .init(id: "1", title: "Buy milk", completed: false),
+        ]
+        let sut = TodosViewModel(service: mock)
+
+        await sut.load()
+
+        guard case .loaded(let todos) = sut.viewState else {
+            return XCTFail("Expected .loaded, got \(sut.viewState)")
+        }
+        XCTAssertEqual(todos.count, 1)
+        XCTAssertEqual(todos[0].title, "Buy milk")
+    }
+
+    // Test that an empty response transitions to .empty.
+    func testLoad_emptyResponse_transitionsToEmpty() async {
+        let mock = MockTodoService()
+        mock.stubbedTodos = []
+        let sut = TodosViewModel(service: mock)
+
+        await sut.load()
+
+        guard case .empty = sut.viewState else {
+            return XCTFail("Expected .empty, got \(sut.viewState)")
+        }
+    }
+
+    // Test that a thrown error transitions to .error.
+    func testLoad_networkError_transitionsToError() async {
+        let mock = MockTodoService()
+        mock.shouldThrow = URLError(.notConnectedToInternet)
+        let sut = TodosViewModel(service: mock)
+
+        await sut.load()
+
+        guard case .error = sut.viewState else {
+            return XCTFail("Expected .error, got \(sut.viewState)")
+        }
+    }
+}
+```
+
+---
+
+## 9. Navigation: interactive swipe-back on nav-bar-hidden routes
+
+**Root cause.** `NavigationStack` is backed by UIKit's `UINavigationController`, and
+the edge swipe-back is its `interactivePopGestureRecognizer`. UIKit ties that
+recognizer to the system back button, so any screen that hides the nav bar
+(`.toolbar(.hidden, for: .navigationBar)` — common with custom headers) loses the
+swipe gesture, and UIKit re-disables it every time such a screen becomes top.
+
+**Standard.** Swipe-back restoration is a navigation-layer concern, so restore it
+once at the **route-registration layer** (`navigationDestination`), not per screen.
+Pushed destinations always have something to pop to; tab roots aren't
+`navigationDestination`s, so they're correctly excluded for free.
+
+```swift
+// Shared/InteractiveSwipeBack.swift
+import SwiftUI
+import UIKit
+
+/// Reaches the enclosing UINavigationController, takes over the pop recognizer's
+/// delegate, and re-enables the edge swipe — scoped to the screen that asks for
+/// it (re-runs on every appear because UIKit re-disables it on nav-bar-hidden
+/// transitions). `canPop`/`onBlocked` guard the pop (e.g. confirm unsaved edits).
+private struct InteractiveSwipeBack: UIViewControllerRepresentable {
+    var canPop: () -> Bool
+    var onBlocked: () -> Void
+
+    func makeUIViewController(context: Context) -> UIViewController {
+        Controller(canPop: canPop, onBlocked: onBlocked)
+    }
+    func updateUIViewController(_ vc: UIViewController, context: Context) {
+        guard let c = vc as? Controller else { return }
+        c.canPop = canPop; c.onBlocked = onBlocked
+    }
+
+    final class Controller: UIViewController, UIGestureRecognizerDelegate {
+        var canPop: () -> Bool
+        var onBlocked: () -> Void
+        init(canPop: @escaping () -> Bool, onBlocked: @escaping () -> Void) {
+            self.canPop = canPop; self.onBlocked = onBlocked
+            super.init(nibName: nil, bundle: nil)
+        }
+        @available(*, unavailable) required init?(coder: NSCoder) { fatalError() }
+
+        override func didMove(toParent parent: UIViewController?) {
+            super.didMove(toParent: parent)
+            reassertSwipeBack()
+        }
+        // UIKit re-disables the recognizer on every nav-bar-hidden transition, so
+        // re-assert on each appear — not just once at insertion (`didMove`).
+        override func viewWillAppear(_ animated: Bool) {
+            super.viewWillAppear(animated)
+            reassertSwipeBack()
+        }
+        override func viewDidAppear(_ animated: Bool) {
+            super.viewDidAppear(animated)
+            reassertSwipeBack()
+        }
+        private func reassertSwipeBack() {
+            guard let r = navigationController?.interactivePopGestureRecognizer else { return }
+            r.delegate = self
+            r.isEnabled = true
+        }
+        func gestureRecognizerShouldBegin(_ g: UIGestureRecognizer) -> Bool {
+            guard (navigationController?.viewControllers.count ?? 0) > 1 else { return false }
+            if canPop() { return true }
+            onBlocked(); return false
+        }
+    }
+}
+
+extension View {
+    /// Restore edge swipe-back on a nav-bar-hidden screen.
+    func enableInteractiveSwipeBack() -> some View {
+        background(InteractiveSwipeBack(canPop: { true }, onBlocked: {}).frame(width: 0, height: 0))
+    }
+    /// Guarded variant: swallow the swipe and run `onBlocked` when `canPop` is false.
+    func interactiveSwipeBack(
+        canPop: @escaping () -> Bool,
+        onBlocked: @escaping () -> Void
+    ) -> some View {
+        background(InteractiveSwipeBack(canPop: canPop, onBlocked: onBlocked).frame(width: 0, height: 0))
+    }
+
+    /// PREFERRED registration: every pushed route gets swipe-back automatically.
+    /// Use this instead of bare `navigationDestination(for:)` for push routes.
+    func swipeBackDestination<D: Hashable, C: View>(
+        for type: D.Type,
+        @ViewBuilder destination: @escaping (D) -> C
+    ) -> some View {
+        navigationDestination(for: type) { value in
+            destination(value).enableInteractiveSwipeBack()
+        }
+    }
+}
+```
+
+```swift
+// Usage — register routes through the wrapper, not bare navigationDestination:
+NavigationStack(path: $router.path) {
+    RootView()
+        .swipeBackDestination(for: ProgramID.self) { ProgramDetailView(id: $0) }
+        .swipeBackDestination(for: SettingsRoute.self) { _ in SettingsView() }
+}
+
+// Only screens with a custom pop policy override explicitly:
+NewPostView()
+    .interactiveSwipeBack(canPop: { viewModel.isSaved }, onBlocked: { showDiscardConfirm = true })
+```
+
+> Anti-pattern: sprinkling `.enableInteractiveSwipeBack()` on each `View` body. It
+> compiles even when forgotten, so nav-bar-hidden routes silently lose the gesture.
+> Enforce at the route layer; optionally add a SwiftLint rule that flags
+> `.toolbar(.hidden, for: .navigationBar)` without a swipe-back modifier.
+
+---
+
+## 10. Repository-layer response cache (hyperoslo/Cache)
+
+When response caching is required, implement it at the Repository (Service) layer. Cache the
+**decoded** `Components.Schemas.*` models returned by the generated `Client` — never
+intercept `HTTPBody` in a middleware (it is a single-consumption stream). `hyperoslo/Cache`'s
+`Storage` is not `Sendable`, so it is always owned by an `actor`.
+
+```swift
+// Core/Cache/ResponseCache.swift
+import Foundation
+import Cache
+
+/// Actor wrapper over hyperoslo/Cache. One instance per cached value type and account namespace.
+/// Owns a non-Sendable `Storage`, so all access is actor-isolated → Swift 6 clean.
+actor ResponseCache<Value: Codable & Sendable> {
+    private let storage: Storage<String, Value>
+
+    /// - Parameters:
+    ///   - name: disk namespace. Include a stable, non-secret account/tenant identifier.
+    ///   - memoryExpiry: in-memory TTL — fast path, lost on app relaunch.
+    ///   - diskExpiry: on-disk TTL — survives relaunch. Never use `.never`.
+    init(
+        name: String,
+        memoryExpiry: Expiry = .seconds(120),
+        diskExpiry: Expiry = .seconds(60 * 60)
+    ) throws {
+        // `fileManager:` is REQUIRED on the 7.4.0 release tag (last release, 2024-08).
+        // The README shows the master signature where it defaults to `.default`, but
+        // that default is unreleased — pass it explicitly and pin the exact version.
+        self.storage = try Storage<String, Value>(
+            diskConfig: DiskConfig(name: name, expiry: diskExpiry),
+            memoryConfig: MemoryConfig(expiry: memoryExpiry, countLimit: 200, totalCostLimit: 0),
+            fileManager: .default,
+            transformer: TransformerFactory.forCodable(ofType: Value.self)
+        )
+    }
+
+    /// Non-expired cached value, or nil on miss/expiry. Read errors degrade to nil.
+    func value(forKey key: String) -> Value? {
+        try? storage.object(forKey: key)
+    }
+
+    func store(_ value: Value, forKey key: String) {
+        try? storage.setObject(value, forKey: key)
+    }
+
+    /// Drop affected keys after a write so the next read repopulates.
+    func invalidate(_ key: String) { try? storage.removeObject(forKey: key) }
+    func invalidateAll() { try? storage.removeAll() }
+}
+```
+
+```swift
+// Core/Networking/TodoProviding.swift
+import Foundation
+
+/// Protocol seam the view models depend on. Keeps the cached `TodoService`
+/// swappable for a protocol-based mock in tests (no third-party mock lib).
+public protocol TodoProviding: Sendable {
+    func todosStream() async -> AsyncThrowingStream<[Components.Schemas.Todo], Error>
+    func createTodo(title: String) async throws -> Components.Schemas.Todo
+    func toggleTodo(id: String) async throws -> Components.Schemas.Todo
+    func deleteTodo(id: String) async throws
+}
+```
+
+```swift
+// Core/Networking/TodoService.swift  (cached repository)
+import Foundation
+
+public actor TodoService: TodoProviding {
+    private let client: Client
+    private let cache: ResponseCache<[Components.Schemas.Todo]>?
+    private let accountID: String
+    private var isActive = true
+    private var requests: [UUID: Task<Void, Never>] = [:]
+
+    public init(
+        client: Client,
+        cache: ResponseCache<[Components.Schemas.Todo]>?,
+        accountID: String
+    ) {
+        self.client = client
+        self.cache = cache
+        self.accountID = accountID
+    }
+
+    private var listKey: String { "\(accountID):listTodos" }
+
+    /// Call before replacing an account or signing out. Cancels reads, clears
+    /// account-scoped cache data, and prevents a late response from reaching the old UI.
+    public func close() async {
+        isActive = false
+        let pendingRequests = Array(requests.values)
+        let pendingContinuations = Array(continuations.values)
+        requests.removeAll()
+        continuations.removeAll()
+        pendingContinuations.forEach { $0.finish() }
+        pendingRequests.forEach { $0.cancel() }
+        // Wait for cancelled work before purging. A request that was suspended in a cache
+        // write cannot repopulate this account's namespace after the purge.
+        for task in pendingRequests { await task.value }
+        await cache?.invalidateAll()
+    }
+
+    // MARK: - Read (stale-while-revalidate)
+
+    /// Yields the cached list first (if any), then the freshly-fetched list.
+    /// The View model iterates with `for try await` and updates state on each yield.
+    /// If the network fails but a cached value exists, the stale value stands and
+    /// the error is swallowed; with no cache, the error surfaces.
+    public func todosStream() async -> AsyncThrowingStream<[Components.Schemas.Todo], Error> {
+        let requestID = UUID()
+        var continuation: AsyncThrowingStream<[Components.Schemas.Todo], Error>.Continuation!
+        let stream = AsyncThrowingStream<[Components.Schemas.Todo], Error> { continuation = $0 }
+
+        guard isActive else {
+            continuation.finish()
+            return stream
+        }
+
+        // Registration happens while this actor is isolated. `close()` therefore sees both
+        // the request and its continuation before it can cancel or purge the account cache.
+        continuations[requestID] = continuation
+        let task = Task { [weak self] in
+            guard let self else { return }
+            await self.runRequest(requestID)
+        }
+        requests[requestID] = task
+        continuation.onTermination = { [weak self] _ in
+            Task { await self?.cancelRequest(requestID) }
+        }
+        return stream
+    }
+
+    private var continuations: [UUID: AsyncThrowingStream<[Components.Schemas.Todo], Error>.Continuation] = [:]
+
+    private func runRequest(_ requestID: UUID) async {
+        guard let continuation = continuations[requestID] else { return }
+        defer { finishRequest(requestID) }
+
+        let cached = await cache?.value(forKey: listKey)
+        guard isActive, !Task.isCancelled else { return }
+        if let cached { continuation.yield(cached) }
+
+        do {
+            let fresh = try await fetchTodos()
+            guard isActive, !Task.isCancelled else { return }
+            if let cache { await cache.store(fresh, forKey: listKey) }
+            // `close()` may have run while the cache actor was awaited.
+            guard isActive, !Task.isCancelled else { return }
+            continuation.yield(fresh)
+        } catch {
+            guard isActive, !Task.isCancelled else { return }
+            if cached == nil { continuation.finish(throwing: error) }
+        }
+    }
+
+    private func finishRequest(_ id: UUID) {
+        continuations[id]?.finish()
+        continuations[id] = nil
+        requests[id] = nil
+    }
+
+    private func cancelRequest(_ id: UUID) {
+        continuations[id]?.finish()
+        continuations[id] = nil
+        requests[id]?.cancel()
+        // Keep the task registered until `finishRequest`. A later account close must await
+        // an already-cancelled task before it purges the disk namespace.
+    }
+
+    private func fetchTodos() async throws -> [Components.Schemas.Todo] {
+        let response = try await client.listTodos(.init())
+        switch response {
+        case .ok(let ok):
+            return try ok.body.json
+        case .undocumented(let statusCode, _):
+            throw TodoServiceError.undocumented(statusCode: statusCode)
+        }
+    }
+
+    // MARK: - Write (invalidate after success)
+
+    public func createTodo(title: String) async throws -> Components.Schemas.Todo {
+        let body = Components.Schemas.CreateTodoRequest(title: title)
+        let response = try await client.createTodo(.init(body: .json(body)))
+        switch response {
+        case .created(let created):
+            await cache?.invalidate(listKey)   // next read repopulates
+            return try created.body.json
+        case .conflict:
+            throw TodoServiceError.conflict
+        case .undocumented(let statusCode, _):
+            throw TodoServiceError.undocumented(statusCode: statusCode)
+        }
+    }
+}
+```
+
+The view model consumes the stream with `for try await` — see §3 `TodosViewModel.load()`
+for the cancellation-safe consumer.
+
+Wire the cache into the service at the composition root — see §7 `AppDependencies`.
+Use an optional cache: if `Storage` initialization fails, continue network-only and record a
+non-sensitive diagnostic. Namespace and key by a stable non-secret account/tenant identifier.
+On account switch or logout, cancel the old service's consumers and call `await oldService.close()`
+before publishing the next account's service. Rebuild the API client with the new credentials.
+
+> Rules recap: cache **decoded models** at the Repository layer (not `HTTPBody`);
+> key on account/tenant + `operationID` + params; explicit memory/disk TTLs (never `.never`);
+> invalidate affected keys after every write and purge/cancel on account switch or logout. Durable user-owned data → SwiftData;
+> secrets → Keychain. `hyperoslo/Cache` is never a system of record.
+
+---
+
+## 11. Durable storage: SwiftData (system of record)
+
+`hyperoslo/Cache` (§10) memoizes transient server-owned responses. **Durable,
+user-owned** data (drafts, offline records) lives in **SwiftData** — the Swift-native
+ORM on Core Data. Model with `@Model`, own one `ModelContainer`, and read/write
+through a repository so features never touch a `ModelContext` directly.
+
+```swift
+// Core/Models/Draft.swift
+import SwiftData
+
+/// A user-owned draft persisted across launches. `@Model` makes the class a
+/// SwiftData entity (schema inferred from stored properties).
+@Model
+final class Draft {
+    @Attribute(.unique) var id: UUID
+    var title: String
+    var body: String
+    var updatedAt: Date
+
+    init(id: UUID = UUID(), title: String, body: String, updatedAt: Date = .now) {
+        self.id = id
+        self.title = title
+        self.body = body
+        self.updatedAt = updatedAt
+    }
+}
+```
+
+```swift
+// Core/Services/DraftRepository.swift
+import Foundation
+import SwiftData
+
+/// Repository over SwiftData. Owns a `ModelContext` bound to the app's container;
+/// `@MainActor` because the default context is main-actor bound.
+@MainActor
+final class DraftRepository {
+    private let context: ModelContext
+
+    init(container: ModelContainer) {
+        self.context = container.mainContext
+    }
+
+    /// Fetch newest-first, optionally filtered by a title substring.
+    func drafts(matching query: String = "") throws -> [Draft] {
+        let predicate = query.isEmpty ? nil : #Predicate<Draft> {
+            $0.title.localizedStandardContains(query)
+        }
+        let descriptor = FetchDescriptor<Draft>(
+            predicate: predicate,
+            sortBy: [SortDescriptor(\.updatedAt, order: .reverse)]
+        )
+        return try context.fetch(descriptor)
+    }
+
+    func upsert(_ draft: Draft) throws {
+        context.insert(draft)          // insert is idempotent on the unique id
+        try context.save()
+    }
+
+    func delete(_ draft: Draft) throws {
+        context.delete(draft)
+        try context.save()
+    }
+}
+```
+
+```swift
+// App/MyApp.swift — build one ModelContainer for the whole app.
+import SwiftUI
+import SwiftData
+
+@main
+struct MyApp: App {
+    // One container per app; SwiftUI injects it into the environment.
+    let container: ModelContainer = {
+        do { return try ModelContainer(for: Draft.self) }
+        catch { fatalError("Failed to create ModelContainer: \(error)") }
+    }()
+
+    var body: some Scene {
+        WindowGroup { RootView() }
+            .modelContainer(container)
+    }
+}
+```
+
+---
+
+## 12. UI testing: XCUITest
+
+Unit tests (§8) cover view models against protocol mocks. **XCUITest** drives the
+real app through the accessibility layer for critical user flows — launch, interact,
+assert on-screen. Give interactive views stable `.accessibilityIdentifier`s so the
+queries don't depend on visible copy.
+
+```swift
+// UITests/TodosFlowUITests.swift
+import XCTest
+
+final class TodosFlowUITests: XCTestCase {
+    override func setUp() {
+        super.setUp()
+        continueAfterFailure = false     // stop at the first failed assertion
+    }
+
+    func testTodosScreen_loadsAndShowsList() {
+        let app = XCUIApplication()
+        // Pass a launch argument the app reads to serve deterministic fixtures.
+        app.launchArguments += ["-uiTestMode"]
+        app.launch()
+
+        // Wait for the navigation title to appear (async load).
+        let title = app.navigationBars["Todos"]
+        XCTAssertTrue(title.waitForExistence(timeout: 5))
+
+        // Tap the first row and assert navigation happened.
+        let firstCell = app.cells.element(boundBy: 0)
+        XCTAssertTrue(firstCell.waitForExistence(timeout: 5))
+        firstCell.tap()
+
+        XCTAssertTrue(app.staticTexts["todoDetailTitle"].waitForExistence(timeout: 5))
+    }
+}
+```