← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


commit 266a0c5c47c0f1e75391fed0873a8d29c86ab786
parent 48d8875767cfa36fce7f8c4b121d29b4129c65cf
Author: Michael Camilleri <[email protected]>
Date:   Sun, 24 May 2026 13:15:51 +0900

Replace Player coalesce timer with an explicit open burst

The previous commit added a 750 ms per-scope window on top of
PlayerSelectionPublisher's existing 500 ms debounce so the puzzle-open fan-out
(read cursor + name-open + the trailing cursor track) shipped in one
CKSyncEngine drain. That required the two timers to be tuned together — the
outbound window's docstring literally encoded the arithmetic of "500 ms
upstream debounce + actor hop" — and a steady-state rename or read-cursor
refresh paid 750 ms of wall-clock latency it did not need. enqueuePlayer now
drains immediately like enqueueMoves; the puzzle- open path brackets its
fan-out in beginPlayerSendBurst/endPlayerSendBurst, which gate the per-enqueue
drain via a per-scope depth counter and issue one sendChanges when the
outermost frame exits. PlayerSelectionPublisher gains publishImmediately(_:) so
the initial cursor track can ride the burst instead of arriving 500 ms later
via the source-side debounce. PlayerSession exposes currentCursorTrack so the
open path can hand that track over directly rather than round-tripping through
onSelectionChanged.

The net effect is one round-trip on open (same as before) and one round-trip
per write at steady state (down from one per 750 ms tick), with the batching
bounded by the work that produces it rather than by a wall-clock window that
has to be re-derived whenever upstream timings shift. resetSyncState now also
clears the new burst-state maps so a reset that races a puzzle-open can't leave
a stale depth gating drains on the freshly-swapped engines.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

Diffstat

MCrossmate/CrossmateApp.swift | 25++++++++++++++++++-------
MCrossmate/Models/PlayerSession.swift | 18+++++++++++++-----
MCrossmate/Services/AppServices.swift | 8++++----
MCrossmate/Services/PlayerNamePublisher.swift | 10+++++-----
MCrossmate/Sync/PlayerSelectionPublisher.swift | 14++++++++++++++
MCrossmate/Sync/SyncEngine.swift | 81+++++++++++++++++++++++++++++++++++++++++++++++--------------------------------
MTests/Unit/PlayerNamePublisherTests.swift | 4++--
MTests/Unit/Sync/ZoneOrphaningTests.swift | 2+-

8 files changed, 105 insertions(+), 57 deletions(-)

diff --git a/Crossmate/CrossmateApp.swift b/Crossmate/CrossmateApp.swift

@@ -497,7 +497,6 @@ private struct PuzzleDisplayView: View {
                     let newRoster = services.makePlayerRoster(for: gameID, preferences: preferences)
                     roster = newRoster
                     session = newSession
-                    Task { await services.publishReadCursor(for: gameID, mode: .activeLease) }
                     openPuzzleFollowUpTask = Task { @MainActor in
                         await finishOpeningPuzzle(
                             session: newSession,
@@ -619,6 +618,7 @@ private struct PuzzleDisplayView: View {
             services.syncMonitor.note(
                 "PuzzleDisplay[\(gameID.uuidString.prefix(8))]: loaded local roster"
             )
+            await services.publishReadCursor(for: gameID, mode: .activeLease)
             await services.playerSelectionPublisher.clear()
         }
     }
@@ -652,18 +652,30 @@ private struct PuzzleDisplayView: View {
         if refreshRoster {
             await activeRoster.refresh()
         }
-        // Publish the local user's name to this game's zone before any
-        // selection publish — otherwise the partner sees "Player" until we
-        // happen to rename ourselves. Keep this scoped to the open game so a
-        // stale shared zone elsewhere cannot hold up this collaboration.
-        await services.playerNamePublisher?.publishName(for: gameID)
         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)
+        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)
+        }
+        if let burstScope {
+            await syncEngine.endPlayerSendBurst(scope: burstScope)
+        }
         session.onSelectionChanged = { selection in
             Task { await selectionPublisher.publish(selection) }
         }
@@ -678,7 +690,6 @@ private struct PuzzleDisplayView: View {
                 )
             }
         }
