crossmate

GridView.swift (40632B)

---

 import SwiftUI
 
 struct GridView: View {
     @Bindable var session: PlayerSession
     let roster: PlayerRoster
     /// Owns the reveal confirmation alert (presented by `PuzzleView`); the
     /// grid's VoiceOver Reveal Square action requests through it so a reveal
     /// is never applied without the standard confirmation.
     let revealConfirmation: RevealConfirmation
     let showsSharedAnnotations: Bool
     /// Whether to render peers' live cursor tracks. Off for a solved puzzle —
     /// the game is no longer a live session, so the other player's cursor is
     /// dropped while author tints stay to colour the finished grid.
     var showsPeerCursors: Bool = true
     /// The finish-banner replay frame to render. When non-nil (the user has
     /// scrubbed back from the end), the grid renders this reconstructed history
     /// instead of the live `Game`: each touched cell shows its after-state,
     /// blanks elsewhere. Live selection, word highlight, and taps are
     /// suppressed, and the playhead cell is tinted in the acting author's
     /// colour. `nil` (the default, or a scrubber at rest) leaves normal play.
     var replayFrame: ReplayFrame? = nil
 
     private let spacing: CGFloat = 1
 
     /// The grid container's resolved size, captured so the single tap recogniser
     /// can map a tap location back to a cell via `PuzzleGridGeometry`.
     @State private var gridSize: CGSize = .zero
 
     /// Decoded `data=` decoration tiles, keyed by payload. Resolved once per
     /// puzzle rather than in `body`, which re-runs on every keystroke.
     @State private var decorationImages: [String: Image] = [:]
 
     var body: some View {
         let width = session.puzzle.width
         let height = session.puzzle.height
         let replayCells = replayFrame?.cells
         let isReplaying = replayFrame != nil
         let replayCursor = replayFrame?.cursor
         // Once the puzzle is solved, rebus squares show their canonical fill
         // (e.g. a Schrödinger square reads "MTWA" rather than the "WA" the
         // solver typed for the down answer). Purely a render-time substitution
         // — the stored entry, its authorship, and marks are left untouched.
         let showsCanonicalRebus = !isReplaying && session.game.completionState == .solved
         // Peer cursor tints are rendered in a separate Canvas layer (see
         // `RemoteCursorTints`) so this 441-cell grid no longer re-evaluates on
         // every peer cursor move — only on local selection and letter changes.
         let showsRemoteTints = showsSharedAnnotations && showsPeerCursors && !isReplaying
         // Author colours are shown for shared live play and for any replay
         // (the rewind reads as coloured per author, matching the scoreboard).
         let authorTintByID: [String: Color] = (showsSharedAnnotations || isReplaying)
             ? Dictionary(
                 roster.entries.map { ($0.authorID, $0.color.tint) },
                 uniquingKeysWith: { first, _ in first }
             )
             : [:]
         // Colour for the replay playhead: the acting author's selection fill,
         // so a rewound move reads in that player's colour (the local fill for
         // our own moves). `nil` outside replay leaves the local cursor as-is.
         let playheadTint: Color? = replayFrame?.cursorAuthorID
             .flatMap { id in roster.entries.first { $0.authorID == id } }
             .map { $0.color.selectionFill }
         let patternPalette = CrossRefPattern.allCases
         let cellGroups = session.puzzle.cellGroups
         // Flatten the grid to a plain draw model read here in `body` (so it
         // tracks the observable game state), then hand it to a single `Canvas`
         // that paints all cell content in one pass — replacing the former
         // 441-view `ForEach`, which dominated first-render cost. Block cells
         // carry no content; they're skipped at draw time but kept in the array
         // so indices map directly to positions.
         let cellModel: [CellDraw] = (0..<(width * height)).map { index in
             let r = index / width
             let c = index % width
             let cell = session.puzzle.cells[r][c]
             let visibleDecorations = session.puzzle.decorations[GridPosition(row: r, col: c)]?
                 .filter { $0.isVisible(solved: showsCanonicalRebus) } ?? []
             guard !cell.isBlock else {
                 return CellDraw(row: r, col: c, isBlock: true, special: nil,
                                 crossRef: nil, entry: "", isPencil: false,
                                 triangle: nil, authorTint: nil,
                                 decorations: visibleDecorations)
             }
             let pos = GridPosition(row: r, col: c)
             let square = session.game.squares[r][c]
             // During replay the cell's letter/mark/author come from the
             // reconstructed history, not the live square.
             let replayCell = replayCells?[pos]
             let entry = isReplaying ? (replayCell?.letter ?? "") : square.entry
             let displayEntry = canonicalRebusFill(for: cell, when: showsCanonicalRebus) ?? entry
             let mark = isReplaying ? (replayCell?.mark ?? .none) : square.mark
             let letterAuthorID = isReplaying ? replayCell?.cellAuthorID : square.letterAuthorID
             let triangle: TriangleKind? = mark.isRevealed
                 ? .revealed
                 : (mark.isCheckedWrong ? .wrong : nil)
             return CellDraw(
                 row: r,
                 col: c,
                 isBlock: false,
                 special: cell.special,
                 crossRef: cellGroups[pos].map { patternPalette[$0 % patternPalette.count] },
                 entry: displayEntry,
                 isPencil: mark.isPencil,
                 triangle: triangle,
                 authorTint: entry.isEmpty ? nil : letterAuthorID.flatMap { authorTintByID[$0] },
                 decorations: visibleDecorations
             )
         }
         // Layered back to front: black (shows through the inter-cell gaps and
         // behind blocks) -> white cell backdrop -> author tints -> peer cursor
         // tints -> local cursor tints -> cells. Keep these as siblings in one
         // layout so iPad-sized proposals cannot give the backing Canvases a
         // different drawing rect than the cells. The cursor layers each read
         // their own selection state in their own body, so a cursor move
         // repaints only a lightweight Canvas and never invalidates the cell
         // `ForEach`. Author tints sit below the local cursor so the focused
         // square's opaque fill can mask the tint (see `LocalCursorTints`).
         PuzzleGridLayerLayout(columns: width, rows: height, spacing: spacing) {
             GridBackdrop(puzzle: session.puzzle, spacing: spacing)
             AuthorTintsLayer(cells: cellModel, columns: width, rows: height, spacing: spacing)
             if showsRemoteTints {
                 RemoteCursorTints(roster: roster, puzzle: session.puzzle, spacing: spacing)
             }
             LocalCursorTints(
                 session: session,
                 spacing: spacing,
                 isReplaying: isReplaying,
                 replayCursor: replayCursor,
                 replayPlayheadTint: playheadTint
             )
             if !isReplaying {
                 RecentChangeBorders(session: session, roster: roster, spacing: spacing)
             }
             PuzzleCellsLayer(
                 cells: cellModel,
                 columns: width,
                 rows: height,
                 spacing: spacing,
                 decorationImages: decorationImages
             )
         }
         // One tap recogniser for the whole grid instead of 441 per-cell ones:
         // with uniform cells the tapped cell is pure arithmetic on the tap
         // location (see `PuzzleGridGeometry.cell(at:)`). `select` already guards
         // blocks and out-of-range, so any in-grid tap is safe to forward.
         .contentShape(Rectangle())
         .onTapGesture(coordinateSpace: .local) { location in
             guard !isReplaying, gridSize != .zero else { return }
             let geometry = PuzzleGridGeometry(
                 size: gridSize, columns: width, rows: height, spacing: spacing
             )
             if let (r, c) = geometry.cell(at: location) {
                 session.select(row: r, col: c)
             }
         }
         .onGeometryChange(for: CGSize.self) { $0.size } action: { gridSize = $0 }
         // Decode once per puzzle. Keyed on the game so switching puzzles inside
         // one grid view re-resolves rather than drawing the previous puzzle's
         // tiles; a puzzle with no `data=` decorations resolves to an empty map
         // and costs a single dictionary walk.
         .task(id: session.mutator.gameID) {
             decorationImages = DecorationImages.decode(session.puzzle.decorations)
         }
         // Synthetic VoiceOver elements over the Canvas layers; built only
         // while VoiceOver is running (see GridAccessibility.swift).
         .puzzleGridAccessibility(
             session: session,
             roster: roster,
             revealConfirmation: revealConfirmation,
             showsSharedAnnotations: showsSharedAnnotations,
             isReplaying: isReplaying,
             gridSize: gridSize,
             spacing: spacing
         )
     }
 
     /// The canonical fill to display for a rebus square on a solved puzzle, or
     /// `nil` to fall back to the stored entry. Only multi-character solutions
     /// (rebus/Schrödinger squares) differ from what the solver typed; ordinary
     /// single-letter cells return `nil` and render their entry unchanged.
     private func canonicalRebusFill(for cell: Puzzle.Cell, when isSolved: Bool) -> String? {
         guard isSolved, let solution = cell.solution, solution.count > 1 else { return nil }
         return solution
     }
 
 }
 
 // MARK: - Cell content
 
 /// Which corner-triangle marker a cell carries, if any. Mirrors the former
 /// `CellView.cornerTriangleColor`: revealed cells are yellow, checked-wrong red.
 private enum TriangleKind {
     case revealed
     case wrong
 }
 
 /// A flat, value-type snapshot of everything one cell draws. Built in
 /// `GridView.body` (so it tracks observable state) and rendered by
 /// `PuzzleCellsLayer`. Replaces the per-cell `CellView`.
 private struct CellDraw {
     let row: Int
     let col: Int
     let isBlock: Bool
     let special: Puzzle.Special?
     let crossRef: CrossRefPattern?
     let entry: String
     let isPencil: Bool
     let triangle: TriangleKind?
     /// The author's base tint, if this cell carries an entry in a shared game.
     /// `PlayerColor.authorTintOpacity` is applied at draw time (in
     /// `AuthorTintsLayer`, not `PuzzleCellsLayer`), matching the former
     /// `CellView` background.
     let authorTint: Color?
     /// Decoration layers currently visible on this cell, in paint order. Already
     /// filtered by phase, so the draw path never has to know whether the puzzle
     /// is solved. Unlike every other field here this is also populated for
     /// blocks, which is the whole point — an after-solve reveal routinely lands
     /// on black squares.
     let decorations: [Puzzle.Decoration]
 }
 
 /// The faint author-attribution washes, split out of `PuzzleCellsLayer` so they
 /// can sit *below* the cursor tints: `LocalCursorTints` paints the focused
 /// square opaquely, masking the author tint on that one cell so the cursor
 /// keeps a single fixed colour whether or not the square is filled. Reads the
 /// same `CellDraw` model as the cells layer, so it repaints on letter changes
 /// and never on cursor moves.
 private struct AuthorTintsLayer: View {
     let cells: [CellDraw]
     let columns: Int
     let rows: Int
     let spacing: CGFloat
 
     var body: some View {
         Canvas { context, size in
             let geometry = PuzzleGridGeometry(
                 size: size, columns: columns, rows: rows, spacing: spacing
             )
             guard geometry.cellSize > 0 else { return }
             for cell in cells {
                 guard let tint = cell.authorTint else { continue }
                 context.fill(
                     Path(geometry.cellRect(row: cell.row, col: cell.col)),
                     with: .color(tint.opacity(PlayerColor.authorTintOpacity))
                 )
             }
         }
         .allowsHitTesting(false)
     }
 }
 
 /// Draws all cell content (shaded/circled specials, cross-ref hatching,
 /// letters, corner triangles) in a single `Canvas`. This is the layer that
 /// previously cost ~441 SwiftUI view subtrees on first render; as one
 /// immediate-mode draw pass it builds in roughly constant time. Z-order within
 /// each cell matches the former `CellView`: shaded → cross-ref → circle →
 /// letter → corner triangle. Author tints are the exception — they render in
 /// `AuthorTintsLayer` beneath the cursor layers so the focused square's opaque
 /// selection fill can mask them.
 private struct PuzzleCellsLayer: View {
     let cells: [CellDraw]
     let columns: Int
     let rows: Int
     let spacing: CGFloat
     /// Decoded `data=` tiles, keyed by payload (see `DecorationImages`).
     var decorationImages: [String: Image] = [:]
     @Environment(\.colorScheme) private var colorScheme
 
     /// Base size before the per-cell fit-scale; mirrors the former
     /// `CellView` letter font (`.system(size: 34, weight: .semibold,
     /// design: .rounded)`).
     private let baseFontSize: CGFloat = 34
 
     var body: some View {
         Canvas { context, size in
             let geometry = PuzzleGridGeometry(
                 size: size, columns: columns, rows: rows, spacing: spacing
             )
             guard geometry.cellSize > 0 else { return }
 
             // Resolved letters are cached per (entry, pencil) for this draw: a
             // full grid has ~26 distinct glyphs, so almost every cell is a hit
             // and `resolve`/`measure` runs a couple of dozen times, not 441.
             var glyphCache: [String: (text: GraphicsContext.ResolvedText, size: CGSize)] = [:]
             var decorationTextCache:
                 [String: (text: GraphicsContext.ResolvedText, size: CGSize)] = [:]
             // Resolved tiles are cached for this draw the same way glyphs are:
             // a grid art puzzle repeats a handful of motifs across many cells.
             var imageCache: [String: GraphicsContext.ResolvedImage] = [:]
 
             // Decorations run over every cell, blocks included — an after-solve
             // reveal routinely lands on black squares, which the content loop
             // below skips entirely.
             for cell in cells where !cell.decorations.isEmpty {
                 drawDecorations(
                     cell,
                     in: geometry.cellRect(row: cell.row, col: cell.col),
                     textCache: &decorationTextCache,
                     cache: &imageCache,
                     context: context
                 )
             }
 
             for cell in cells where !cell.isBlock {
                 let rect = geometry.cellRect(row: cell.row, col: cell.col)
 
                 if cell.special == .shaded {
                     context.fill(Path(rect), with: .color(.black.opacity(0.22)))
                 }
                 if let crossRef = cell.crossRef {
                     drawCrossRef(crossRef, in: rect, row: cell.row, col: cell.col, context: context)
                 }
                 if cell.special == .circled {
                     context.stroke(
                         Path(ellipseIn: rect.insetBy(dx: 1.5, dy: 1.5)),
                         with: .color(.black.opacity(0.55)),
                         lineWidth: 1
                     )
                 }
                 if !cell.entry.isEmpty {
                     drawLetter(cell, in: rect, cache: &glyphCache, context: context)
                 }
                 if let triangle = cell.triangle {
                     let side = min(rect.width, rect.height) * 0.3
                     var path = Path()
                     path.move(to: CGPoint(x: rect.maxX - side, y: rect.minY))
                     path.addLine(to: CGPoint(x: rect.maxX, y: rect.minY))
                     path.addLine(to: CGPoint(x: rect.maxX, y: rect.minY + side))
                     path.closeSubpath()
                     context.fill(path, with: .color(triangle == .revealed ? .yellow : .red))
                 }
             }
         }
     }
 
     /// Paints a cell's decoration layers in definition order — the format's
     /// stacking rule is that a repeated design character's lines paint in the
     /// order they were written.
     ///
     /// Two kinds are deliberately not drawn here. A `before`-phase `mark` is
     /// already folded into `Cell.special` by `Puzzle.init`, so drawing it again
     /// would double-stroke every circle; only an `after` mark needs handling.
     /// And `fg-*` colours belong to the entry glyph, so they're applied in
     /// `drawLetter` rather than as a layer of their own.
     private func drawDecorations(
         _ cell: CellDraw,
         in rect: CGRect,
         textCache: inout [String: (text: GraphicsContext.ResolvedText, size: CGSize)],
         cache: inout [String: GraphicsContext.ResolvedImage],
         context: GraphicsContext
     ) {
         for decoration in cell.decorations {
             switch decoration.content {
             case .mark(let special) where decoration.phase == .after:
                 switch special {
                 case .shaded:
                     context.fill(Path(rect), with: .color(.black.opacity(0.22)))
                 case .circled:
                     context.stroke(
                         Path(ellipseIn: rect.insetBy(dx: 1.5, dy: 1.5)),
                         with: .color(.black.opacity(0.55)),
                         lineWidth: 1
                     )
                 }
             case .mark:
                 continue
             case .color(.background, let light, let dark):
                 guard let color = Puzzle.Decoration.Content.color(
                     light: light, dark: dark, for: colorScheme
                 ) else {
                     continue
                 }
                 context.fill(Path(rect), with: .color(color))
             case .color:
                 continue
             case .text(let value):
                 let key = "\(value)|\(cell.isBlock)"
                 let resolved: GraphicsContext.ResolvedText
                 let natural: CGSize
                 if let hit = textCache[key] {
                     resolved = hit.text
                     natural = hit.size
                 } else {
                     let text = context.resolve(
                         Text(value)
                             .font(
                                 .system(
                                     size: baseFontSize * 0.8,
                                     weight: .semibold,
                                     design: .rounded
                                 )
                             )
                             .foregroundStyle(cell.isBlock ? Color.white : Color.black)
                     )
                     let measured = text.measure(
                         in: CGSize(width: CGFloat.infinity, height: CGFloat.infinity)
                     )
                     textCache[key] = (text, measured)
                     resolved = text
                     natural = measured
                 }
                 guard natural.width > 0, natural.height > 0 else { continue }
                 let availableWidth = rect.width - 4
                 let scale = min(1, availableWidth / natural.width, rect.height / natural.height)
                 context.drawLayer { layer in
                     layer.translateBy(x: rect.midX, y: rect.midY)
                     layer.scaleBy(x: scale, y: scale)
                     layer.draw(resolved, at: .zero, anchor: .center)
                 }
             case .data(_, _, let payload):
                 guard let image = decorationImages[payload] else { continue }
                 let resolved: GraphicsContext.ResolvedImage
                 if let hit = cache[payload] {
                     resolved = hit
                 } else {
                     resolved = context.resolve(image)
                     cache[payload] = resolved
                 }
                 context.draw(resolved, in: rect)
             }
         }
     }
 
     /// The entry colour override from an `fg-*` decoration, if one applies.
     private func foregroundOverride(for cell: CellDraw) -> Color? {
         for decoration in cell.decorations {
             guard case .color(.foreground, let light, let dark) = decoration.content,
                   let color = Puzzle.Decoration.Content.color(
                       light: light, dark: dark, for: colorScheme
                   ) else {
                 continue
             }
             return color
         }
         return nil
     }
 
     /// Draws one entry centred in its cell, scaled down to fit exactly as the
     /// former `.minimumScaleFactor(0.1)` did: the largest size ≤ base that fits
     /// the cell minus the 2pt horizontal padding. Single letters never scale (a
     /// 4-char rebus does), and the per-cell scale is pure arithmetic on one
     /// cached measurement.
     private func drawLetter(
         _ cell: CellDraw,
         in rect: CGRect,
         cache: inout [String: (text: GraphicsContext.ResolvedText, size: CGSize)],
         context: GraphicsContext
     ) {
         let foreground = foregroundOverride(for: cell)
         // The colour joins the cache key: two cells can share an entry and
         // differ only in an `fg-*` decoration, and caching on the entry alone
         // would paint the second in the first one's colour.
         let key = "\(cell.entry)|\(cell.isPencil)|\(foreground.map(String.init(describing:)) ?? "")"
         let resolved: GraphicsContext.ResolvedText
         let natural: CGSize
         if let hit = cache[key] {
             resolved = hit.text
             natural = hit.size
         } else {
             let color: Color = foreground ?? (cell.isPencil ? .black.opacity(0.5) : .black)
             let text = context.resolve(
                 Text(cell.entry)
                     .font(.system(size: baseFontSize, weight: .semibold, design: .rounded))
                     .foregroundStyle(color)
             )
             let measured = text.measure(in: CGSize(width: CGFloat.infinity, height: CGFloat.infinity))
             cache[key] = (text, measured)
             resolved = text
             natural = measured
         }
         guard natural.width > 0, natural.height > 0 else { return }
         let availableWidth = rect.width - 4  // matches .padding(.horizontal, 2)
         let scale = min(1, availableWidth / natural.width, rect.height / natural.height)
         context.drawLayer { layer in
             layer.translateBy(x: rect.midX, y: rect.midY)
             layer.scaleBy(x: scale, y: scale)
             layer.draw(resolved, at: .zero, anchor: .center)
         }
     }
 
     /// Strokes the passive cross-reference hatching for one cell, reusing the
     /// `CrossRefLines` lattice so lines stay continuous across cell borders.
     /// The path is generated in cell-local space, then clipped to the cell and
     /// translated into place.
     private func drawCrossRef(
         _ pattern: CrossRefPattern,
         in rect: CGRect,
         row: Int,
         col: Int,
         context: GraphicsContext
     ) {
         let ink = Color.black.opacity(0.20)
         let localRect = CGRect(x: 0, y: 0, width: rect.width, height: rect.height)
         func stroke(_ slope: CrossRefLines.Slope) {
             let path = CrossRefLines(slope: slope, row: row, col: col, spacing: spacing)
                 .path(in: localRect)
             var layer = context
             layer.clip(to: Path(rect))
             layer.translateBy(x: rect.minX, y: rect.minY)
             layer.stroke(path, with: .color(ink), lineWidth: 1)
         }
         switch pattern {
         case .diagonalDown: stroke(.down)
         case .diagonalUp: stroke(.up)
         case .crosshatch: stroke(.down); stroke(.up)
         case .horizontal: stroke(.horizontal)
         case .vertical: stroke(.vertical)
         }
     }
 }
 
 // MARK: - Layout
 
 private enum PuzzleGridMetrics {
     static func cellSize(
         for proposal: ProposedViewSize,
         columns: Int,
         rows: Int,
         spacing: CGFloat
     ) -> CGFloat {
         cellSize(
             availableWidth: proposal.width,
             availableHeight: proposal.height,
             columns: columns,
             rows: rows,
             spacing: spacing
         )
     }
 
     static func cellSize(
         availableWidth: CGFloat?,
         availableHeight: CGFloat?,
         columns: Int,
         rows: Int,
         spacing: CGFloat
     ) -> CGFloat {
         let cols = CGFloat(columns)
         let rs = CGFloat(rows)
         let width = availableWidth ?? .infinity
         let height = availableHeight ?? .infinity
         let widthBased = width.isFinite
             ? (width - spacing * (cols + 1)) / cols
             : .infinity
         let heightBased = height.isFinite
             ? (height - spacing * (rs + 1)) / rs
             : .infinity
         return max(0, min(widthBased, heightBased))
     }
 }
 
 /// Stacks the grid's backing layers and cell layout into one measured surface.
 /// Using `.background` for the Canvases can let SwiftUI hand those layers a
 /// different size from the custom cell layout on iPad, which makes their
 /// derived rects drift. This layout makes the Canvases draw from the same
 /// surface size and places the cell grid at the exact rect derived from it.
 private struct PuzzleGridLayerLayout: Layout {
     let columns: Int
     let rows: Int
     let spacing: CGFloat
 
     func sizeThatFits(
         proposal: ProposedViewSize,
         subviews: Subviews,
         cache: inout ()
     ) -> CGSize {
         let cellSize = PuzzleGridMetrics.cellSize(
             for: proposal,
             columns: columns,
             rows: rows,
             spacing: spacing
         )
         let width = cellSize * CGFloat(columns) + spacing * CGFloat(columns + 1)
         let height = cellSize * CGFloat(rows) + spacing * CGFloat(rows + 1)
         return CGSize(width: width, height: height)
     }
 
     func placeSubviews(
         in bounds: CGRect,
         proposal: ProposedViewSize,
         subviews: Subviews,
         cache: inout ()
     ) {
         guard let cellGrid = subviews.last else { return }
         let geometry = PuzzleGridGeometry(
             size: bounds.size,
             columns: columns,
             rows: rows,
             spacing: spacing
         )
         let layerProposal = ProposedViewSize(width: bounds.width, height: bounds.height)
         for subview in subviews.dropLast() {
             subview.place(
                 at: CGPoint(x: bounds.minX, y: bounds.minY),
                 anchor: .topLeading,
                 proposal: layerProposal
             )
         }
         // The view builder must emit backing layers first and the cell grid
         // last; the cell grid is the only subview placed on the tight grid rect.
         let cellGridRect = geometry.gridRect.offsetBy(dx: bounds.minX, dy: bounds.minY)
         cellGrid.place(
             at: cellGridRect.origin,
             anchor: .topLeading,
             proposal: ProposedViewSize(width: cellGridRect.width, height: cellGridRect.height)
         )
     }
 }
 
 /// Shared cell geometry for the puzzle grid: given a container `size`, computes
 /// the uniform cell size (via `PuzzleGridMetrics`) and the centred origin, then
 /// hands back the frame of any `(row, col)`. `PuzzleCellsLayer` and the backing
 /// `Canvas` layers (`GridBackdrop`, `RemoteCursorTints`, `LocalCursorTints`) all
 /// derive their cell rects from this, so every layer stays pixel-aligned; it
 /// also inverts the mapping (`cell(at:)`) for the grid's single tap recogniser.
 /// Internal (not private) so `GridAccessibility` can frame its synthetic
 /// VoiceOver elements on the same lattice.
 struct PuzzleGridGeometry {
     let cellSize: CGFloat
     let spacing: CGFloat
     let gridSize: CGSize
     private let columns: Int
     private let rows: Int
     private let originX: CGFloat
     private let originY: CGFloat
 
     init(size: CGSize, columns: Int, rows: Int, spacing: CGFloat) {
         let cellSize = PuzzleGridMetrics.cellSize(
             for: ProposedViewSize(width: size.width, height: size.height),
             columns: columns,
             rows: rows,
             spacing: spacing
         )
         let gridWidth = cellSize * CGFloat(columns) + spacing * CGFloat(columns + 1)
         let gridHeight = cellSize * CGFloat(rows) + spacing * CGFloat(rows + 1)
         self.cellSize = cellSize
         self.spacing = spacing
         self.columns = columns
         self.rows = rows
         self.gridSize = CGSize(width: gridWidth, height: gridHeight)
         self.originX = (size.width - gridWidth) / 2
         self.originY = (size.height - gridHeight) / 2
     }
 
     var gridRect: CGRect {
         CGRect(origin: CGPoint(x: originX, y: originY), size: gridSize)
     }
 
     func cellRect(row: Int, col: Int) -> CGRect {
         CGRect(
             x: originX + spacing + CGFloat(col) * (cellSize + spacing),
             y: originY + spacing + CGFloat(row) * (cellSize + spacing),
             width: cellSize,
             height: cellSize
         )
     }
 
     /// Inverse of `cellRect`: maps a tap point (in the grid's coordinate space)
     /// to the cell it falls in. Returns `nil` for points outside the grid (the
     /// centring margin / black border). The uniform lattice makes this pure
     /// arithmetic — the reason a single grid-wide tap recogniser can replace a
     /// per-cell one. Points landing in an inter-cell gap clamp to the nearest
     /// cell so the whole grid surface is tappable.
     func cell(at point: CGPoint) -> (row: Int, col: Int)? {
         guard gridRect.contains(point) else { return nil }
         let stride = cellSize + spacing
         guard stride > 0 else { return nil }
         let col = min(max(Int((point.x - originX - spacing) / stride), 0), columns - 1)
         let row = min(max(Int((point.y - originY - spacing) / stride), 0), rows - 1)
         return (row, col)
     }
 }
 
 // MARK: - Backing layers
 
 /// The opaque white cell backdrop, drawn behind the (clear-based) cells and
 /// beneath the peer cursor tints. Depends only on the puzzle's block layout, so
 /// it is static for the life of the game and never repaints during play. Blocks
 /// are skipped, leaving the container's black to show through.
 private struct GridBackdrop: View {
     let puzzle: Puzzle
     let spacing: CGFloat
 
     var body: some View {
         Canvas { context, size in
             let geometry = PuzzleGridGeometry(
                 size: size,
                 columns: puzzle.width,
                 rows: puzzle.height,
                 spacing: spacing
             )
             context.fill(Path(geometry.gridRect), with: .color(.black))
             for r in 0..<puzzle.height {
                 for c in 0..<puzzle.width where !puzzle.cells[r][c].isBlock {
                     context.fill(Path(geometry.cellRect(row: r, col: c)), with: .color(.white))
                 }
             }
         }
         .allowsHitTesting(false)
     }
 }
 
 /// Every present peer's selected answer, filled with that peer's selection
 /// colour so the track reads as a coloured run; the exact focused square is
 /// intentionally local-only. This is the only layer that observes the
 /// high-frequency `roster.remoteSelections` stream, so a peer cursor move
 /// repaints just this Canvas — drawing a handful of word cells — instead of
 /// re-evaluating the cell grid above.
 private struct RemoteCursorTints: View {
     let roster: PlayerRoster
     let puzzle: Puzzle
     let spacing: CGFloat
 
     var body: some View {
         let tints = remoteTrackTints()
         Canvas { context, size in
             guard !tints.isEmpty else { return }
             let geometry = PuzzleGridGeometry(
                 size: size,
                 columns: puzzle.width,
                 rows: puzzle.height,
                 spacing: spacing
             )
             for (pos, color) in tints {
                 context.fill(Path(geometry.cellRect(row: pos.row, col: pos.col)), with: .color(color))
             }
         }
         .allowsHitTesting(false)
     }
 
     /// Resolves each peer's cursor track to a per-cell fill colour, latest
     /// write winning where two peers' words overlap a cell.
     private func remoteTrackTints() -> [GridPosition: Color] {
         var tint: [GridPosition: (Date, Color)] = [:]
         for (_, sel) in roster.remoteSelections {
             for cell in puzzle.wordCells(
                 atRow: sel.row, col: sel.col, direction: sel.direction
             ) {
                 let pos = GridPosition(row: cell.row, col: cell.col)
                 if tint[pos].map({ $0.0 < sel.updatedAt }) ?? true {
                     tint[pos] = (sel.updatedAt, sel.color.selectionFill)
                 }
             }
         }
         return tint.mapValues { $0.1 }
     }
 }
 
 /// The local player's own cursor: the focused square (selection fill), the rest
 /// of the focused word (highlight fill), and a border on cross-referenced cells
 /// related to the focus. Like `RemoteCursorTints`, this is the only view that
 /// reads `session`'s selection, so a local cursor move repaints just this Canvas
 /// — a handful of cells — instead of re-evaluating the 441-cell grid above. In
 /// replay it draws only the single playhead cell in the acting author's colour;
 /// the live selection is suppressed. Sits above `RemoteCursorTints` so the local
 /// cursor reads over a peer's track where they overlap.
 private struct LocalCursorTints: View {
     let session: PlayerSession
     let spacing: CGFloat
     let isReplaying: Bool
     let replayCursor: GridPosition?
     let replayPlayheadTint: Color?
 
     @Environment(PlayerPreferences.self) private var preferences
 
     var body: some View {
         let fills = cellFills()
         let borders = isReplaying ? [] : relatedBorderCells()
         let borderColor = preferences.color.highlightFill
         // The focused square is repainted from white before its selection fill
         // so the author tint in the layer beneath never stacks with it: the
         // cursor keeps one fixed colour whether or not the square is filled,
         // while the rest of the word still blends with author tints. Live play
         // only — the replay playhead keeps the plain translucent fill.
         let selectedCell: GridPosition? = isReplaying
             ? nil
             : GridPosition(row: session.selectedRow, col: session.selectedCol)
         Canvas { context, size in
             guard !fills.isEmpty || !borders.isEmpty else { return }
             let geometry = PuzzleGridGeometry(
                 size: size,
                 columns: session.puzzle.width,
                 rows: session.puzzle.height,
                 spacing: spacing
             )
             if let pos = selectedCell {
                 context.fill(
                     Path(geometry.cellRect(row: pos.row, col: pos.col)),
                     with: .color(.white)
                 )
             }
             for (pos, color) in fills {
                 context.fill(Path(geometry.cellRect(row: pos.row, col: pos.col)), with: .color(color))
             }
             for pos in borders {
                 // Inset by half the line width so the stroke sits inside the
                 // cell, matching the in-cell `strokeBorder` it replaces.
                 let rect = geometry.cellRect(row: pos.row, col: pos.col).insetBy(dx: 1.5, dy: 1.5)
                 context.stroke(Path(rect), with: .color(borderColor), lineWidth: 3)
             }
         }
         .allowsHitTesting(false)
     }
 
     /// The selection/highlight fills. In replay this is just the playhead cell in
     /// the acting author's colour; live, it's the focused word in the highlight
     /// fill with the focused square overridden to the stronger selection fill.
     private func cellFills() -> [GridPosition: Color] {
         if isReplaying {
             guard let replayCursor, let replayPlayheadTint else { return [:] }
             return [replayCursor: replayPlayheadTint]
         }
         let color = preferences.color
         var fills: [GridPosition: Color] = [:]
         for cell in session.puzzle.wordCells(
             atRow: session.selectedRow,
             col: session.selectedCol,
             direction: session.direction
         ) {
             fills[GridPosition(row: cell.row, col: cell.col)] = color.highlightFill
         }
         fills[GridPosition(row: session.selectedRow, col: session.selectedCol)] = color.selectionFill
         return fills
     }
 
     private func relatedBorderCells() -> [GridPosition] {
         Array(session.puzzle.relatedCells(
             atRow: session.selectedRow,
             col: session.selectedCol,
             direction: session.direction
         ))
     }
 }
 
 /// Fading author-coloured borders on cells a peer filled or cleared since this
 /// player last viewed the puzzle. The set is captured once on the open arm beat
 /// (`PlayerSession.recentChanges`, populated by `PuzzleView`); this layer reveals
 /// it and fades it out when the player's first interaction clears the set. Like
 /// the cursor-tint layers it reads only its own slice of `session`, so it is the
 /// only view that repaints when the change set changes. Drawn over the cursor
 /// tints but behind the cells, matching `LocalCursorTints`' related-cell borders.
 private struct RecentChangeBorders: View {
     let session: PlayerSession
     let roster: PlayerRoster
     let spacing: CGFloat
 
     /// The resolved strokes currently drawn. Held locally so they stay on
     /// screen through the fade-out after `recentChanges` is cleared.
     @State private var shown: [GridPosition: Color] = [:]
     @State private var visible = false
 
     var body: some View {
         Canvas { context, size in
             guard !shown.isEmpty else { return }
             let geometry = PuzzleGridGeometry(
                 size: size,
                 columns: session.puzzle.width,
                 rows: session.puzzle.height,
                 spacing: spacing
             )
             for (pos, color) in shown {
                 let rect = geometry.cellRect(row: pos.row, col: pos.col)
                 let path = Path(rect.insetBy(dx: 1.5, dy: 1.5))
                 context.stroke(
                     path,
                     with: .color(color.opacity(0.10)),
                     lineWidth: 6
                 )
                 context.stroke(
                     path,
                     with: .color(color.opacity(0.30)),
                     lineWidth: 2
                 )
             }
         }
         .opacity(visible ? 1 : 0)
         .animation(.easeOut(duration: 0.45), value: visible)
         .allowsHitTesting(false)
         .onAppear { apply(session.recentChanges) }
         .onChange(of: session.recentChanges) { _, changes in apply(changes) }
     }
 
     private func apply(_ changes: [GridPosition: String]) {
         if changes.isEmpty {
             // Fade out, then drop the strokes once the animation has finished so
             // they remain visible while the opacity animates down.
             visible = false
             Task {
                 try? await Task.sleep(for: .milliseconds(500))
                 if session.recentChanges.isEmpty { shown = [:] }
             }
         } else {
             shown = resolve(changes)
             visible = true
         }
     }
 
     /// Maps each changed cell to its writer's colour, dropping out-of-bounds or
     /// block positions defensively. A writer no longer in the roster falls back
     /// to a neutral border rather than being skipped.
     private func resolve(_ changes: [GridPosition: String]) -> [GridPosition: Color] {
         let colorByAuthor = Dictionary(
             roster.entries.map { ($0.authorID, $0.color.tint) },
             uniquingKeysWith: { first, _ in first }
         )
         let width = session.puzzle.width
         let height = session.puzzle.height
         var result: [GridPosition: Color] = [:]
         for (pos, authorID) in changes {
             guard pos.row >= 0, pos.row < height, pos.col >= 0, pos.col < width else { continue }
             guard !session.puzzle.cells[pos.row][pos.col].isBlock else { continue }
             result[pos] = colorByAuthor[authorID] ?? Color.secondary
         }
         return result
     }
 }