crossmate

CrossmateApp.swift (58161B)

---

 import CloudKit
 import SwiftUI
 import UserNotifications
 
 @main
 struct CrossmateApp: App {
     @UIApplicationDelegateAdaptor private var appDelegate: AppDelegate
 
     @State private var services: AppServices
 
     init() {
         AppDefaultsMigrator.run()
         let services = AppServices()
         self._services = State(initialValue: services)
         AppServices.current = services
     }
 
     var body: some Scene {
         WindowGroup {
             #if DEBUG
             if MarketingLaunch.isImportScene {
                 // The import scene drives the real Game List + New Puzzle sheet
                 // (seeded via `--crossmate-seed-demo`); `GameListView` opens the
                 // sheet and seeds the Imported tab when it detects this mode.
                 rootContent
             } else if MarketingLaunch.isScreenshot {
                 MarketingScreenshotView(services: services)
                     .environment(services.preferences)
                     .environment(services.inputMonitor)
                     .environment(services.announcements)
                     .environment(\.engagementStatus, services.engagementStatus)
             } else {
                 rootContent
             }
             #else
             rootContent
             #endif
         }
         .commands {
             PuzzleCommands()
         }
     }
 
     private var rootContent: some View {
         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(\.appActions, services.appActions)
     }
 }
 
 // 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)
     }
 
     /// The handlers below are installed by `AppServices.start`, which runs
     /// from the root view's asynchronous startup task — and UIKit can deliver
     /// the APNs token or a remote notification before that task gets there.
     /// Each callback therefore buffers what arrives early, and each handler
     /// replays its buffer on assignment (the same cold-launch handoff the
     /// notification-navigation and share-acceptance brokers provide), so a
     /// callback that wins the race against SwiftUI startup is deferred rather
     /// than lost.
     var onRemoteNotification: ((
         String,
         CKDatabase.Scope?,
         PushPayload.Event?,
         UUID?,
         String?,
         String?,
         Date?,
         Bool
     ) async -> Void)? {
         didSet { drainBufferedRemoteNotifications() }
     }
     /// 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)? {
         didSet {
             guard let handler = onAPNsRegistrationResult,
                   let message = bufferedAPNsRegistrationResult else { return }
             bufferedAPNsRegistrationResult = nil
             handler(message)
         }
     }
     /// 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)? {
         didSet {
             guard let handler = onAPNsToken,
                   let token = bufferedAPNsToken else { return }
             bufferedAPNsToken = nil
             handler(token)
         }
     }
     /// Tells the app that visible notification receipts may be waiting in the
     /// App Group ring buffer written by the Notification Service Extension.
     /// Deliberately unbuffered: `AppServices.start` imports the ring buffer
     /// unconditionally, so an early call is covered by startup itself.
     var onVisibleNotificationReceiptsAvailable: (() -> Void)?
 
     /// A remote notification that arrived before `onRemoteNotification` was
     /// installed, captured with its already-derived fields — including the
     /// arrival-time background flag, so the replay preserves the state the
     /// push actually arrived in.
     private struct BufferedRemoteNotification {
         let summary: String
         let scope: CKDatabase.Scope?
         let event: PushPayload.Event?
         let gameID: UUID?
         let kind: String?
         let senderDeviceID: String?
         let presenceUntil: Date?
         let isBackground: Bool
     }
 
     private var bufferedAPNsRegistrationResult: String?
     private var bufferedAPNsToken: Data?
     private var bufferedRemoteNotifications: [BufferedRemoteNotification] = []
     /// Bounds a pathological pre-start push burst. Oldest entries drop first —
     /// pushes are wake signals, and the newest reflects current server state.
     private static let bufferedRemoteNotificationCap = 8
 
     private func bufferRemoteNotification(_ push: BufferedRemoteNotification) {
         // A pre-start push is a wake signal, not a work item: a second push
         // from the same source supersedes the queued one (carrying the newer
         // presence deadline) instead of queueing duplicate fetch work for the
         // drain.
         if let index = bufferedRemoteNotifications.firstIndex(where: {
             $0.scope == push.scope
                 && $0.event == push.event
                 && $0.gameID == push.gameID
                 && $0.kind == push.kind
                 && $0.senderDeviceID == push.senderDeviceID
         }) {
             bufferedRemoteNotifications[index] = push
         } else {
             bufferedRemoteNotifications.append(push)
             if bufferedRemoteNotifications.count > Self.bufferedRemoteNotificationCap {
                 bufferedRemoteNotifications.removeFirst()
             }
         }
     }
 
     /// The in-flight drain, kept so a background wake that drove startup can
     /// await the buffered work before completing its fetch handler. Chained:
     /// a new drain awaits its predecessor, so replays never interleave.
     private var remoteNotificationDrain: Task<Void, Never>?
 
     /// Test seams for the process-global UIApplication/AppServices lookup in
     /// the background-only startup path. Production leaves both nil.
     var isInstalledApplicationDelegateForTesting: Bool?
     var startServicesForTesting: (() async -> Void)?
 
     private func drainBufferedRemoteNotifications() {
         guard onRemoteNotification != nil, !bufferedRemoteNotifications.isEmpty else { return }
         let previous = remoteNotificationDrain
         remoteNotificationDrain = Task { @MainActor in
             await previous?.value
             while !bufferedRemoteNotifications.isEmpty {
                 let push = bufferedRemoteNotifications.removeFirst()
                 await onRemoteNotification?(
                     push.summary,
                     push.scope,
                     push.event,
                     push.gameID,
                     push.kind,
                     push.senderDeviceID,
                     push.presenceUntil,
                     push.isBackground
                 )
             }
         }
     }
 
     private func deliverAPNsRegistrationResult(_ message: String) {
         if let onAPNsRegistrationResult {
             onAPNsRegistrationResult(message)
         } else {
             bufferedAPNsRegistrationResult = message
         }
     }
 
     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)
         deliverAPNsRegistrationResult("APNs registered token=\(prefix)… (\(deviceToken.count) bytes)")
         if let onAPNsToken {
             onAPNsToken(deviceToken)
         } else {
             bufferedAPNsToken = deviceToken
         }
     }
 
     func application(
         _ application: UIApplication,
         didFailToRegisterForRemoteNotificationsWithError error: Error
     ) {
         let nsError = error as NSError
         deliverAPNsRegistrationResult(
             "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
         }
         // Invite rows are populated by an async sync pass after the push
         // arrives. Present the foreground notification so the invite is still
         // visible while that row catches up.
         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
         }
 
         Task { @MainActor in
             if Self.isInviteNotification(userInfo) {
                 NotificationNavigationBroker.shared.openGameList(inviteGameID: gameID)
             } else {
                 NotificationNavigationBroker.shared.openGame(gameID)
             }
             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 static func isInviteNotification(_ userInfo: [AnyHashable: Any]) -> Bool {
         (userInfo["pingKind"] as? String) == PingKind.invite.rawValue
             || (userInfo["kind"] as? String) == PingKind.invite.rawValue
     }
 
     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 presenceUntil = Self.date(from: userInfo["presenceUntil"] as? String)
         let isBackground = application.applicationState != .active
         guard let onRemoteNotification else {
             // Pre-start arrival: buffer the wake, then drive startup — this
             // push may be the only driver the process gets, because on a
             // background-only launch no scene activates and the root view's
             // startup task never runs. `start` is one-shot and shares its
             // in-flight task, so racing the root task waits for the same
             // handler-ready boundary. Awaiting the drain then keeps the fetch
             // completion honest — it reports after the buffered work ran,
             // inside the background execution budget.
             //
             // Only the installed delegate may do this: a delegate the system
             // is not using (unit tests construct their own) must not capture
             // the real handlers by starting services itself.
             bufferRemoteNotification(BufferedRemoteNotification(
                 summary: summary,
                 scope: scope,
                 event: payload?.event,
                 gameID: gameID,
                 kind: kind,
                 senderDeviceID: senderDeviceID,
                 presenceUntil: presenceUntil,
                 isBackground: isBackground
             ))
             let isInstalledDelegate = isInstalledApplicationDelegateForTesting
                 ?? (application.delegate === self)
             if isInstalledDelegate, let startServicesForTesting {
                 await startServicesForTesting()
                 await remoteNotificationDrain?.value
             } else if isInstalledDelegate, let services = AppServices.current {
                 await services.start(appDelegate: self)
                 await remoteNotificationDrain?.value
             }
             return .newData
         }
         await onRemoteNotification(
             summary,
             scope,
             payload?.event,
             gameID,
             kind,
             senderDeviceID,
             presenceUntil,
             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() }
     }
     var onOpenGameList: (() -> Void)? {
         didSet { flushPendingGameListOpen() }
     }
     var onOpenInviteInGameList: ((UUID) -> Void)? {
         didSet { flushPendingInviteGameListOpen() }
     }
     /// Swaps the puzzle on top of the stack for another row representing the
     /// same puzzle — the live game → Chronicle handover. Deliberately unbuffered,
     /// unlike the open handlers above: with no handler installed there is no
     /// navigation stack showing that puzzle, so there is nothing to correct.
     var onReplaceOpenGame: ((_ from: UUID, _ to: UUID) -> Void)?
 
     private var pendingGameIDs: [UUID] = []
     private var pendingGameListOpen = false
     private var pendingInviteGameIDs: [UUID] = []
 
     private init() {}
 
     func openGame(_ gameID: UUID) {
         guard let onOpenGame else {
             pendingGameIDs.append(gameID)
             return
         }
         onOpenGame(gameID)
     }
 
     func replaceOpenGame(_ from: UUID, with to: UUID) {
         onReplaceOpenGame?(from, to)
     }
 
     func openGameList(inviteGameID: UUID? = nil) {
         if let inviteGameID {
             guard let onOpenInviteInGameList else {
                 pendingInviteGameIDs.append(inviteGameID)
                 return
             }
             onOpenInviteInGameList(inviteGameID)
             return
         }
         guard let onOpenGameList else {
             pendingGameListOpen = true
             return
         }
         onOpenGameList()
     }
 
     private func flushPendingGameIDs() {
         guard let onOpenGame, !pendingGameIDs.isEmpty else { return }
         let gameIDs = pendingGameIDs
         pendingGameIDs.removeAll()
         for gameID in gameIDs {
             onOpenGame(gameID)
         }
     }
 
     private func flushPendingGameListOpen() {
         guard let onOpenGameList, pendingGameListOpen else { return }
         pendingGameListOpen = false
         onOpenGameList()
     }
 
     private func flushPendingInviteGameListOpen() {
         guard let onOpenInviteInGameList, !pendingInviteGameIDs.isEmpty else { return }
         let gameIDs = pendingInviteGameIDs
         pendingInviteGameIDs.removeAll()
         for gameID in gameIDs {
             onOpenInviteInGameList(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: [UUID] = []
     @State private var pendingJoin: PendingJoinPlaceholder?
     @State private var pendingInviteNotificationGameID: UUID?
     /// 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() },
                 onLoadRecentCompleted: { cutoff in
                     await services.loadRecentCompleted(since: cutoff)
                 },
                 onLoadMoreCompleted: {
                     await services.loadMoreCompleted()
                 },
                 onDisappear: { services.gameListDisappeared() },
                 onAcceptInvite: { shareURL, pingRecordName, shape in
                     try await acceptInviteFromGameList(
                         shareURL: shareURL,
                         pingRecordName: pingRecordName,
                         shape: shape
                     )
                 },
                 pendingInviteNotificationGameID: $pendingInviteNotificationGameID,
                 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.append(gameID)
             }
             NotificationNavigationBroker.shared.onOpenGameList = {
                 UIApplication.shared.dismissPresentedViewControllers()
                 navigationPath = []
                 pendingInviteNotificationGameID = nil
             }
             NotificationNavigationBroker.shared.onOpenInviteInGameList = { gameID in
                 UIApplication.shared.dismissPresentedViewControllers()
                 navigationPath = []
                 pendingInviteNotificationGameID = gameID
             }
             NotificationNavigationBroker.shared.onReplaceOpenGame = { from, to in
                 // Only the puzzle actually on top is swapped; anything deeper (or
                 // a stack the user has since left) is left alone.
                 guard navigationPath.last == from else { return }
                 // One assignment, so the stack goes straight from the live game
                 // to its Chronicle rather than popping and pushing. Animations
                 // off for the same reason: this is a substitution of one
                 // representation for another, not a navigation the user made.
                 var transaction = Transaction()
                 transaction.disablesAnimations = true
                 withTransaction(transaction) {
                     navigationPath[navigationPath.count - 1] = to
                 }
             }
             // 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 = CloudService.cloudErrorCode(error)
                         let gone = (error as? AcceptedShareError)?.kind == .removed
                             || code == .unknownItem
                             || code == .zoneNotFound
                         let versionMismatch = (error as? CloudServiceError) == .containerVersionMismatch
                         // Both of these are the user's world being different to
                         // what the link assumed, not something broken: warn and
                         // explain rather than reporting a failure.
                         let expected = gone || versionMismatch
                         let copy: (title: String, body: String)
                         if versionMismatch {
                             copy = ("Update Needed", error.localizedDescription)
                         } else if gone {
                             copy = ("Puzzle Removed", "This puzzle was removed.")
                         } else {
                             copy = CloudFailureCopy.joinFailure(for: error)
                         }
                         services.eventLog.note(
                             "share link join failed: \(error.localizedDescription)",
                             level: expected ? "info" : "error"
                         )
                         services.announcements.post(Announcement(
                             id: "share-link-join-failed",
                             scope: .global,
                             severity: expected ? .warning : .error,
                             title: copy.title,
                             body: copy.body,
                             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 {
     private var syncedID: UUID? {
         guard preferences.isICloudSyncEnabled,
               let mutator = session?.mutator,
               !mutator.isArchived
         else { return nil }
         return gameID
     }
 
     private var syncedScope: CKDatabase.Scope? {
         guard preferences.isICloudSyncEnabled,
               let mutator = session?.mutator,
               !mutator.isArchived
         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
                         guard !session.mutator.isArchived else { return }
                         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)
                             }
                             // 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)
                     },
                     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 only for unshared games: this device's
                             // journal is the whole history, so replay needs no
                             // CloudKit. Shared games always use the merged
                             // loader, even if their Moves rows have not caught
                             // up locally yet, so replay can wait for every
                             // contributing device's journal instead of caching
                             // an incomplete local timeline.
                             let entries = store.localJournalEntries(for: gameID)
                             if !store.isGameShared(gameID: gameID),
                                !store.isGameArchived(gameID: gameID) {
                                 services.syncMonitor.note(
                                     "replay[\(short)]: local-only path " +
                                     "(unshared game), localEntries=\(entries.count)"
                                 )
                                 return .ready(ReplayTimeline(merging: [entries]))
                             }
                             services.syncMonitor.note(
                                 "replay[\(short)]: shared merged path, " +
                                 "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 [:] }
                         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…"
             let canonicalGameID = store.canonicalGameID(for: gameID)
             Task {
                 await services.badge.dismissDeliveredNotifications(
                     for: canonicalGameID
                 )
             }
 
             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,
                     preferences: preferences
                 )
                 let newRoster = services.makePlayerRoster(for: gameID, preferences: preferences)
                 await newRoster.preload()
                 guard !Task.isCancelled else { return }
                 roster = newRoster
                 session = newSession
                 noteSessionPhase(scenePhase)
                 openPuzzleFollowUpTask = Task { @MainActor in
                     await finishOpeningPuzzle(
                         session: newSession,
                         roster: newRoster,
                         isShared: mutator.isShared
                     )
                 }
             } catch {
                 loadError = String(describing: error)
             }
         }
         .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
             guard session?.mutator.isArchived == false else { return }
             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 `presenceUntil` 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
             }
         }
         .onAppear {
             services.puzzleAppeared(gameID: gameID)
         }
         .onDisappear {
             openPuzzleFollowUpTask?.cancel()
             openPuzzleFollowUpTask = nil
             services.puzzleDisappeared(gameID: gameID)
             guard session?.mutator.isArchived == false else { return }
             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,
             isSyncSupported: loadedSession.mutator.isSyncSupported
         )
         for announcement in OpenPuzzleBanner.announcements(for: openState) {
             services.announcements.post(announcement)
         }
         if loadedSession.mutator.isArchived {
             services.syncMonitor.note(
                 "PuzzleDisplay[\(gameID.uuidString.prefix(8))]: loaded Chronicle roster " +
                 "(live lifecycle disabled)"
             )
             // The Chronicle is a local projection with a derived storage ID.
             // Publish the read watermark through the retained live game's
             // original identity so sibling devices clear the same Completed
             // tile and app-icon badge.
             await services.publishReadCursor(
                 for: store.canonicalGameID(for: gameID),
                 mode: .currentTime
             )
             return
         }
         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) {
         guard session?.mutator.isArchived == false else { return }
         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 }
         // Pair the away baseline with a seed request. Sharing activation
         // normally established it already; this also covers a very quick leave
         // and ensures an empty grid is recorded as an intentional snapshot.
         store.ensurePeerChangeLedgerSeeded(for: gameID)
         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 }
         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 {
         // Establish the local letter snapshot while the puzzle is visible, so
         // the first inbound Moves record can be compared with it. This also
         // records an intentionally empty snapshot for a puzzle with no entries.
         store.ensurePeerChangeLedgerSeeded(for: gameID)
         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 current address set. The open burst
         // already stamped this game's Player row, so avoid a full repair sweep.
         await services.accountPush.refreshPushRegistration()
         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).
     }
 
 }