crossmate

PlayerSession.swift (15777B)

---

 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
     var selectedRow: Int {
         didSet { publishSelectionIfNeeded() }
     }
     var selectedCol: Int {
         didSet { publishSelectionIfNeeded() }
     }
     var direction: Puzzle.Direction = .across {
         didSet { publishSelectionIfNeeded() }
     }
     var isPencilMode: Bool = false
 
     /// Optional sink fired whenever the cursor moves. Wired to
     /// `PlayerSelectionPublisher` from the puzzle view so the local selection is
     /// debounced + pushed to CloudKit, and the peer can render the outline.
     /// Unset for solo (non-shared) games.
     var onSelectionChanged: ((PlayerSelection) -> Void)?
 
     /// Optional sink fired after local mutations that can fill or solve the
     /// puzzle. This keeps completion UI out of SwiftUI's render-time body
     /// evaluation path.
     @ObservationIgnored
     var onCompletionStateChanged: ((Game.CompletionState) -> Void)?
 
     /// Optional sink fired for collaborator-visible events (check, reveal, win)
     /// so the puzzle screen can enqueue a CloudKit ping for other participants.
     /// Set only for shared games with iCloud sync enabled; nil for solo games.
     @ObservationIgnored
     var onPlayerEvent: ((PingKind, PingScope?) -> Void)?
 
     /// Last completion state we fired a `.win` ping for. Tracked so the win
     /// ping fires once on the `.solved` transition and not on every keystroke
     /// after the puzzle is already solved.
     @ObservationIgnored
     private var lastWinCompletionState: Game.CompletionState?
 
     /// 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 }
 
     init(game: Game, mutator: GameMutator) {
         self.game = game
         self.mutator = mutator
         self.lastWinCompletionState = game.completionState
         let puzzle = game.puzzle
 
         // 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.
         if let first = puzzle.acrossClues.first,
            let cell = puzzle.cell(numbered: first.number) {
             self.selectedRow = cell.row
             self.selectedCol = cell.col
             self.direction = .across
         } else if let first = puzzle.downClues.first,
                   let cell = puzzle.cell(numbered: first.number) {
             self.selectedRow = cell.row
             self.selectedCol = cell.col
             self.direction = .down
         } else {
             self.selectedRow = 0
             self.selectedCol = 0
         }
     }
 
     // MARK: - Selection
 
     private func publishSelectionIfNeeded() {
         guard let onSelectionChanged else { return }
         onSelectionChanged(PlayerSelection(
             row: 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])
         onPlayerEvent?(.check, .square)
     }
 
     func checkCurrentWord() {
         mutator.checkCells(currentWordCells())
         onPlayerEvent?(.check, .word)
     }
 
     func checkPuzzle() {
         mutator.checkCells(puzzle.cells.flatMap { $0 })
         onPlayerEvent?(.check, .puzzle)
     }
 
     func revealSquare() {
         let cell = puzzle.cells[selectedRow][selectedCol]
         guard !cell.isBlock else { return }
         mutator.revealCells([cell])
         onPlayerEvent?(.reveal, .square)
         publishTerminalCompletionState()
     }
 
     func revealCurrentWord() {
         mutator.revealCells(currentWordCells())
         onPlayerEvent?(.reveal, .word)
         publishTerminalCompletionState()
     }
 
     func revealPuzzle() {
         mutator.revealCells(puzzle.cells.flatMap { $0 })
         onPlayerEvent?(.reveal, .puzzle)
         publishTerminalCompletionState()
     }
 
     func clearCurrentWord() {
         mutator.clearCells(currentWordCells())
     }
 
     func clearPuzzle() {
         mutator.clearCells(puzzle.cells.flatMap { $0 })
     }
 
     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)
         let completionState = game.completionState
         publishTerminalCompletionState(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)
     }
 
     // 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 = rebusBuffer
         let inputRow = selectedRow
         let inputCol = selectedCol
         isRebusActive = false
         rebusBuffer = ""
         mutator.setLetter(value, atRow: inputRow, atCol: inputCol, pencil: isPencilMode)
         let completionState = game.completionState
         publishTerminalCompletionState(completionState)
         if completionState != .solved {
             advance()
         }
     }
 
     // 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 publishTerminalCompletionState(_ state: Game.CompletionState? = nil) {
         let state = state ?? game.completionState
         guard state != .incomplete else { return }
         if state == .solved, lastWinCompletionState != .solved {
             onPlayerEvent?(.win, nil)
         }
         lastWinCompletionState = state
         onCompletionStateChanged?(state)
     }
 
     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
     }
 }