-        session.publishCurrentSelection()
     }
 
     private func pollOpenSyncedPuzzle() async {

diff --git a/Crossmate/Models/PlayerSession.swift b/Crossmate/Models/PlayerSession.swift

@@ -127,16 +127,24 @@ final class PlayerSession {
 
     func publishCurrentSelection() {
         guard let onSelectionChanged else { return }
-        guard let track = puzzle.cursorTrack(
-            atRow: selectedRow,
-            col: selectedCol,
-            direction: direction
-        ) else { return }
+        guard let track = currentCursorTrack else { return }
         guard track != lastPublishedCursorTrack else { return }
         lastPublishedCursorTrack = track
         onSelectionChanged(track)
     }
 
+    /// Cursor track for the active selection, or `nil` if the selected
+    /// cell has no answer slot in the current direction. Exposed so the
+    /// puzzle-open path can ship the initial track in the open burst
+    /// without routing it through `onSelectionChanged`'s debounced sink.
+    var currentCursorTrack: PlayerSelection? {
+        puzzle.cursorTrack(
+            atRow: selectedRow,
+            col: selectedCol,
+            direction: direction
+        )
+    }
+
     func select(row: Int, col: Int) {
         guard isValid(row: row, col: col), !puzzle.cells[row][col].isBlock else { return }
         if row == selectedRow && col == selectedCol {

diff --git a/Crossmate/Services/AppServices.swift b/Crossmate/Services/AppServices.swift

@@ -208,7 +208,7 @@ final class AppServices {
             sink: { gameID, authorID in
                 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
                 guard isEnabled else { return }
-                await syncEngine.enqueuePlayerRecord(
+                await syncEngine.enqueuePlayer(
                     gameID: gameID,
                     authorID: authorID,
                     reason: "selection"
@@ -391,10 +391,10 @@ final class AppServices {
             preferences: preferences,
             persistence: persistence,
             authorIdentity: identity,
-            enqueuePlayerRecord: { [preferences, syncEngine] gameID, authorID, reason in
+            enqueuePlayer: { [preferences, syncEngine] gameID, authorID, reason in
                 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
                 guard isEnabled else { return }
-                await syncEngine.enqueuePlayerRecord(
+                await syncEngine.enqueuePlayer(
                     gameID: gameID,
                     authorID: authorID,
                     reason: reason
@@ -1638,7 +1638,7 @@ final class AppServices {
         case .activeLease: reason = "readCursor(activeLease)"
         case .currentTime: reason = "readCursor(currentTime)"
         }
-        await syncEngine.enqueuePlayerRecord(
+        await syncEngine.enqueuePlayer(
             gameID: gameID,
             authorID: authorID,
             reason: reason

diff --git a/Crossmate/Services/PlayerNamePublisher.swift b/Crossmate/Services/PlayerNamePublisher.swift

@@ -14,7 +14,7 @@ final class PlayerNamePublisher {
     private let preferences: PlayerPreferences
     private let persistence: PersistenceController
     private let authorIdentity: AuthorIdentity
-    private let enqueuePlayerRecord: (UUID, String, String) async -> Void
+    private let enqueuePlayer: (UUID, String, String) async -> Void
 
     private var debounceTask: Task<Void, Never>?
     private var observationTask: Task<Void, Never>?
@@ -27,12 +27,12 @@ final class PlayerNamePublisher {
         preferences: PlayerPreferences,
         persistence: PersistenceController,
         authorIdentity: AuthorIdentity,
-        enqueuePlayerRecord: @escaping (UUID, String, String) async -> Void
+        enqueuePlayer: @escaping (UUID, String, String) async -> Void
     ) {
         self.preferences = preferences
         self.persistence = persistence
         self.authorIdentity = authorIdentity
-        self.enqueuePlayerRecord = enqueuePlayerRecord
+        self.enqueuePlayer = enqueuePlayer
         startObserving()
     }
 
@@ -89,7 +89,7 @@ final class PlayerNamePublisher {
             name: preferences.name
         ) else { return }
 
-        await enqueuePlayerRecord(gameID, authorID, "name-open")
+        await enqueuePlayer(gameID, authorID, "name-open")
     }
 
     private func fanOut(newName: String) async {
@@ -104,7 +104,7 @@ final class PlayerNamePublisher {
         )
 
         for gameID in touchedGameIDs {
-            await enqueuePlayerRecord(gameID, authorID, "name-rename")
+            await enqueuePlayer(gameID, authorID, "name-rename")
         }
 
         onFanOutForTesting?(newName)

diff --git a/Crossmate/Sync/PlayerSelectionPublisher.swift b/Crossmate/Sync/PlayerSelectionPublisher.swift

@@ -86,6 +86,20 @@ actor PlayerSelectionPublisher {
         await performFlush()
     }
 
+    /// Publishes `selection` synchronously, skipping the trailing-edge
+    /// debounce and discarding any pending debounce. Used by the
+    /// puzzle-open path so the initial cursor track ships in the same
+    /// CKSyncEngine drain as the read cursor and name-open enqueues
+    /// instead of arriving ~500 ms later.
+    func publishImmediately(_ selection: PlayerSelection) async {
+        guard gameID != nil, authorID != nil else { return }
+        if selection == lastPublished { return }
+        debounceTask?.cancel()
+        debounceTask = nil
+        pending = selection
+        await performFlush()
+    }
+
     private func scheduleDebounce() {
         debounceTask?.cancel()
         let interval = debounceInterval

diff --git a/Crossmate/Sync/SyncEngine.swift b/Crossmate/Sync/SyncEngine.swift

@@ -286,35 +286,45 @@ actor SyncEngine {
         Task.detached { [engine] in try? await engine.sendChanges() }
     }
 
-    /// Per-scope debounce slot for the coalesced Player-record drain.
-    /// Keyed by `GameEntity.databaseScope` (0 = private, 1 = shared).
-    private var playerSendDebounce: [Int16: Task<Void, Never>] = [:]
-    /// How long to wait after the first Player enqueue before firing
-    /// `sendChanges`. Sized to cover the full puzzle-open burst: read cursor
-    /// and name-open enqueue synchronously, then the cursor-track selection
-    /// arrives after PlayerSelectionPublisher's 500 ms debounce plus an
-    /// actor hop — measured at ~1 s end-to-end on device. 750 ms catches
-    /// the trailing selection in the same batch without perceptibly
-    /// deferring a true solo edit.
-    private static let playerSendCoalesceWindow: Duration = .milliseconds(750)
-
-    /// Coalescing variant of `sendChangesDetached` for the Player-record
-    /// path. The first enqueue in a window schedules a deferred drain;
-    /// subsequent enqueues for the same scope are absorbed into that same
-    /// drain (CKSyncEngine state dedupes repeated `.saveRecord` for the same
-    /// record ID, and one `sendChanges` ships them all in a single batch).
-    private func scheduleCoalescedPlayerSend(on engine: CKSyncEngine, scope: Int16) {
-        if playerSendDebounce[scope] != nil { return }
-        let window = Self.playerSendCoalesceWindow
-        playerSendDebounce[scope] = Task.detached { [engine, weak self] in
-            try? await Task.sleep(for: window)
-            await self?.clearPlayerSendDebounce(scope: scope)
-            try? await engine.sendChanges()
-        }
+    /// Per-scope burst depth. `enqueuePlayer` consults this — while
+    /// non-zero for a scope, it records that a drain is owed instead of
+    /// firing `sendChanges` immediately. The outermost frame issues one
+    /// `sendChanges` on exit if any enqueue landed during the burst.
+    /// Replaces an earlier time-window coalesce that had to be tuned to
+    /// match `PlayerSelectionPublisher`'s debounce: the open path now
+    /// explicitly fans out read cursor, name, and the initial selection
+    /// inside a burst, so the batch is bounded by the work that produces
+    /// it rather than by a wall-clock window.
+    private var playerSendBurstDepth: [Int16: Int] = [:]
+    private var playerSendBurstPending: Set<Int16> = []
+
+    /// Opens a Player-record send burst for `gameID`'s scope. Subsequent
+    /// `enqueuePlayer` calls on that scope skip their immediate
+    /// drain; the caller must pair this with `endPlayerSendBurst(scope:)`,
+    /// which fires one `sendChanges` if any enqueue landed in between.
+    /// Returns the scope so the caller can close the matching burst even
+    /// if the game's zone routing changes after the call.
+    func beginPlayerSendBurst(gameID: UUID) -> Int16? {
+        let ctx = persistence.container.newBackgroundContext()
+        guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return nil }
+        playerSendBurstDepth[info.scope, default: 0] += 1
+        return info.scope
     }
 
-    private func clearPlayerSendDebounce(scope: Int16) {
-        playerSendDebounce.removeValue(forKey: scope)
+    /// Closes a burst opened by `beginPlayerSendBurst`. The outermost
+    /// frame drains the affected engine if any enqueue landed during the
+    /// burst; nested frames just decrement the counter.
+    func endPlayerSendBurst(scope: Int16) {
+        guard let depth = playerSendBurstDepth[scope], depth > 0 else { return }
+        if depth > 1 {
+            playerSendBurstDepth[scope] = depth - 1
+            return
+        }
+        playerSendBurstDepth.removeValue(forKey: scope)
+        guard playerSendBurstPending.remove(scope) != nil else { return }
+        let engine = scope == 1 ? sharedEngine : privateEngine
+        guard let engine else { return }
+        sendChangesDetached(on: engine)
     }
 
     // MARK: - Outbound
@@ -688,11 +698,10 @@ actor SyncEngine {
     /// (game, authorID), so participants only ever write their own slot.
     /// `reason` is logged so the diagnostics view can attribute each enqueue
     /// to its caller (rename, read cursor, cursor track, …); it does not
-    /// affect routing. The outbound drain is coalesced via
-    /// `scheduleCoalescedPlayerSend` so several enqueues in the same tick
-    /// (puzzle-open fans out name + read cursor + cursor track in <1s) ship
-    /// as one batch instead of one round-trip per record.
-    func enqueuePlayerRecord(gameID: UUID, authorID: String, reason: String) async {
+    /// affect routing. Drains immediately unless a burst is open for this
+    /// scope (see `beginPlayerSendBurst`) — the open path uses a burst to
+    /// ship read cursor + name + initial selection in one round-trip.
+    func enqueuePlayer(gameID: UUID, authorID: String, reason: String) async {
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return }
         let engine = info.scope == 1 ? sharedEngine : privateEngine
@@ -701,7 +710,11 @@ actor SyncEngine {
         let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         await trace("enqueue Player[\(gameID.uuidString.prefix(8))] reason=\(reason)")
-        scheduleCoalescedPlayerSend(on: engine, scope: info.scope)
+        if (playerSendBurstDepth[info.scope] ?? 0) > 0 {
+            playerSendBurstPending.insert(info.scope)
+        } else {
+            sendChangesDetached(on: engine)
+        }
     }
 
     /// Registers a Game record as a pending send and ensures its zone is
@@ -772,6 +785,8 @@ actor SyncEngine {
         seenPingRecords = [:]
         liveQueryCheckpoints = [:]
         loggedFirstSharedPushPayload = false
+        playerSendBurstDepth = [:]
+        playerSendBurstPending = []
         _ = enqueueUnconfirmedMoves()
     }
 

diff --git a/Tests/Unit/PlayerNamePublisherTests.swift b/Tests/Unit/PlayerNamePublisherTests.swift

@@ -73,7 +73,7 @@ struct PlayerNamePublisherTests {
             preferences: preferences,
             persistence: persistence,
             authorIdentity: AuthorIdentity(testing: authorID),
-            enqueuePlayerRecord: { _, _, _ in }
+            enqueuePlayer: { _, _, _ in }
         )
     }
 
@@ -184,7 +184,7 @@ struct PlayerNamePublisherTests {
             preferences: prefs,
             persistence: p,
             authorIdentity: AuthorIdentity(testing: "_local"),
-            enqueuePlayerRecord: { gameID, _, _ in enqueued.append(gameID) }
+            enqueuePlayer: { gameID, _, _ in enqueued.append(gameID) }
         )
 
         await broadcaster.publishName(for: secondID)

diff --git a/Tests/Unit/Sync/ZoneOrphaningTests.swift b/Tests/Unit/Sync/ZoneOrphaningTests.swift

@@ -93,7 +93,7 @@ struct ZoneOrphaningTests {
         let (gameID, zoneName, owner) = try makeSharedGame(in: ctx)
         let engine = await makeEngine(persistence: persistence)
 
-        await engine.enqueuePlayerRecord(gameID: gameID, authorID: "_localAuthor", reason: "test")
+        await engine.enqueuePlayer(gameID: gameID, authorID: "_localAuthor", reason: "test")
         let beforeNames = await engine.pendingSaveRecordNames(scope: .shared)
         let playerRecordName = RecordSerializer.recordName(forPlayerInGame: gameID, authorID: "_localAuthor")
         #expect(beforeNames.contains(playerRecordName))