crossmate

CrossmateApp.swift (52143B)

---

 import CloudKit
 import SwiftUI
 import UserNotifications
 
 @main
 struct CrossmateApp: App {
     @UIApplicationDelegateAdaptor private var appDelegate: AppDelegate
 
     @State private var services: AppServices
 
     init() {
         self._services = State(initialValue: AppServices())
     }
 
     var body: some Scene {
         WindowGroup {
             if ProcessInfo.processInfo.arguments.contains("--crossmate-marketing-screenshot") {
                 MarketingPuzzleScreenshotView(services: services)
                     .environment(services.preferences)
                     .environment(services.inputMonitor)
                     .environment(services.announcements)
                     .environment(\.engagementStatus, services.engagementStatus)
             } else {
                 RootView(
                     services: services,
                     appDelegate: appDelegate
                 )
                 .environment(\.managedObjectContext, services.persistence.viewContext)
                 .environment(services.driveMonitor)
                 .environment(services.inputMonitor)
                 .environment(services.announcements)
                 .environment(services.tips)
                 .environment(services.syncMonitor)
                 .environment(services.eventLog)
                 .environment(\.syncEngine, services.syncEngine)
                 .environment(\.engagementStatus, services.engagementStatus)
                 .environment(services.nytAuth)
                 .environment(\.nytPuzzleFetcher, services.nytFetcher)
                 .environment(\.resetDatabase, {
                     do {
                         try await services.cloudService.resetAllData()
                     } catch {
                         services.announcements.post(Announcement(
                             id: "reset-database-error",
                             scope: .global,
                             severity: .error,
                             title: "Resetting Failed",
                             body: error.localizedDescription,
                             dismissal: .manual
                         ))
                     }
                 })
                 .environment(\.inviteFriend, { gameID, friendAuthorID in
                     try await services.invites.inviteFriend(gameID: gameID, friendAuthorID: friendAuthorID)
                 })
                 .environment(\.acceptInvite, { shareURL, pingRecordName in
                     _ = try await services.invites.acceptInvite(
                         shareURL: shareURL,
                         pingRecordName: pingRecordName
                     )
                 })
                 .environment(\.declineInvite, { gameID in
                     try await services.invites.declineInvite(gameID: gameID)
                 })
                 .environment(\.blockFriend, { friendAuthorID in
                     await services.invites.blockFriend(authorID: friendAuthorID)
                 })
                 .environment(\.renameFriend, { friendAuthorID, nickname in
                     do {
                         try await services.friendController.setNickname(
                             friendAuthorID: friendAuthorID,
                             nickname: nickname
                         )
                     } catch {
                         services.announcements.post(Announcement(
                             id: "rename-friend-error-\(friendAuthorID)",
                             scope: .global,
                             severity: .error,
                             title: "Renaming Failed",
                             body: error.localizedDescription,
                             dismissal: .manual
                         ))
                     }
                 })
                 .environment(\.sendResignPings, { gameID in
                     await services.sessions.sendCompletionPings(gameID: gameID, resigned: true)
                 })
             }
         }
         .commands {
             PuzzleCommands()
         }
     }
 }
 
 // MARK: - App Delegate
 
 final class AppDelegate: UIResponder, UIApplicationDelegate, @preconcurrency UNUserNotificationCenterDelegate, @unchecked Sendable {
     /// Trims the iPad/Mac menu bar — and the hold-⌘ discoverability overlay it
     /// drives — to the menus Crossmate actually uses. The app has no File or
     /// View surface, so both standard menus are removed; Edit stays (system
     /// undo/copy/paste), and the puzzle's Entry/Hints menus come from
     /// `PuzzleCommands`. Only touch the main system menu, never contextual ones.
     override func buildMenu(with builder: UIMenuBuilder) {
         super.buildMenu(with: builder)
         guard builder.system == .main else { return }
         builder.remove(menu: .file)
         builder.remove(menu: .view)
     }
 
     var onRemoteNotification: ((
         String,
         CKDatabase.Scope?,
         PushPayload.Event?,
         UUID?,
         String?,
         String?,
         Date?,
         Bool
     ) async -> Void)?
     /// Reports the outcome of `registerForRemoteNotifications`. Surfaced in
     /// the diagnostics log so a missing APNs token (e.g. an aps-environment
     /// mismatch between the entitlements and the TestFlight distribution
     /// channel) is visible rather than silently degrading sync to the
     /// CKSyncEngine poll cadence.
     var onAPNsRegistrationResult: ((String) -> Void)?
     /// Delivers the raw APNs token to `PushClient` so it can register with the
     /// Crossmate push worker. Fires on every successful APNs registration —
     /// the worker dedupes unchanged triples server-side.
     var onAPNsToken: ((Data) -> Void)?
     /// Tells the app that visible notification receipts may be waiting in the
     /// App Group ring buffer written by the Notification Service Extension.
     var onVisibleNotificationReceiptsAvailable: (() -> Void)?
 
     func application(
         _ application: UIApplication,
         didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
     ) -> Bool {
         application.registerForRemoteNotifications()
         UNUserNotificationCenter.current().delegate = self
         return true
     }
 
     func application(
         _ application: UIApplication,
         didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
     ) {
         let hex = deviceToken.map { String(format: "%02x", $0) }.joined()
         let prefix = hex.prefix(12)
         onAPNsRegistrationResult?("APNs registered token=\(prefix)… (\(deviceToken.count) bytes)")
         onAPNsToken?(deviceToken)
     }
 
     func application(
         _ application: UIApplication,
         didFailToRegisterForRemoteNotificationsWithError error: Error
     ) {
         let nsError = error as NSError
         onAPNsRegistrationResult?(
             "APNs registration FAILED — domain=\(nsError.domain) code=\(nsError.code) " +
             "\(nsError.localizedDescription)"
         )
     }
 
     /// Foreground notification arrival. If the user is currently viewing the
     /// puzzle the ping refers to, hide it entirely (`[]`); otherwise show it
     /// as a banner with sound.
     func userNotificationCenter(
         _ center: UNUserNotificationCenter,
         willPresent notification: UNNotification,
         withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
     ) {
         let userInfo = notification.request.content.userInfo
         guard let gameID = Self.gameID(from: userInfo) else {
             logForegroundVisibleNotification(notification, source: "foreground")
             completionHandler([.banner, .list, .sound])
             return
         }
         // An invite banner is redundant on the Game List: the invite already
         // shows in the "Invited" section there. Suppress it while no puzzle is
         // active (the user is on the list), but still present it when the user
         // is inside a different puzzle and wouldn't see that row.
         let isInvite = (userInfo["pingKind"] as? String) == PingKind.invite.rawValue
         if isInvite, NotificationState.activePuzzleID() == nil {
             completionHandler([])
             return
         }
         if NotificationState.isSuppressed(gameID: gameID) {
             completionHandler([])
         } else {
             logForegroundVisibleNotification(notification, source: "foreground")
             completionHandler([.banner, .list, .sound])
         }
     }
 
     func userNotificationCenter(
         _ center: UNUserNotificationCenter,
         didReceive response: UNNotificationResponse,
         withCompletionHandler completionHandler: @escaping () -> Void
     ) {
         let userInfo = response.notification.request.content.userInfo
         guard let gameID = Self.gameID(from: userInfo) else {
             completionHandler()
             return
         }
 
         let fromInvitePing =
             (userInfo["pingKind"] as? String) == PingKind.invite.rawValue
 
         Task { @MainActor in
             NotificationNavigationBroker.shared.openGame(
                 gameID,
                 fromInvitePing: fromInvitePing
             )
             completionHandler()
         }
     }
 
     private static func gameID(from userInfo: [AnyHashable: Any]) -> UUID? {
         if let id = userInfo["gameID"] as? String,
            let uuid = UUID(uuidString: id) {
             return uuid
         }
         guard let ck = userInfo["ck"] as? [AnyHashable: Any],
               let qry = ck["qry"] as? [AnyHashable: Any],
               let zoneName = qry["zid"] as? String,
               zoneName.hasPrefix("game-")
         else { return nil }
         return UUID(uuidString: String(zoneName.dropFirst("game-".count)))
     }
 
     private func logForegroundVisibleNotification(
         _ notification: UNNotification,
         source: String
     ) {
         if (notification.request.content.userInfo["crossmateNSELogged"] as? Bool) != true {
             VisibleNotificationReceiptLog.record(
                 body: notification.request.content.body,
                 source: source
             )
         }
         onVisibleNotificationReceiptsAvailable?()
     }
 
     /// Asks the user for notification permission only if they haven't yet
     /// answered the prompt. Idempotent — once the user has decided either
     /// way, this is a no-op.
     static func requestNotificationAuthorizationIfNeeded() async {
         let center = UNUserNotificationCenter.current()
         let settings = await center.notificationSettings()
         guard settings.authorizationStatus == .notDetermined else { return }
         _ = try? await center.requestAuthorization(options: [.alert, .sound, .badge])
     }
 
     func application(
         _ application: UIApplication,
         didReceiveRemoteNotification userInfo: [AnyHashable: Any]
     ) async -> UIBackgroundFetchResult {
         let summary = AppServices.describePush(userInfo: userInfo)
         let scope = AppServices.databaseScope(fromPush: userInfo)
         let payload = PushPayload.decode(from: userInfo["payload"] as? String)
         let gameID = Self.gameID(from: userInfo)
         let kind = userInfo["kind"] as? String
         let senderDeviceID = userInfo["senderDeviceID"] as? String
         let readAt = Self.date(from: userInfo["readAt"] as? String)
         let isBackground = application.applicationState != .active
         await onRemoteNotification?(
             summary,
             scope,
             payload?.event,
             gameID,
             kind,
             senderDeviceID,
             readAt,
             isBackground
         )
         return .newData
     }
 
     private static func date(from raw: String?) -> Date? {
         guard let raw else { return nil }
         let formatter = ISO8601DateFormatter()
         formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
         if let date = formatter.date(from: raw) { return date }
         formatter.formatOptions = [.withInternetDateTime]
         return formatter.date(from: raw)
     }
 
     func application(
         _ application: UIApplication,
         configurationForConnecting connectingSceneSession: UISceneSession,
         options: UIScene.ConnectionOptions
     ) -> UISceneConfiguration {
         let configuration = UISceneConfiguration(
             name: nil,
             sessionRole: connectingSceneSession.role
         )
         configuration.delegateClass = SceneDelegate.self
         return configuration
     }
 }
 
 @MainActor
 final class NotificationNavigationBroker {
     static let shared = NotificationNavigationBroker()
 
     var onOpenGame: ((UUID) -> Void)? {
         didSet { flushPendingGameIDs() }
     }
 
     private var pendingGameIDs: [UUID] = []
     /// Game IDs whose navigation was triggered by tapping an `.invite` ping
     /// notification. The CKShare that materialises such a game is accepted on
     /// a separate path and can land seconds after the tap, so the destination
     /// view consumes this flag to know it should wait rather than hard-error
     /// when the game isn't in the local store yet.
     private var inviteOriginGameIDs: Set<UUID> = []
 
     private init() {}
 
     func openGame(_ gameID: UUID, fromInvitePing: Bool = false) {
         if fromInvitePing { inviteOriginGameIDs.insert(gameID) }
         guard let onOpenGame else {
             pendingGameIDs.append(gameID)
             return
         }
         onOpenGame(gameID)
     }
 
     /// Returns `true` exactly once if `gameID` was opened by tapping an
     /// `.invite` ping notification, clearing the flag so a later re-open of
     /// the same game (e.g. from the library list) behaves normally.
     func consumeInviteOrigin(_ gameID: UUID) -> Bool {
         inviteOriginGameIDs.remove(gameID) != nil
     }
 
     private func flushPendingGameIDs() {
         guard let onOpenGame, !pendingGameIDs.isEmpty else { return }
         let gameIDs = pendingGameIDs
         pendingGameIDs.removeAll()
         for gameID in gameIDs {
             onOpenGame(gameID)
         }
     }
 }
 
 @MainActor
 final class CloudShareAcceptanceBroker {
     static let shared = CloudShareAcceptanceBroker()
 
     var onAcceptShare: ((CKShare.Metadata) async -> Void)? {
         didSet { flushPendingAcceptedShares() }
     }
 
     private var pendingAcceptedShares: [CKShare.Metadata] = []
 
     private init() {}
 
     func acceptCloudKitShare(_ metadata: CKShare.Metadata) {
         guard let onAcceptShare else {
             pendingAcceptedShares.append(metadata)
             return
         }
         Task { await onAcceptShare(metadata) }
     }
 
     private func flushPendingAcceptedShares() {
         guard let onAcceptShare, !pendingAcceptedShares.isEmpty else { return }
         let metadatas = pendingAcceptedShares
         pendingAcceptedShares.removeAll()
         for metadata in metadatas {
             Task { await onAcceptShare(metadata) }
         }
     }
 }
 
 /// Bridges a tapped Crossmate universal link from the `SceneDelegate` to
 /// `RootView`. A custom scene delegate is installed for the OS CKShare-accept
 /// callback, and once that exists, `NSUserActivityTypeBrowsingWeb` activities
 /// are delivered to *it* rather than SwiftUI's `.onContinueUserActivity` — so
 /// they must be forwarded explicitly. Buffers links that arrive before
 /// `RootView` wires up its handler (a cold launch delivers the activity in
 /// `scene(_:willConnectTo:)`, before the root `.task` runs), mirroring
 /// `CloudShareAcceptanceBroker`.
 @MainActor
 final class ShareLinkBroker {
     static let shared = ShareLinkBroker()
 
     var onOpenShareLink: ((URL) -> Void)? {
         didSet { flushPendingLinks() }
     }
 
     private var pendingURLs: [URL] = []
 
     private init() {}
 
     func openShareLink(_ url: URL) {
         guard let onOpenShareLink else {
             pendingURLs.append(url)
             return
         }
         onOpenShareLink(url)
     }
 
     private func flushPendingLinks() {
         guard let onOpenShareLink, !pendingURLs.isEmpty else { return }
         let urls = pendingURLs
         pendingURLs.removeAll()
         for url in urls { onOpenShareLink(url) }
     }
 }
 
 final class SceneDelegate: NSObject, UIWindowSceneDelegate {
     func scene(
         _ scene: UIScene,
         willConnectTo session: UISceneSession,
         options connectionOptions: UIScene.ConnectionOptions
     ) {
         // SwiftUI owns the window in this lifecycle — only read the launch
         // options here, never create a window. A universal link (or a CKShare)
         // that cold-launches the app arrives via `connectionOptions`, not
         // through the `continue` / `userDidAcceptCloudKitShareWith` callbacks.
         for activity in connectionOptions.userActivities {
             handle(userActivity: activity)
         }
         if let metadata = connectionOptions.cloudKitShareMetadata {
             CloudShareAcceptanceBroker.shared.acceptCloudKitShare(metadata)
         }
     }
 
     func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
         handle(userActivity: userActivity)
     }
 
     func windowScene(
         _ windowScene: UIWindowScene,
         userDidAcceptCloudKitShareWith metadata: CKShare.Metadata
     ) {
         CloudShareAcceptanceBroker.shared.acceptCloudKitShare(metadata)
     }
 
     /// Forwards a tapped Crossmate universal link to `RootView` via
     /// `ShareLinkBroker`. Non-web activities (and web activities without a URL)
     /// are ignored.
     private func handle(userActivity: NSUserActivity) {
         guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
               let url = userActivity.webpageURL else { return }
         ShareLinkBroker.shared.openShareLink(url)
     }
 }
 
 // MARK: - Root View
 
 /// Drives the join placeholder overlay while a tapped share link is being
 /// accepted; `shape` is the silhouette decoded from the link, if any.
 struct PendingJoinPlaceholder: Identifiable {
     let id = UUID()
     let shape: GridSilhouette.Grid?
 }
 
 struct RootView: View {
     let services: AppServices
     let appDelegate: AppDelegate
 
     @Environment(\.scenePhase) private var scenePhase
     @State private var navigationPath = NavigationPath()
     @State private var pendingJoin: PendingJoinPlaceholder?
     /// The in-flight share-accept driven by a tapped link, retained so the
     /// joining screen's Cancel can stop it (its poll unwinds on cancellation).
     @State private var joinTask: Task<Void, Error>?
 
     var body: some View {
         NavigationStack(path: $navigationPath) {
             GameListView(
                 store: services.store,
                 shareController: services.shareController,
                 authorIdentity: services.identity,
                 onRefresh: { await services.refreshLibrary() },
                 onAppear: { await services.gameListAppeared() },
                 onDisappear: { services.gameListDisappeared() },
                 onAcceptInvite: { shareURL, pingRecordName, shape in
                     try await acceptInviteFromGameList(
                         shareURL: shareURL,
                         pingRecordName: pingRecordName,
                         shape: shape
                     )
                 },
                 navigationPath: $navigationPath
             )
             .navigationDestination(for: UUID.self) { gameID in
                 PuzzleDisplayView(
                     gameID: gameID,
                     store: services.store,
                     shareController: services.shareController,
                     services: services
                 )
                 .id(gameID)
             }
         }
         .environment(services.preferences)
         .overlay {
             if let join = pendingJoin {
                 JoiningPuzzleView(shape: join.shape, onCancel: {
                     joinTask?.cancel()
                     withAnimation { pendingJoin = nil }
                 })
                 .transition(.opacity)
                 .zIndex(1)
             }
         }
         .task {
             NotificationState.setActivePuzzleID(nil)
             NotificationNavigationBroker.shared.onOpenGame = { gameID in
                 UIApplication.shared.dismissPresentedViewControllers()
                 navigationPath = NavigationPath()
                 navigationPath.append(gameID)
             }
             // A tapped Crossmate share link (universal link), routed here by the
             // `SceneDelegate` through `ShareLinkBroker` — `.onContinueUserActivity`
             // never fires once a custom scene delegate is installed. Show the
             // placeholder immediately off the silhouette in the URL, then accept
             // the share (the iCloud token is reconstructed locally, so there's no
             // Safari → iCloud bounce). `.cloudShareAcceptanceCompleted` clears the
             // placeholder and navigates to the joined game.
             ShareLinkBroker.shared.onOpenShareLink = { url in
                 guard let route = ShareLinkRoute(shortLink: url) else { return }
                 withAnimation { pendingJoin = PendingJoinPlaceholder(shape: route.shape) }
                 joinTask = Task<Void, Error> {
                     do {
                         let outcome = try await services.cloudService.acceptShare(url: route.iCloudShareURL)
                         // The share was accepted but its puzzle hasn't synced in
                         // yet — the joining screen timed out. The game still
                         // arrives in the list shortly, so reassure rather than
                         // leave the user wondering why nothing opened.
                         if case .pendingSync = outcome {
                             services.announcements.post(.puzzleStillSyncing())
                         }
                     } catch {
                         // A Cancel tap returns without throwing, so reaching
                         // here is a genuine failure to join. The common one is a
                         // dead link — the inviter deleted or left the game, so
                         // its share is gone, which the metadata fetch reports as
                         // `.unknownItem`/`.zoneNotFound`. Surface it on the Game
                         // List rather than bouncing the user back in silence.
                         guard !Task.isCancelled else { return }
                         withAnimation { pendingJoin = nil }
                         let code = (error as? CKError)?.code
                         let gone = code == .unknownItem || code == .zoneNotFound
                         services.eventLog.note(
                             "share link join failed: \(error.localizedDescription)",
                             level: gone ? "info" : "error"
                         )
                         services.announcements.post(Announcement(
                             id: "share-link-join-failed",
                             scope: .global,
                             severity: gone ? .warning : .error,
                             title: gone ? "Puzzle Removed" : "Accepting Failed",
                             body: gone
                                 ? "This puzzle was removed."
                                 : error.localizedDescription,
                             dismissal: .manual
                         ))
                     }
                 }
             }
             await services.start(appDelegate: appDelegate)
         }
         .onOpenURL { url in
             if let id = services.importService.importGame(from: url) {
                 navigationPath.append(id)
             }
         }
         .onReceive(NotificationCenter.default.publisher(for: .cloudShareAcceptanceStarted)) { _ in
             UIApplication.shared.dismissPresentedViewControllers()
         }
         .onReceive(NotificationCenter.default.publisher(for: .cloudShareAcceptanceCompleted)) { notification in
             withAnimation { pendingJoin = nil }
             guard let gameID = notification.userInfo?["gameID"] as? UUID else { return }
             // A join driven from inside the puzzle view (an `.invite`
             // notification tap) is already showing this game — appending
             // again would stack a duplicate screen. Navigate only when the
             // accept came from elsewhere, e.g. the Invited list.
             guard NotificationState.activePuzzleID() != gameID else { return }
             navigationPath.append(gameID)
         }
         .onChange(of: scenePhase) { _, newPhase in
             switch newPhase {
             case .active:
                 services.noteAppForeground(true)
                 Task { await services.syncOnForeground() }
             case .background, .inactive:
                 services.noteAppForeground(false)
                 NotificationState.setActivePuzzleID(nil)
                 // Synchronous: takes a background-execution assertion before the
                 // flush Task suspends, so buffered edits persist + enqueue even
                 // if the scene is suspended immediately.
                 services.syncOnBackground()
             @unknown default:
                 break
             }
         }
     }
 
     private func acceptInviteFromGameList(
         shareURL: String,
         pingRecordName: String,
         shape: GridSilhouette.Grid?
     ) async throws {
         joinTask?.cancel()
         withAnimation { pendingJoin = PendingJoinPlaceholder(shape: shape) }
         let task = Task<Void, Error> {
             let outcome = try await services.invites.acceptInvite(
                 shareURL: shareURL,
                 pingRecordName: pingRecordName
             )
             guard !Task.isCancelled else { return }
             if case .pendingSync = outcome {
                 services.announcements.post(.puzzleStillSyncing())
             }
         }
         joinTask = task
         do {
             try await task.value
         } catch {
             if task.isCancelled { return }
             withAnimation { pendingJoin = nil }
             throw error
         }
     }
 }
 
 private extension UIApplication {
     func dismissPresentedViewControllers() {
         for scene in connectedScenes {
             guard let windowScene = scene as? UIWindowScene else { continue }
             for window in windowScene.windows where window.isKeyWindow {
                 window.rootViewController?.dismiss(animated: true)
             }
         }
     }
 }
 
 // MARK: - Game Destination
 
 /// Loads a game when navigated to.
 private struct PuzzleDisplayView: View {
     /// When opened from an `.invite` ping notification, the game's local
     /// `GameEntity` does not exist yet: the join path accepts the pending
     /// CKShare and fetches its zone. Keep showing the join spinner and retry
     /// the local load this long — measured from when the accept completes —
     /// before giving up and surfacing the underlying error.
     private static let inviteJoinTimeout: TimeInterval = 30
     private static let inviteJoinPollInterval: Duration = .seconds(1)
 
     private var syncedID: UUID? {
         preferences.isICloudSyncEnabled && session != nil ? gameID : nil
     }
 
     private var syncedScope: CKDatabase.Scope? {
         guard preferences.isICloudSyncEnabled,
               let mutator = session?.mutator
         else { return nil }
         return mutator.isOwned ? .private : .shared
     }
 
     let gameID: UUID
     let store: GameStore
     let shareController: ShareController
     let services: AppServices
 
     @Environment(PlayerPreferences.self) private var preferences
     @Environment(\.scenePhase) private var scenePhase
     @State private var session: PlayerSession?
     @State private var roster: PlayerRoster?
     @State private var loadError: String?
     @State private var loadingMessage = "Loading puzzle..."
     @State private var openPuzzleFollowUpTask: Task<Void, Never>?
 
     var body: some View {
         Group {
             if let session, let roster {
                 PuzzleView(
                     session: session,
                     shareController: shareController,
                     roster: roster,
                     onComplete: { notifyPeers in
                         do {
                             let changed = try notifyPeers
                                 ? store.markCompleted(id: gameID)
                                 : store.markCompletedFromObservedSolvedState(id: gameID)
                             if changed {
                                 // Seal the solve clock at the finish so peers and
                                 // sibling devices get the final time at once, not
                                 // only when this device next leaves the puzzle.
                                 services.sessions.noteClockCompleted(gameID: gameID)
                                 if notifyPeers {
                                     Task {
                                         await services.sessions.sendCompletionPings(gameID: gameID, resigned: false)
                                     }
                                 }
                             }
                             // The game is done — drop the other player's cursor
                             // and tear the live room down. Idempotent, so the
                             // repeated observed/on-appear completions are safe.
                             Task { await services.engagement.endEngagement(gameID: gameID) }
                         } catch {
                             services.announcements.post(Announcement(
                                 id: "mark-completed-error-\(gameID.uuidString)",
                                 scope: .game(gameID),
                                 severity: .error,
                                 title: "Saving Failed",
                                 body: error.localizedDescription,
                                 dismissal: .manual
                             ))
                         }
                     },
                     onResign: {
                         try store.resignGame(id: gameID)
                         services.sessions.noteClockCompleted(gameID: gameID)
                         Task {
                             await services.sessions.sendCompletionPings(gameID: gameID, resigned: true)
                         }
                     },
                     onDelete: { try store.deleteGame(id: gameID) },
                     onNudge: { await services.sessions.nudge(gameID: gameID) },
                     nudgeReadyAt: { services.sessions.nudgeReadyAt(gameID: gameID) },
                     loadReplay: {
                         let short = gameID.uuidString.prefix(8)
                         // Finished-game timelines are immutable (edit-lockout),
                         // so a cached assembly is reused verbatim on re-entry —
                         // this is what stops rapid nav from re-running the merge
                         // each time a fresh `ReplayControls` instance asks for it.
                         return await ReplayAssembler.memoised(
                             cached: services.replays.cachedReplayTimeline(gameID: gameID),
                             onHit: { cached in
                                 services.syncMonitor.note(
                                     "replay[\(short)]: served from timeline memo " +
                                     "(steps=\(cached.count))"
                                 )
                             },
                             store: { services.replays.cacheReplayTimeline($0, gameID: gameID) }
                         ) {
                             // Local-first: if no *other* device wrote into this
                             // game, this device's journal is the whole history,
                             // so replay needs no CloudKit. `contributingDevices`
                             // reads the per-device MovesEntity rows — the
                             // device-level signal the author-keyed roster can't
                             // give, so it sees this account's own second device,
                             // not just other people. Any other contributor →
                             // merged fetch, which gates on every contributing
                             // device's journal.
                             let entries = store.localJournalEntries(for: gameID)
                             let localDeviceID = RecordSerializer.localDeviceID
                             let otherDevices = store.contributingDevices(for: gameID)
                                 .filter { $0.deviceID != localDeviceID }
                             if otherDevices.isEmpty {
                                 services.syncMonitor.note(
                                     "replay[\(short)]: local-only path " +
                                     "(no other contributing devices), localEntries=\(entries.count)"
                                 )
                                 return .ready(ReplayTimeline(merging: [entries]))
                             }
                             services.syncMonitor.note(
                                 "replay[\(short)]: merged path, " +
                                 "otherDevices=\(otherDevices.count), localEntries=\(entries.count)"
                             )
                             return await services.replays.loadReplay(gameID: gameID)
                         }
                     },
                     loadRecentChanges: {
                         // Cells a peer changed since this device last viewed the
                         // game. A missing timestamp means a first-ever open —
                         // establish the baseline silently rather than flag the
                         // whole board (the leave/background path below stamps it).
                         guard let since = services.gameViewedStore.lastViewed(forGame: gameID)
                         else { return [:] }
                         services.syncMonitor.note(
                             "recent changes[\(gameID.uuidString.prefix(8))] open diag: "
                             + store.recentChangesDiagnosticSummary(forGame: gameID, since: since)
                         )
                         return store.recentlyChangedCells(forGame: gameID, since: since)
                     },
                     markPuzzleViewed: { stampPuzzleViewed() }
                 )
             } else if let loadError {
                 ContentUnavailableView(
                     "Couldn't load puzzle",
                     systemImage: "exclamationmark.triangle",
                     description: Text(loadError)
                 )
             } else {
                 ProgressView(loadingMessage)
                     .frame(maxWidth: .infinity, maxHeight: .infinity)
             }
         }
         .navigationTitle("")
         .navigationBarTitleDisplayMode(.inline)
         .task(id: syncedID) {
             guard let scope = syncedScope else { return }
             await services.freshenPuzzleGrid(gameID: gameID, scope: scope, reason: .appeared)
         }
         .task(id: gameID) {
             openPuzzleFollowUpTask?.cancel()
             openPuzzleFollowUpTask = nil
             session = nil
             roster = nil
             loadError = nil
             loadingMessage = "Loading puzzle..."
             noteSessionPhase(scenePhase)
             Task { await services.badge.dismissDeliveredNotifications(for: gameID) }
 
             // Tapping an `.invite` ping notification navigates here at once,
             // before this game's `GameEntity` exists locally. Only for that
             // explicitly-flagged case do we treat a missing game as "still
             // joining": accept the pending CKShare (see below) and wait for
             // the shared zone to land, instead of hard-erroring.
             let fromInvitePing =
                 NotificationNavigationBroker.shared.consumeInviteOrigin(gameID)
             var joinDeadline = Date().addingTimeInterval(Self.inviteJoinTimeout)
             var didAcceptInvite = false
 
             while !Task.isCancelled {
                 do {
                     if let plan = NYTPuzzleUpgrader.plan(for: gameID, store: store) {
                         loadingMessage = "Updating puzzle..."
                         let fetcher = services.nytFetcher
                         let outcome = await NYTPuzzleUpgrader.apply(plan: plan, store: store) { date in
                             try await fetcher.fetchPuzzle(for: date)
                         }
                         switch outcome {
                         case .upgraded:
                             services.eventLog.note("[upgrade NYT \(gameID.uuidString.prefix(8))] applied")
                         case .mismatched(let reason):
                             services.eventLog.note("[upgrade NYT \(gameID.uuidString.prefix(8))] structural mismatch — \(reason)", level: "warn")
                         case .failed(let error):
                             services.eventLog.note("[upgrade NYT \(gameID.uuidString.prefix(8))] fetch failed: \(error)", level: "error")
                         }
                     }
                     let (game, mutator) = try store.loadGame(id: gameID)
                     let newSession = PlayerSession(
                         game: game,
                         mutator: mutator,
                         cursorStore: services.cursorStore
                     )
                     let newRoster = services.makePlayerRoster(for: gameID, preferences: preferences)
                     roster = newRoster
                     session = newSession
                     openPuzzleFollowUpTask = Task { @MainActor in
                         await finishOpeningPuzzle(
                             session: newSession,
                             roster: newRoster,
                             isShared: mutator.isShared
                         )
                     }
                     break
                 } catch GameStore.LoadError.gameNotFound
                     where fromInvitePing
                         && preferences.isICloudSyncEnabled
                         && Date() < joinDeadline {
                     loadingMessage = "Joining shared puzzle..."
 
                     // Tapping the `.invite` notification only navigated here;
                     // it did not accept the CKShare. Do that ourselves, once —
                     // without it the game's `GameEntity` never materialises and
                     // the join can only time out. The accept also fetches the
                     // shared zone, so on success the next `loadGame` finds the
                     // game; the deadline is reset because the accept itself can
                     // outlast the original window.
                     if !didAcceptInvite {
                         didAcceptInvite = true
                         do {
                             try await services.invites.acceptPendingInvite(gameID: gameID)
                             joinDeadline = Date()
                                 .addingTimeInterval(Self.inviteJoinTimeout)
                         } catch {
                             if !Task.isCancelled {
                                 loadError = error.localizedDescription
                             }
                             break
                         }
                         continue
                     }
 
                     do {
                         try await Task.sleep(for: Self.inviteJoinPollInterval)
                     } catch {
                         break // task cancelled
                     }
                 } catch {
                     loadError = String(describing: error)
                     break
                 }
             }
         }
         .task(id: session?.mutator.isShared == true) {
             // Solve-clock liveness heartbeat. Only for a shared game on screen:
             // a co-solver extrapolates this device's open session toward now only
             // as far as its last beat, so a continuous sitting must keep beating
             // or it would be briefly capped on their clock. Solo games skip it —
             // the local clock already extrapolates to now and no peer is watching.
             // Cancelled on leave or gameID change.
             guard session?.mutator.isShared == true else { return }
             while !Task.isCancelled {
                 try? await Task.sleep(for: .seconds(SessionCoordinator.clockHeartbeatInterval))
                 guard !Task.isCancelled else { break }
                 services.sessions.noteClockHeartbeat(gameID: gameID)
             }
         }
         .onChange(of: session?.mutator.isShared) { oldValue, newValue in
             // Fire only on a definite `false → true` transition — that's the
             // mid-session share-create case. Initial loads of an already-shared
             // game go `nil → true` and are handled inline in `task(id: gameID)`.
             guard oldValue == false, newValue == true,
                   let session,
                   preferences.isICloudSyncEnabled
             else { return }
             Task { await activateSharing(for: session) }
         }
         .onChange(of: scenePhase) { _, newPhase in
             noteSessionPhase(newPhase)
             // Only act on settled transitions. `.inactive` is transient (lock
             // animation, app switcher, Control Center, banners), so a write
             // there would thrash the Player record on every lock/unlock.
             // `.background` publishes the cursor so sibling devices catch up
             // promptly; `.active` republishes on resume in case moves arrived
             // (and were marked seen in lockstep) while we were foregrounded.
             let id = gameID
             switch newPhase {
             case .active:
                 Task {
                     await services.publishReadCursor(for: id, mode: .activeLease)
                     // Backgrounding tears the engagement socket down without
                     // rebuilding it, so a live session that dropped while we
                     // were away never comes back on its own. Re-offer on
                     // resume; this is a no-op when the channel is still live
                     // (the coordinator only acts from an idle state).
                     await services.engagement.startEngagementIfPossible(gameID: id)
                 }
                 // Reveal any peer changes that landed while we were away on the
                 // same resume the catch-up banner re-derives on, not only on a
                 // fresh navigation into the puzzle.
                 Task { await recaptureRecentChanges() }
             case .background:
                 // Stop the engagement reconnect loop so it doesn't keep
                 // re-dialling the live socket on background CKSyncEngine wakes.
                 // (Re-leasing `readAt` in the background is now prevented
                 // centrally by publishReadCursor's foreground gate, not here.)
                 // `.active` re-arms the loop via `startEngagementIfPossible`.
                 services.engagement.cancelEngagementReconnectRetry(gameID: id)
                 Task { await services.publishReadCursor(for: id, mode: .currentTime) }
                 // Backgrounding counts as leaving for the away-change baseline:
                 // anything a peer does after this should flag on the next open.
                 stampPuzzleViewed()
             case .inactive:
                 break
             @unknown default:
                 break
             }
         }
         .onDisappear {
             openPuzzleFollowUpTask?.cancel()
             openPuzzleFollowUpTask = nil
             let selectionPublisher = services.playerSelectionPublisher
             let movesUpdater = services.movesUpdater
             let id = gameID
             // Navigating away is a leave: clear the active-puzzle ID and commit
             // the catch-up baseline (idempotent with the .background path).
             services.sessions.notePuzzleClosed(gameID: id)
             services.engagement.scheduleEngagementEnd(gameID: id)
             // Navigating away is a leave: stamp the away-change baseline so the
             // next open diffs against now.
             stampPuzzleViewed()
             Task {
                 await movesUpdater.flush()
                 // The clear-cursor and close-lease writes both enqueue without
                 // forcing a drain (see `enqueuePlayer`'s `drain` flag), so there
                 // are no sends for a burst to collapse — CKSyncEngine ships both
                 // Player-record changes on its own schedule.
                 await selectionPublisher.clear()
                 await services.publishReadCursor(for: id, mode: .currentTime)
                 // The pause self-gates on content (no letter changes reaches
                 // no one) and supersedes any pending grace-window timer, so the
                 // close-after-background case never fires a second push.
                 await services.sessions.publishSessionEndPush(gameID: id)
             }
         }
     }
 
     private func finishOpeningPuzzle(
         session loadedSession: PlayerSession,
         roster loadedRoster: PlayerRoster,
         isShared: Bool
     ) async {
         await loadedRoster.refresh()
         guard !Task.isCancelled, session === loadedSession else { return }
 
         // Re-derive banners that hang off persisted game state (e.g. the
         // access-revoked banner). They are otherwise posted only on the live
         // sync transition that first produces them, which a puzzle opened in
         // a later process never re-fires.
         let openState = OpenPuzzleState(
             gameID: gameID,
             isAccessRevoked: loadedSession.mutator.isAccessRevoked
         )
         for announcement in OpenPuzzleBanner.announcements(for: openState) {
             services.announcements.post(announcement)
         }
         if isShared && preferences.isICloudSyncEnabled {
             services.syncMonitor.note(
                 "PuzzleDisplay[\(gameID.uuidString.prefix(8))]: loaded shared roster"
             )
             await services.logPlayerLeaseSnapshot(gameID: gameID)
             await activateSharing(for: loadedSession, refreshRoster: false)
         } else {
             services.syncMonitor.note(
                 "PuzzleDisplay[\(gameID.uuidString.prefix(8))]: loaded local roster"
             )
             await services.publishReadCursor(for: gameID, mode: .activeLease)
             await services.playerSelectionPublisher.clear()
         }
     }
 
     /// Forwards settled scene phases to the session controller, which owns
     /// the begin/end/grace choreography (active-puzzle ID, deferred play and
     /// pause pushes, catch-up banner).
     private func noteSessionPhase(_ phase: ScenePhase) {
         switch phase {
         case .active:
             services.sessions.notePuzzleActive(gameID: gameID)
         case .background:
             services.sessions.notePuzzleBackgrounded(gameID: gameID)
         case .inactive:
             // Transient (lock animation, app switcher, Control Center,
             // banners) — the user is still on the puzzle. Toggling the
             // active-puzzle ID or firing a pause push here would thrash
             // both on every interruption.
             break
         @unknown default:
             break
         }
     }
 
     /// Records that this device has now viewed the game up to the current
     /// moment, the baseline the next open diffs against for "changed while you
     /// were away" borders. Device-local; only shared games are tracked (solo
     /// games have no peers to surface). Called on the player's first
     /// interaction (via `PuzzleView`'s acknowledgement) and on leave/background.
     private func stampPuzzleViewed() {
         guard session?.mutator.isShared == true else { return }
         services.gameViewedStore.advance(Date(), forGame: gameID)
     }
 
     /// Recaptures the "changed while you were away" borders against the current
     /// view baseline. The `.task`-driven capture only runs on a fresh open, so a
     /// background→foreground resume of the same open puzzle would otherwise leave
     /// the borders stale (or absent) even as the catch-up banner re-derives.
     /// Mirrors the open beat's settle so the diff reflects the freshened grid;
     /// idempotent — `recentChanges` is `Equatable`, and the baseline only
     /// advances on leave.
     private func recaptureRecentChanges() async {
         try? await Task.sleep(for: .milliseconds(750))
         guard let session, session.mutator.isShared,
               let since = services.gameViewedStore.lastViewed(forGame: gameID)
         else { return }
         services.syncMonitor.note(
             "recent changes[\(gameID.uuidString.prefix(8))] recapture diag: "
             + store.recentChangesDiagnosticSummary(forGame: gameID, since: since)
         )
         session.recentChanges = store.recentlyChangedCells(forGame: gameID, since: since)
     }
 
     /// Initialises shared-game state (roster, selection publishing, name broadcast) for
     /// the open session. Called when the puzzle first appears as shared, and
     /// again if a previously-solo game becomes shared mid-session.
     private func activateSharing(for session: PlayerSession, refreshRoster: Bool = true) async {
         Task { await AppDelegate.requestNotificationAuthorizationIfNeeded() }
         let activeRoster: PlayerRoster
         if let roster {
             activeRoster = roster
         } else {
             let newRoster = services.makePlayerRoster(for: gameID, preferences: preferences)
             roster = newRoster
             activeRoster = newRoster
         }
         if refreshRoster {
             await activeRoster.refresh()
         }
         guard let authorID = services.identity.currentID else { return }
         let selectionPublisher = services.playerSelectionPublisher
         // Fan out read-cursor lease, display name, and the initial cursor
         // track inside one Player-record send burst so they ship in a single
         // CKSyncEngine drain. Name publish lands before the selection so the
         // partner never sees a "Player" placeholder; the burst close then
         // issues exactly one `sendChanges`. Subsequent selection edits go
         // through `PlayerSelectionPublisher`'s trailing-edge debounce and
         // each fires its own drain — same shape as Moves.
         let syncEngine = services.syncEngine
         let burstScope = await syncEngine.beginPlayerSendBurst(gameID: gameID)
         // Stamp this game's derived push address inside the burst so it ships on
         // the same Player-record write as the read-cursor lease; registration of
         // this device under it happens just after the burst.
         _ = services.accountPush.setDerivedPushAddress(gameID: gameID, authorID: authorID)
         await services.publishReadCursor(for: gameID, mode: .activeLease)
         await services.playerNamePublisher?.publishName(for: gameID)
         await selectionPublisher.begin(
             gameID: gameID,
             authorID: authorID,
             currentName: preferences.name
         )
         if let track = session.currentCursorTrack {
             await selectionPublisher.publishImmediately(track)
             await services.engagement.noteLocalSelection(track, gameID: gameID)
         }
         if let burstScope {
             await syncEngine.endPlayerSendBurst(scope: burstScope)
         }
         // Register this device under the (now-minted) address set so the
         // just-opened game can deliver pushes here immediately.
         await services.accountPush.reconcilePushRegistration()
         await services.engagement.startEngagementIfPossible(gameID: gameID)
         let services = self.services
         let eventGameID = gameID
         session.onSelectionChanged = { selection in
             Task {
                 await selectionPublisher.publish(selection)
                 await services.engagement.noteLocalSelection(selection, gameID: eventGameID)
             }
         }
         // check/reveal no longer ping peers; cell state propagates through
         // Moves (the cell's `CellMark` carries the check/reveal result).
     }
 
 }