crossmate

PlayerSession.swift (23182B)

---

 import Foundation
 import Observation
 
 /// Local, per-player state for a single crossword game. Holds everything that
 /// belongs to one player and is *not* shared with the other side of a
 /// collaborative session: cursor position, current direction, pencil mode,
 /// and (eventually) chosen colour. All shared mutations are routed through
 /// the underlying `Game`.
 @MainActor
 @Observable
 final class PlayerSession {
     let game: Game
     let mutator: GameMutator
 
     /// Device-local store for this player's last cursor position, keyed by
     /// game. Restored on open and rewritten as the cursor moves so reopening a
     /// puzzle — even after a cold launch — returns to where they left off.
     /// `nil` for solo/test sessions that don't persist.
     @ObservationIgnored
     private let cursorStore: GameCursorStore?
 
     var selectedRow: Int {
         didSet { selectionDidChange() }
     }
     var selectedCol: Int {
         didSet { selectionDidChange() }
     }
     var direction: Puzzle.Direction = .across {
         didSet { selectionDidChange() }
     }
     var isPencilMode: Bool = false
 
     /// Optional sink fired whenever the selected answer slot changes. The
     /// local cursor reticle remains exact and local-only; the published value
     /// is the coarser cursor track persisted to CloudKit for collaborators.
     /// Unset for solo (non-shared) games.
     var onSelectionChanged: ((PlayerSelection) -> Void)? {
         didSet {
             if onSelectionChanged == nil {
                 lastPublishedCursorTrack = nil
             }
         }
     }
 
     @ObservationIgnored
     private var lastPublishedCursorTrack: PlayerSelection?
 
     /// The single completion signal the UI reacts to, carrying both *what*
     /// completion state the grid reached and *who* drove it there. Unlike
     /// `Game.completionState` — derived state that flips for local and remote
     /// edits alike — this is an event: repeated failed attempts on an
     /// already-full wrong grid still get a fresh sequence, and a local solve is
     /// distinguishable from a collaborator's. `PlayerSession` is the sole owner:
     /// local input emits `.local` inline, while a remote merge into the shared
     /// `Game` is reconciled into `.observed` (see `observeRemoteCompletion`). A
     /// single owner means the view has one handler and no ordering coupling.
     struct CompletionEvent: Equatable {
         let sequence: Int
         let state: Game.CompletionState
         let origin: Origin
 
         /// Who drove the grid to its completion state: this player's own input,
         /// or a merge of a collaborator's edits.
         enum Origin: Equatable {
             case local
             case observed
         }
     }
 
     var completionEvent: CompletionEvent?
 
     @ObservationIgnored
     private var completionEventSequence = 0
 
     /// Rebus mode lets the player type a multi-character value into a single
     /// cell (e.g. "STAR" or "♥"). While active, keyboard input accumulates in
     /// `rebusBuffer` rather than going straight to `Game.squares`; on commit
     /// the buffer is written to the cell and the cursor advances.
     var isRebusActive: Bool = false
     var rebusBuffer: String = ""
 
     var puzzle: Puzzle { game.puzzle }
 
     /// Cells a peer filled or cleared since this player last viewed the puzzle,
     /// each mapped to the author who wrote the change. Captured once on the
     /// open "arm" beat (see `PuzzleView`) and rendered as fading author-coloured
     /// borders by `GridView`; cleared on the player's first interaction, which
     /// is the acknowledgement. Empty outside that window.
     var recentChanges: [GridPosition: String] = [:]
 
     /// Fired when `recentChanges` is acknowledged (cleared) by an interaction,
     /// so the owner can advance this game's last-viewed timestamp. Unset for
     /// solo/test sessions.
     @ObservationIgnored
     var onRecentChangesAcknowledged: (() -> Void)?
 
     init(game: Game, mutator: GameMutator, cursorStore: GameCursorStore? = nil) {
         self.game = game
         self.mutator = mutator
         self.cursorStore = cursorStore
         let puzzle = game.puzzle
 
         // Default: start at the first across clue. Fall back to the first down
         // clue if the puzzle has no across answers, then to (0, 0) for a
         // degenerate puzzle with no clues at all.
         var startRow = 0
         var startCol = 0
         var startDirection: Puzzle.Direction = .across
         if let first = puzzle.acrossClues.first,
            let cell = puzzle.cell(numbered: first.number) {
             startRow = cell.row
             startCol = cell.col
             startDirection = .across
         } else if let first = puzzle.downClues.first,
                   let cell = puzzle.cell(numbered: first.number) {
             startRow = cell.row
             startCol = cell.col
             startDirection = .down
         }
 
         // Prefer this player's last position for the game when one was
         // persisted and still points at an editable cell. The grid never
         // changes for a given game, so a stored cursor stays valid; the
         // bounds/block check is purely defensive.
         if let saved = cursorStore?.cursor(forGame: mutator.gameID),
            saved.row >= 0, saved.row < puzzle.height,
            saved.col >= 0, saved.col < puzzle.width,
            !puzzle.cells[saved.row][saved.col].isBlock {
             startRow = saved.row
             startCol = saved.col
             startDirection = saved.direction
         }
 
         self.selectedRow = startRow
         self.selectedCol = startCol
         self.direction = startDirection
 
         // A non-block cell always belongs to at least one word; flip if the
         // restored direction has none so the cursor never lands directionless.
         if !hasWord(at: selectedRow, col: selectedCol, direction: direction),
            hasWord(at: selectedRow, col: selectedCol, direction: direction.opposite) {
             direction = direction.opposite
         }
 
         observeRemoteCompletion()
     }
 
     // MARK: - Selection
 
     private func selectionDidChange() {
         acknowledgeRecentChangesIfNeeded()
         publishCurrentSelection()
         cursorStore?.setCursor(
             .init(row: selectedRow, col: selectedCol, direction: direction),
             forGame: mutator.gameID
         )
     }
 
     /// Clears the "changed while you were away" borders on the first selection
     /// change after they were captured — moving the cursor or typing (which
     /// advances it) both route through here — and notifies the owner so the
     /// last-viewed timestamp advances. A no-op while `recentChanges` is empty.
     private func acknowledgeRecentChangesIfNeeded() {
         guard !recentChanges.isEmpty else { return }
         recentChanges = [:]
         onRecentChangesAcknowledged?()
     }
 
     func publishCurrentSelection() {
         guard let onSelectionChanged 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 {
             direction = direction.opposite
             if !hasWord(at: row, col: col, direction: direction) {
                 direction = direction.opposite
             }
         } else {
             selectedRow = row
             selectedCol = col
             if !hasWord(at: row, col: col, direction: direction) {
                 direction = direction.opposite
             }
         }
     }
 
     func togglePencil() {
         // TODO: when wired up, letters typed in pencil mode should be stored
         // as tentative entries (rendered in a lighter weight) until confirmed.
         isPencilMode.toggle()
     }
 
     func toggleDirection() {
         let next = direction.opposite
         if hasWord(at: selectedRow, col: selectedCol, direction: next) {
             direction = next
         }
     }
 
     func setDirection(_ newDirection: Puzzle.Direction) {
         guard newDirection != direction else { return }
         if hasWord(at: selectedRow, col: selectedCol, direction: newDirection) {
             direction = newDirection
         }
     }
 
     func selectClue(direction: Puzzle.Direction, number: Int) {
         guard let cell = puzzle.cell(numbered: number) else { return }
         self.direction = direction
         selectedRow = cell.row
         selectedCol = cell.col
     }
 
     // MARK: - Clue navigation
 
     func goToNextClue() {
         moveClue(by: +1)
     }
 
     func goToPreviousClue() {
         moveClue(by: -1)
     }
 
     func goToNextWord() {
         moveWord(by: +1)
     }
 
     func goToPreviousWord() {
         moveWord(by: -1)
     }
 
     func goToNextLetter() {
         advance()
     }
 
     func goToPreviousLetter() {
         retreat()
     }
 
     private func moveClue(by offset: Int) {
         // Walk every clue in order: all acrosses, then all downs. Stepping past
         // the last across rolls into the first down (and vice versa going
         // backwards), which matches how most crossword apps behave.
         let ordered = orderedClues()
         guard !ordered.isEmpty else { return }
 
         let currentNumber = currentClueNumber()
         let currentIndex = ordered.firstIndex {
             $0.0 == direction && $0.1.number == currentNumber
         } ?? 0
         let count = ordered.count
         let nextIndex = ((currentIndex + offset) % count + count) % count
 
         let (newDirection, newClue) = ordered[nextIndex]
         direction = newDirection
         moveToClueStart(number: newClue.number)
     }
 
     private func orderedClues() -> [(Puzzle.Direction, Puzzle.Clue)] {
         puzzle.acrossClues.map { (.across, $0) }
             + puzzle.downClues.map { (.down, $0) }
     }
 
     private func moveWord(by offset: Int) {
         let clues = direction == .across ? puzzle.acrossClues : puzzle.downClues
         guard !clues.isEmpty else { return }
         let currentNumber = currentClueNumber()
         let currentIndex = clues.firstIndex { $0.number == currentNumber } ?? 0
         let count = clues.count
         let nextIndex = ((currentIndex + offset) % count + count) % count
         moveToClueStart(number: clues[nextIndex].number)
     }
 
     // MARK: - Check / Reveal / Clear
     //
     // These translate the player's cursor into a set of cells (or the whole
     // puzzle) and ask `Game` to apply the operation. The actual marking lives
     // on `Game` because checks and reveals are shared state.
 
     func checkSquare() {
         let cell = puzzle.cells[selectedRow][selectedCol]
         guard !cell.isBlock else { return }
         mutator.checkCells([cell])
     }
 
     func checkCurrentWord() {
         mutator.checkCells(currentWordCells())
     }
 
     func checkPuzzle() {
         mutator.checkCells(puzzle.cells.flatMap { $0 })
     }
 
     func revealSquare() {
         let cell = puzzle.cells[selectedRow][selectedCol]
         guard !cell.isBlock else { return }
         mutator.revealCells([cell])
         publishLocalCompletion()
     }
 
     func revealCurrentWord() {
         mutator.revealCells(currentWordCells())
         publishLocalCompletion()
     }
 
     func revealPuzzle() {
         mutator.revealCells(puzzle.cells.flatMap { $0 })
         publishLocalCompletion()
     }
 
     func clearCurrentWord() {
         mutator.clearCells(currentWordCells())
     }
 
     func clearPuzzle() {
         mutator.clearCells(puzzle.cells.flatMap { $0 })
     }
 
     // MARK: - Undo / redo
 
     var canUndo: Bool { mutator.canUndo }
     var canRedo: Bool { mutator.canRedo }
 
     /// Undoes the most recent move and follows the cursor to the cell it
     /// touched, so reversing a typed letter lands back on that letter. A bulk
     /// clear returns no target, so the cursor stays where it is.
     func undo() {
         if let landing = mutator.undo() {
             placeCursor(atRow: landing.position.row, atCol: landing.position.col, preferring: landing.direction)
         }
     }
 
     func redo() {
         if let landing = mutator.redo() {
             placeCursor(atRow: landing.position.row, atCol: landing.position.col, preferring: landing.direction)
         }
     }
 
     /// Moves the cursor onto `(row, col)` without the same-cell direction flip
     /// `select(row:col:)` applies. When `preferred` is given and that direction
     /// has a word at the destination, the cursor adopts it — so undoing a letter
     /// restores the orientation it was typed in. Otherwise the current direction
     /// is kept, flipped only if it has no word here, so the cursor never lands
     /// directionless.
     private func placeCursor(atRow row: Int, atCol col: Int, preferring preferred: Puzzle.Direction? = nil) {
         guard isValid(row: row, col: col), !puzzle.cells[row][col].isBlock else { return }
         selectedRow = row
         selectedCol = col
         if let preferred, hasWord(at: row, col: col, direction: preferred) {
             direction = preferred
             return
         }
         if !hasWord(at: row, col: col, direction: direction),
            hasWord(at: row, col: col, direction: direction.opposite) {
             direction = direction.opposite
         }
     }
 
     private func currentClueNumber() -> Int? {
         let start = wordStart(row: selectedRow, col: selectedCol, direction: direction)
         return puzzle.cells[start.row][start.col].number
     }
 
     private func moveToClueStart(number: Int) {
         for r in 0..<puzzle.height {
             for c in 0..<puzzle.width where puzzle.cells[r][c].number == number {
                 selectedRow = r
                 selectedCol = c
                 return
             }
         }
     }
 
     private func moveToClueEnd(direction newDirection: Puzzle.Direction, number: Int) {
         guard let start = puzzle.cell(numbered: number) else { return }
         let (dr, dc) = step(for: newDirection)
         var row = start.row
         var col = start.col
         while isValid(row: row + dr, col: col + dc),
               !puzzle.cells[row + dr][col + dc].isBlock {
             row += dr
             col += dc
         }
         direction = newDirection
         selectedRow = row
         selectedCol = col
     }
 
     // MARK: - Input
 
     func enter(_ letter: String) {
         let inputRow = selectedRow
         let inputCol = selectedCol
         let cell = puzzle.cells[inputRow][inputCol]
         guard !cell.isBlock else { return }
         mutator.setLetter(letter, atRow: inputRow, atCol: inputCol, pencil: isPencilMode, direction: direction)
         let completionState = game.completionState
         publishLocalCompletion(completionState)
         if completionState != .solved {
             advance()
         }
     }
 
     func deleteBackward() {
         // If the cursor is on an empty cell or a revealed (locked) cell,
         // retreat first — revealed cells can't be cleared in place, so delete
         // tunnels past them to the previous editable cell. `clearLetter`
         // itself no-ops on revealed cells, so calling it unconditionally
         // after retreat is safe.
         let currentMark = game.squares[selectedRow][selectedCol].mark
         let currentEmpty = game.squares[selectedRow][selectedCol].entry.isEmpty
         if currentEmpty || currentMark.isRevealed {
             retreat()
         }
         mutator.clearLetter(atRow: selectedRow, atCol: selectedCol, direction: direction)
     }
 
     // MARK: - Rebus
 
     func startRebus() {
         let cell = puzzle.cells[selectedRow][selectedCol]
         guard !cell.isBlock else { return }
         rebusBuffer = game.squares[selectedRow][selectedCol].entry
         isRebusActive = true
     }
 
     func appendRebusLetter(_ letter: String) {
         rebusBuffer += letter.uppercased()
     }
 
     func deleteRebusLetter() {
         guard !rebusBuffer.isEmpty else { return }
         rebusBuffer.removeLast()
     }
 
     func commitRebus() {
         let value = committedRebusValue(from: rebusBuffer)
         let inputRow = selectedRow
         let inputCol = selectedCol
         isRebusActive = false
         rebusBuffer = ""
         mutator.setLetter(value, atRow: inputRow, atCol: inputCol, pencil: isPencilMode, direction: direction)
         let completionState = game.completionState
         publishLocalCompletion(completionState)
         if completionState != .solved {
             advance()
         }
     }
 
     private func committedRebusValue(from buffer: String) -> String {
         guard buffer.rangeOfCharacter(from: CharacterSet.whitespacesAndNewlines.inverted) != nil else {
             return buffer
         }
         return buffer.trimmingCharacters(in: .whitespacesAndNewlines)
     }
 
     // MARK: - Word geometry
 
     func isInCurrentWord(row: Int, col: Int) -> Bool {
         currentWordCells().contains(where: { $0.row == row && $0.col == col })
     }
 
     func currentClue() -> Puzzle.Clue? {
         let start = wordStart(row: selectedRow, col: selectedCol, direction: direction)
         guard let number = puzzle.cells[start.row][start.col].number else { return nil }
         let clues = direction == .across ? puzzle.acrossClues : puzzle.downClues
         return clues.first { $0.number == number }
     }
 
     private func currentWordCells() -> [Puzzle.Cell] {
         let (dr, dc) = step(for: direction)
         let start = wordStart(row: selectedRow, col: selectedCol, direction: direction)
         var cells: [Puzzle.Cell] = []
         var r = start.row
         var c = start.col
         while isValid(row: r, col: c) && !puzzle.cells[r][c].isBlock {
             cells.append(puzzle.cells[r][c])
             r += dr
             c += dc
         }
         return cells
     }
 
     private func wordStart(row: Int, col: Int, direction: Puzzle.Direction) -> (row: Int, col: Int) {
         let (dr, dc) = step(for: direction)
         var r = row
         var c = col
         while isValid(row: r - dr, col: c - dc) && !puzzle.cells[r - dr][c - dc].isBlock {
             r -= dr
             c -= dc
         }
         return (r, c)
     }
 
     private func hasWord(at row: Int, col: Int, direction: Puzzle.Direction) -> Bool {
         let (dr, dc) = step(for: direction)
         let hasNext = isValid(row: row + dr, col: col + dc)
             && !puzzle.cells[row + dr][col + dc].isBlock
         let hasPrev = isValid(row: row - dr, col: col - dc)
             && !puzzle.cells[row - dr][col - dc].isBlock
         return hasNext || hasPrev
     }
 
     private func step(for direction: Puzzle.Direction) -> (Int, Int) {
         direction == .across ? (0, 1) : (1, 0)
     }
 
     private func publishLocalCompletion(_ state: Game.CompletionState? = nil) {
         let state = state ?? game.completionState
         guard state != .incomplete else { return }
         emitCompletion(state, origin: .local)
     }
 
     private func emitCompletion(_ state: Game.CompletionState, origin: CompletionEvent.Origin) {
         completionEventSequence += 1
         completionEvent = CompletionEvent(
             sequence: completionEventSequence,
             state: state,
             origin: origin
         )
     }
 
     /// Watches the shared `Game`'s completion state for a transition this
     /// player didn't drive — a collaborator's merged edits completing the grid
     /// — and reconciles it into a single `.observed` completion event. Armed
     /// once at the end of `init` (so the game's already-restored initial state
     /// never fires) and re-armed after every change, since
     /// `withObservationTracking` is one-shot. Only a remote *solve* surfaces: a
     /// collaborator's wrong fill must not interrupt the local solver, and a
     /// solve the local input path already announced is not re-emitted.
     private func observeRemoteCompletion() {
         withObservationTracking {
             _ = game.completionState
         } onChange: { [weak self] in
             // `onChange` fires synchronously at willSet, before the new value is
             // readable; hop to the main actor to read the settled state and re-arm.
             Task { @MainActor [weak self] in
                 guard let self else { return }
                 self.reconcileRemoteCompletion()
                 self.observeRemoteCompletion()
             }
         }
     }
 
     private func reconcileRemoteCompletion() {
         let state = game.completionState
         guard state == .solved else { return }
         guard completionEvent?.state != .solved else { return }
         emitCompletion(state, origin: .observed)
     }
 
     private func advance() {
         let (dr, dc) = step(for: direction)
         let r = selectedRow + dr
         let c = selectedCol + dc
         // If we're still inside the current word, step one cell. Otherwise
         // we've hit the end of the word, so jump to the next clue in the full
         // clue list. Without that, we'd fall through the block into a different
         // word in the same row/column — which for down clues is almost never
         // the next clue by number.
         if isValid(row: r, col: c) && !puzzle.cells[r][c].isBlock {
             selectedRow = r
             selectedCol = c
         } else {
             advanceToNextClue()
         }
     }
 
     private func advanceToNextClue() {
         moveClue(by: +1)
     }
 
     private func retreat() {
         let start = wordStart(row: selectedRow, col: selectedCol, direction: direction)
         if selectedRow == start.row && selectedCol == start.col {
             retreatToPreviousClueEnd()
             return
         }
 
         let (dr, dc) = step(for: direction)
         var r = selectedRow - dr
         var c = selectedCol - dc
         while isValid(row: r, col: c) && puzzle.cells[r][c].isBlock {
             r -= dr
             c -= dc
         }
         if isValid(row: r, col: c) {
             selectedRow = r
             selectedCol = c
         }
     }
 
     private func retreatToPreviousClueEnd() {
         let ordered = orderedClues()
         guard !ordered.isEmpty else { return }
 
         let currentNumber = currentClueNumber()
         let currentIndex = ordered.firstIndex {
             $0.0 == direction && $0.1.number == currentNumber
         } ?? 0
         let previousIndex = ((currentIndex - 1) % ordered.count + ordered.count) % ordered.count
         let (newDirection, newClue) = ordered[previousIndex]
         moveToClueEnd(direction: newDirection, number: newClue.number)
     }
 
     private func isValid(row: Int, col: Int) -> Bool {
         row >= 0 && row < puzzle.height && col >= 0 && col < puzzle.width
     }
 }