crossmate

NYTToXDConverter.swift (36135B)

---

 import Foundation
 
 /// Converts NYT puzzle JSON (from `/v6/puzzle/daily/{date}.json`) to `.xd` format.
 enum NYTToXDConverter {
     struct ConversionError: LocalizedError {
         let message: String
         var errorDescription: String? { message }
     }
 
     /// Whether a cell fill must ride into the grid via a `Rebus:` placeholder
     /// rather than appear literally. The `.xd` grid is one character per cell and
     /// the grid parser only takes letters (plus block/special markers and
     /// declared placeholders) as direct fills, so anything longer than one
     /// character — or a single non-letter character such as the "2"/"3" cells in
     /// an "R2D2"/"C3PO" themer — has to be encoded. Routing every non-letter fill
     /// through a placeholder means a digit never appears literally in the grid:
     /// each grid digit is unambiguously a placeholder reference, so digit fills
     /// and digit placeholders can't collide.
     private static func needsRebusEncoding(_ answer: String) -> Bool {
         if answer.count != 1 { return true }
         return !(answer.first?.isLetter ?? false)
     }
 
     /// The asset the puzzle wants drawn over the grid for `key`, if any.
     ///
     /// Both overlay values are **one-based** indices into `assets`, and the URI
     /// must be read from there rather than derived: the host and filename shape
     /// have changed repeatedly over the years.
     private static func overlayImageURL(jsonData: Data, key: String) throws -> URL? {
         guard let root = try JSONSerialization.jsonObject(with: jsonData) as? [String: Any],
               let bodyArray = root["body"] as? [[String: Any]],
               let body = bodyArray.first,
               let overlays = body["overlays"] as? [String: Any],
               let index = intValue(overlays[key]),
               let assets = root["assets"] as? [[String: Any]] else {
             return nil
         }
         let position = index - 1
         guard assets.indices.contains(position),
               let uri = assets[position]["uri"] as? String,
               !uri.isEmpty else {
             return nil
         }
         return URL(string: uri)
     }
 
     /// The asset visible from the start of the puzzle, if any.
     static func beforeStartImageURL(jsonData: Data) throws -> URL? {
         try overlayImageURL(jsonData: jsonData, key: "beforeStart")
     }
 
     /// The asset revealed over the completed grid, if any.
     static func afterSolveImageURL(jsonData: Data) throws -> URL? {
         try overlayImageURL(jsonData: jsonData, key: "afterSolve")
     }
 
     /// Converts raw JSON data from the NYT puzzle endpoint to an `.xd` source string.
     ///
     /// The image arguments are the assets named by their corresponding URL
     /// helpers, when the caller managed to fetch them. Absent or unusable, the
     /// puzzle still converts without that art; an asset failure must never cost
     /// the player the underlying crossword.
     static func convert(
         jsonData: Data,
         beforeStartImage: Data? = nil,
         afterSolveImage: Data? = nil
     ) throws -> String {
         guard let root = try JSONSerialization.jsonObject(with: jsonData) as? [String: Any] else {
             throw ConversionError(message: "Invalid JSON root.")
         }
 
         // -- Metadata --
 
         let publicationDate = root["publicationDate"] as? String ?? ""
         let nytTitle = (root["title"] as? String)?
             .trimmingCharacters(in: .whitespacesAndNewlines)
         let title = if let nytTitle, !nytTitle.isEmpty {
             nytTitle
         } else {
             title(forPublicationDate: publicationDate)
         }
         let constructors = root["constructors"] as? [String] ?? []
         let editor = root["editor"] as? String
         let copyright = root["copyright"] as? String
 
         guard let bodyArray = root["body"] as? [[String: Any]],
               let body = bodyArray.first else {
             throw ConversionError(message: "Missing body in puzzle JSON.")
         }
 
         guard let dimensions = body["dimensions"] as? [String: Int],
               let width = dimensions["width"],
               let height = dimensions["height"] else {
             throw ConversionError(message: "Missing dimensions.")
         }
 
         guard width > 0, height > 0 else {
             throw ConversionError(message: "Invalid dimensions (\(width)x\(height)).")
         }
 
         guard let cells = body["cells"] as? [Any] else {
             throw ConversionError(message: "Missing cells.")
         }
 
         let (expectedCellCount, overflowed) = width.multipliedReportingOverflow(by: height)
         guard !overflowed, cells.count == expectedCellCount else {
             throw ConversionError(message: "Cell count (\(cells.count)) does not match dimensions (\(width)x\(height)).")
         }
 
         guard let clues = body["clues"] as? [[String: Any]] else {
             throw ConversionError(message: "Missing clues.")
         }
 
         // -- Parse cells into answers --
 
         // Each cell is either an empty dict (block) or a dict with "answer", "type", etc.
         var answers: [String?] = []  // nil = block, String = answer
         var acceptedAnswersByCellIndex: [Int: [String]] = [:]
 
         for (index, cell) in cells.enumerated() {
             guard let dict = cell as? [String: Any], !dict.isEmpty else {
                 answers.append(nil)
                 continue
             }
 
             let answer = dict["answer"] as? String ?? ""
             // NYT encodes a "Schrödinger" square — one correct as either of two
             // fills — as a slash-joined answer like "HIT/MISS", with every
             // acceptable entry enumerated in moreAnswers.valid. We keep the
             // slash form verbatim as the canonical fill: it's ASCII, needs no
             // rebus-header escaping, matches NYT's official answer, and reveals
             // as "HIT/MISS". The individual sides ("HIT", "MISS") and the single
             // crossing letters ("H", "M") ride along as accepted alternates
             // below — that's what a player actually enters, since the keyboard
             // can't produce a slash.
             if answer.isEmpty {
                 // A playable cell (NYT type 1) with no answer is an intentional
                 // blank: the "gap" in themers like the 2006-07-06 "THE GAP"
                 // puzzle, where crossing words read straight through a square
                 // whose solution is a literal space. NYT flags these with a
                 // blank-marker `moreAnswers` ("B"), which we drop by `continue`ing
                 // past the alternates below — the square's only correct state is
                 // empty. Any other answerless cell is a block.
                 answers.append(intValue(dict["type"]) == 1 ? " " : nil)
                 continue
             }
             answers.append(answer)
 
             if let moreAnswers = dict["moreAnswers"] as? [String: Any],
                let valid = moreAnswers["valid"] as? [String] {
                 // Every acceptable entry NYT lists passes through unchanged — the
                 // individual sides of a Schrödinger square, single crossing
                 // letters, and any other accepted string all round-trip into the
                 // Accept metadata.
                 let cleaned = valid.filter { !$0.isEmpty && $0 != answer }
                 if !cleaned.isEmpty {
                     acceptedAnswersByCellIndex[index] = cleaned
                 }
             }
         }
 
         // -- Find special (shaded/circled) cells from NYT cell data --
 
         let specialCells = specialCellInfo(body: body)
 
         // -- Build rebus header if needed --
 
         // Each distinct fill claims a grid placeholder. The fill alone is the
         // identity: circling and shading now ride in the `## Decorations`
         // section keyed by position, so a shaded and an unshaded occurrence of
         // the same rebus can share one placeholder instead of burning two.
         var rebusEntries: [(key: Character, answer: String)] = []
         var rebusLookup: [String: Character] = [:]
 
         for answer in answers {
             guard let answer, needsRebusEncoding(answer) else { continue }
             if rebusLookup[answer] == nil {
                 guard rebusLookup.count < XD.rebusPlaceholders.count else {
                     throw ConversionError(
                         message: "Too many distinct rebus fills (\(rebusLookup.count + 1)); ran out of grid placeholders."
                     )
                 }
                 let key = XD.rebusPlaceholders[rebusLookup.count]
                 rebusLookup[answer] = key
                 rebusEntries.append((key: key, answer: answer))
             }
         }
 
         // -- Build grid lines --
 
         var gridLines: [String] = []
         for row in 0..<height {
             var line = ""
             for col in 0..<width {
                 let index = row * width + col
                 guard let answer = answers[index] else {
                     line += "#"
                     continue
                 }
                 if needsRebusEncoding(answer) {
                     line += String(rebusLookup[answer]!)
                     continue
                 }
                 // A circled or shaded cell keeps its letter in the grid now that
                 // the decoration is expressed separately. The old `@`/`*` markers
                 // displaced the fill and left it to be recovered from the clue
                 // answers; the grid is both more readable and less derived for it.
                 line += answer.uppercased()
             }
             gridLines.append(line)
         }
 
         // -- Build clue lines --
 
         // Sort clues: Across first, then Down; within each group, by label number.
         let sortedClues = clues.sorted { a, b in
             let dirA = (a["direction"] as? String) ?? ""
             let dirB = (b["direction"] as? String) ?? ""
             if dirA != dirB { return dirA == "Across" }
             let labelA = intValue(a["label"]) ?? 0
             let labelB = intValue(b["label"]) ?? 0
             return labelA < labelB
         }
 
         var acrossClueLines: [String] = []
         var downClueLines: [String] = []
 
         for clue in sortedClues {
             let direction = clue["direction"] as? String ?? ""
             let label = intValue(clue["label"]) ?? 0
 
             // Extract clue text from the nested structure:
             // "text": [{"plain": "Clue text", "formatted": "<i>Clue text</i>"}]
             // When NYT supplies emphasis markup in `formatted` (italic themers,
             // etc.) convert it to .xd brace markup; otherwise fall back to the
             // `plain` reading. `formatted` is *not* always richer than plain —
             // image clues carry a bare symbol there ("¥") — so it is only
             // preferred when it actually carries markup.
             let clueText: String
             if let textArray = clue["text"] as? [[String: Any]],
                let firstText = textArray.first {
                 if let formatted = firstText["formatted"] as? String,
                    let markup = xdMarkup(fromFormatted: formatted) {
                     clueText = stripAriaLabelPrefix(markup)
                 } else if let plain = firstText["plain"] as? String {
                     clueText = stripAriaLabelPrefix(plain)
                 } else {
                     clueText = ""
                 }
             } else {
                 clueText = ""
             }
 
             // Build answer from cell indices
             let cellIndices = clue["cells"] as? [Int] ?? []
             var answerStr = ""
             for cellIndex in cellIndices {
                 guard answers.indices.contains(cellIndex) else {
                     throw ConversionError(
                         message: "Clue \(label) \(direction) references invalid cell index \(cellIndex)."
                     )
                 }
                 if let answer = answers[cellIndex] {
                     answerStr += answer
                 }
             }
 
             let prefix = direction == "Across" ? "A" : "D"
             let line = "\(prefix)\(label). \(clueText) ~ \(answerStr)"
             let acceptLine: String?
             let acceptedAnswers = acceptedAnswerVariants(
                 cellIndices: cellIndices,
                 answers: answers,
                 acceptedAnswersByCellIndex: acceptedAnswersByCellIndex
             )
             if acceptedAnswers.isEmpty {
                 acceptLine = nil
             } else {
                 let escaped = acceptedAnswers.map(escapeAcceptToken).joined(separator: " ")
                 acceptLine = "\(prefix)\(label) ^Accept: \(escaped)"
             }
 
             if direction == "Across" {
                 acrossClueLines.append(line)
                 if let acceptLine { acrossClueLines.append(acceptLine) }
             } else {
                 downClueLines.append(line)
                 if let acceptLine { downClueLines.append(acceptLine) }
             }
         }
 
         // -- Assemble .xd source --
 
         var sections: [String] = []
 
         // Metadata section
         var metadata: [String] = []
         metadata.append("Title: \(title)")
         metadata.append("ConVer: \(XD.currentConverterVersion)")
         metadata.append("Publisher: New York Times")
         if !publicationDate.isEmpty {
             metadata.append("Date: \(publicationDate)")
         }
         if !constructors.isEmpty {
             metadata.append("Author: \(constructors.joined(separator: ", "))")
         }
         if let editor {
             metadata.append("Editor: \(editor)")
         }
         if let copyright {
             metadata.append("Copyright: \(copyright)")
         }
 
         if !rebusEntries.isEmpty {
             let rebusStr = rebusEntries
                 .map { "\($0.key)=\(escapeRebusValue($0.answer))" }
                 .joined(separator: " ")
             metadata.append("Rebus: \(rebusStr)")
         }
 
         let relatives = buildRelativeGroups(clues: clues)
         if !relatives.isEmpty {
             let joined = relatives
                 .map { $0.joined(separator: ",") }
                 .joined(separator: "; ")
             metadata.append("Relatives: \(joined)")
         }
 
         sections.append(metadata.joined(separator: "\n"))
 
         // Grid section
         sections.append(gridLines.joined(separator: "\n"))
 
         // Clue sections (across then down, separated by blank line)
         let allClueLines = acrossClueLines + [""] + downClueLines
         sections.append(allClueLines.joined(separator: "\n"))
 
         // Decorations last: it is optional, named, and looked up by name rather
         // than position, so it can only ever be appended.
         var allDecorations = decorations(
             circled: specialCells.circled,
             shaded: specialCells.shaded,
             width: width
         )
         for (position, tile) in overlayDecorations(
             image: beforeStartImage,
             phase: .before,
             body: body,
             width: width,
             height: height
         ) {
             allDecorations[position, default: []].append(tile)
         }
         for (position, tile) in overlayDecorations(
             image: afterSolveImage,
             phase: .after,
             body: body,
             width: width,
             height: height
         ) {
             allDecorations[position, default: []].append(tile)
         }
         if let decorationSection = try XDDecorationWriter.section(
             decorations: allDecorations,
             width: width,
             height: height
         ) {
             sections.append(decorationSection)
         }
 
         // The .xd parser splits sections on two or more consecutive blank lines,
         // so we need two blank lines (three newlines) between sections.
         return sections.joined(separator: "\n\n\n")
     }
 
     private static func acceptedAnswerVariants(
         cellIndices: [Int],
         answers: [String?],
         acceptedAnswersByCellIndex: [Int: [String]]
     ) -> [String] {
         var variants: [String] = []
         var seen = Set<String>()
         let canonicalParts = cellIndices.map { answers.indices.contains($0) ? answers[$0] ?? "" : "" }
         let canonicalAnswer = canonicalParts.joined()
 
         for (partIndex, cellIndex) in cellIndices.enumerated() {
             guard let accepted = acceptedAnswersByCellIndex[cellIndex] else { continue }
             for value in accepted {
                 var parts = canonicalParts
                 parts[partIndex] = value
                 let variant = parts.joined()
                 guard variant != canonicalAnswer, seen.insert(variant).inserted else { continue }
                 variants.append(variant)
             }
         }
 
         return variants
     }
 
     /// Escapes a `Rebus:` value for the header's whitespace-delimited,
     /// `=`-keyed grammar (see `XD.parseRebusHeader`). Because the header splits
     /// entries on whitespace, a value that *is* whitespace — the space fill of a
     /// "gap" cell — can't appear literally; it rides in as the named escape
     /// `\space`. Backslash is the escape introducer, so a literal backslash
     /// doubles to `\\`. The scheme is deliberately open-ended: further `\name`
     /// (or `\u{...}`) escapes can join it to carry any character the header
     /// grammar would otherwise eat. `XD.unescapeRebusValue` is the inverse.
     private static func escapeRebusValue(_ value: String) -> String {
         var out = ""
         for ch in value {
             switch ch {
             case "\\": out += "\\\\"
             case " ": out += "\\space"
             default: out.append(ch)
             }
         }
         return out
     }
 
     private static func escapeAcceptToken(_ token: String) -> String {
         var escaped = ""
         for ch in token {
             if ch == "\\" || ch.isWhitespace {
                 escaped.append("\\")
             }
             escaped.append(ch)
         }
         return escaped
     }
 
     private static func title(forPublicationDate publicationDate: String) -> String {
         guard let date = date(fromPublicationDate: publicationDate) else {
             return "NYT Crossword"
         }
 
         let formatter = DateFormatter()
         formatter.calendar = Calendar(identifier: .gregorian)
         formatter.locale = Locale(identifier: "en_US_POSIX")
         formatter.timeZone = TimeZone(identifier: "America/New_York")
         formatter.dateFormat = "EEEE"
         return "\(formatter.string(from: date)) Crossword"
     }
 
     private static func date(fromPublicationDate publicationDate: String) -> Date? {
         let trimmed = publicationDate.trimmingCharacters(in: .whitespaces)
         guard let match = trimmed.firstMatch(of: /^(\d{4})-(\d{2})-(\d{2})$/),
               let year = Int(match.1),
               let month = Int(match.2),
               let day = Int(match.3)
         else { return nil }
 
         var calendar = Calendar(identifier: .gregorian)
         calendar.timeZone = TimeZone(identifier: "America/New_York") ?? .gmt
         var comps = DateComponents()
         comps.calendar = calendar
         comps.timeZone = calendar.timeZone
         comps.year = year
         comps.month = month
         comps.day = day
         return calendar.date(from: comps)
     }
 
     /// Themer/revealer groups: the structured `relatives` field plus
     /// italics-flagged theme answers. These are the connections the
     /// constructor did *not* surface in clue text — typically the trick
     /// underlying a theme — so they're suitable for catalog/analysis but
     /// should not drive any in-grid highlighting that would spoil the solve.
     /// Cross-references that live in clue prose ("See 11-Down") are derived
     /// at puzzle-load time in `Puzzle.init` instead.
     private static func buildRelativeGroups(clues: [[String: Any]]) -> [[String]] {
         var groups = buildRelatives(clues: clues)
         groups.append(contentsOf: buildFormattedClueGroups(clues: clues))
         var seen = Set<Set<String>>()
         return groups.filter { group in
             let key = Set(group)
             guard !key.isEmpty, !seen.contains(key) else { return false }
             seen.insert(key)
             return true
         }
     }
 
     /// Builds groups of cross-referenced clues from the v6 per-clue
     /// `relatives` arrays. Two rules admit a group, everything else is
     /// discarded:
     ///
     /// 1. **Revealer** — a clue with ≥2 relatives defines a group consisting
     ///    of itself plus every clue it references. The revealer's list is
     ///    treated as canonical.
     /// 2. **Mutual pair** — two clues that each list the other as their sole
     ///    relative form a group of two (the classic "See 14-Across" pattern).
     ///
     /// Single-direction 1-relative edges (where A references B but B does
     /// not reference A back) are dropped. This guards against NYT data
     /// errors where a leaf clue points at the wrong revealer.
     private static func buildRelatives(clues: [[String: Any]]) -> [[String]] {
         // Extract each clue's (label, direction) and relatives array.
         var tokens: [String?] = []
         var relativeIndices: [[Int]] = []
         tokens.reserveCapacity(clues.count)
         relativeIndices.reserveCapacity(clues.count)
         for clue in clues {
             let direction = clue["direction"] as? String ?? ""
             let label = intValue(clue["label"]) ?? 0
             if label > 0, direction == "Across" || direction == "Down" {
                 tokens.append("\(label)\(direction == "Across" ? "A" : "D")")
             } else {
                 tokens.append(nil)
             }
             let raw = clue["relatives"] as? [Int] ?? []
             let cleaned = Array(Set(raw.filter { $0 >= 0 && $0 < clues.count }))
             relativeIndices.append(cleaned)
         }
 
         var groups: [[String]] = []
         var seen = Set<Set<Int>>()
 
         func emit(_ members: Set<Int>) {
             guard members.count >= 2, !seen.contains(members) else { return }
             seen.insert(members)
             let sorted = members.sorted { a, b in
                 // Order by (number, direction-is-across-first). Extract from
                 // the stored token; fallback to index if a token is missing.
                 guard let ta = tokens[a], let tb = tokens[b] else { return a < b }
                 let (na, da) = (Int(ta.dropLast()) ?? 0, ta.last!)
                 let (nb, db) = (Int(tb.dropLast()) ?? 0, tb.last!)
                 if na != nb { return na < nb }
                 return da == "A" && db == "D"
             }
             let toks = sorted.compactMap { tokens[$0] }
             if toks.count >= 2 { groups.append(toks) }
         }
 
         // Rule 1: revealers.
         for (i, refs) in relativeIndices.enumerated() where refs.count >= 2 {
             var members = Set<Int>()
             members.insert(i)
             for r in refs { members.insert(r) }
             emit(members)
         }
 
         // Rule 2: mutual pairs. Only consider clues with exactly one relative
         // — revealer-formed groups already cover the multi-relative cases.
         for (i, refs) in relativeIndices.enumerated() where refs.count == 1 {
             let j = refs[0]
             guard j != i, relativeIndices.indices.contains(j) else { continue }
             if relativeIndices[j] == [i] {
                 emit(Set([i, j]))
             }
         }
 
         return groups
     }
 
     /// NYT marks some theme clues by supplying formatted clue text, commonly
     /// `<i>...</i>`, without adding `relatives`. Group all such clue refs so
     /// their answer cells can be highlighted by Crossmate's thematic mask.
     ///
     /// A revealer is folded into the same group when its prose names the set —
     /// "the answer to each italicized clue", "the five italicized clues". The
     /// revealer carries no markup or `relatives` of its own, so this prose
     /// reference is the only signal binding it to the themers. The link is only
     /// drawn when an italicized set actually exists, which keeps an incidental
     /// mention from a clue that isn't a revealer out of the group.
     private static func buildFormattedClueGroups(clues: [[String: Any]]) -> [[String]] {
         var tokens = clues.compactMap { clue -> String? in
             guard clueHasFormattedText(clue) else { return nil }
             return clueToken(clue)
         }
         guard !tokens.isEmpty else { return [] }
 
         let themers = Set(tokens)
         for clue in clues where clueReferencesItalicizedSet(clue) {
             guard let token = clueToken(clue), !themers.contains(token) else { continue }
             tokens.append(token)
         }
         return [sortedClueTokens(tokens)]
     }
 
     /// Whether a clue's prose points at the italicized themers — the word
     /// "italicized" immediately followed by "clue" or "answer" ("each
     /// italicized clue", "answers to the italicized clues"). Italic is the only
     /// emphasis NYT pairs with a revealer; bold and underline never are.
     private static func clueReferencesItalicizedSet(_ clue: [String: Any]) -> Bool {
         cluePlainText(clue).lowercased().contains(/italici[sz]ed\s+(clue|answer)/)
     }
 
     private static func cluePlainText(_ clue: [String: Any]) -> String {
         guard let textArray = clue["text"] as? [[String: Any]],
               let plain = textArray.first?["plain"] as? String else { return "" }
         return plain
     }
 
     /// Orders `{number}{A|D}` tokens by number, Across before Down, so a folded
     /// revealer lands in sequence rather than at the end.
     private static func sortedClueTokens(_ tokens: [String]) -> [String] {
         tokens.sorted { a, b in
             let na = Int(a.dropLast()) ?? 0
             let nb = Int(b.dropLast()) ?? 0
             if na != nb { return na < nb }
             return a.last == "A" && b.last == "D"
         }
     }
 
     private static func clueHasFormattedText(_ clue: [String: Any]) -> Bool {
         guard let textArray = clue["text"] as? [[String: Any]] else { return false }
         return textArray.contains { textPart in
             guard let formatted = textPart["formatted"] as? String else { return false }
             // A non-empty `formatted` field alone isn't a theme signal: image
             // clues mirror a bare symbol ("¥") or the plain text there. Only
             // genuine emphasis markup marks a themer.
             return containsEmphasisMarkup(decodeBasicEntities(formatted))
         }
     }
 
     typealias TagMapping = (open: String, close: String, xdOpen: String, xdClose: String)
 
     /// HTML emphasis tags that mark a *theme* clue. NYT italicizes its themers
     /// (`<i>`/`<em>`), the convention this grouping keys on; `<b>`/`<strong>`
     /// are included as the same kind of prose emphasis. Underline is handled
     /// separately (see `underlineTags`) because NYT uses it for highlight
     /// gimmicks — "`<u>John</u> ___`" — not themers, so it must not group.
     private static let emphasisTags: [TagMapping] = [
         ("<i>", "</i>", "{/", "/}"),
         ("<em>", "</em>", "{/", "/}"),
         ("<b>", "</b>", "{*", "*}"),
         ("<strong>", "</strong>", "{*", "*}"),
     ]
 
     /// Underline markup. Mapped for display fidelity (it is the second most
     /// common clue markup in the NYT archive) but deliberately excluded from
     /// the theme-grouping signal above.
     private static let underlineTags: [TagMapping] = [
         ("<u>", "</u>", "{_", "_}"),
     ]
 
     private static var markupTags: [TagMapping] { emphasisTags + underlineTags }
 
     /// Whether `html` carries emphasis NYT uses to flag a themer. Other markup
     /// (underline, sub/sup, layout tags) does not count.
     private static func containsEmphasisMarkup(_ html: String) -> Bool {
         let lower = html.lowercased()
         return emphasisTags.contains { lower.contains($0.open) }
     }
 
     private static func containsConvertibleMarkup(_ html: String) -> Bool {
         let lower = html.lowercased()
         return markupTags.contains { lower.contains($0.open) }
     }
 
     /// Converts NYT `formatted` clue HTML to `.xd` brace markup, or returns nil
     /// when it carries no markup we recognize (so the caller falls back to
     /// `plain`). Entities are decoded so prose like `Salt &amp; pepper`
     /// round-trips, and any unrecognized residual tags — sub/sup, `<span>`,
     /// stray layout markup — are dropped, preserving their text content.
     private static func xdMarkup(fromFormatted formatted: String) -> String? {
         let decoded = decodeBasicEntities(formatted)
         guard containsConvertibleMarkup(decoded) else { return nil }
         var out = decoded
         for tag in markupTags {
             out = out.replacingOccurrences(of: tag.open, with: tag.xdOpen, options: .caseInsensitive)
             out = out.replacingOccurrences(of: tag.close, with: tag.xdClose, options: .caseInsensitive)
         }
         return out.replacing(/<[^>]+>/, with: "")
     }
 
     private static func decodeBasicEntities(_ s: String) -> String {
         var out = s
         for (entity, char) in [("&lt;", "<"), ("&gt;", ">"), ("&quot;", "\""),
                                ("&#39;", "'"), ("&apos;", "'"), ("&amp;", "&")] {
             out = out.replacingOccurrences(of: entity, with: char)
         }
         return out
     }
 
     private static func clueToken(_ clue: [String: Any]) -> String? {
         let direction = clue["direction"] as? String ?? ""
         let label = intValue(clue["label"]) ?? 0
         guard label > 0, direction == "Across" || direction == "Down" else { return nil }
         return "\(label)\(direction == "Across" ? "A" : "D")"
     }
 
     private static func specialCellInfo(body: [String: Any]) -> (circled: Set<Int>, shaded: Set<Int>) {
         guard let cells = body["cells"] as? [Any] else { return ([], []) }
         var circled: Set<Int> = []
         var shaded: Set<Int> = []
         for (index, cell) in cells.enumerated() {
             guard let dict = cell as? [String: Any] else { continue }
             switch intValue(dict["type"]) {
             case 2:
                 circled.insert(index)
             case 3:
                 shaded.insert(index)
             default:
                 continue
             }
         }
 
         return (circled, shaded)
     }
 
     /// Slices one overlay into per-cell decorations with its original phase.
     ///
     /// Every failure here is silent and total: no image, unreadable geometry,
     /// an asset that doesn't match the board, or a payload over budget all
     /// yield no decorations rather than a partial set. A fragmented overlay
     /// reads as a bug, whereas missing art still leaves a usable crossword.
     private static func overlayDecorations(
         image: Data?,
         phase: Puzzle.Decoration.Phase,
         body: [String: Any],
         width: Int,
         height: Int
     ) -> [GridPosition: Puzzle.Decoration] {
         guard let image,
               let boardSVG = body["board"] as? String,
               let geometry = NYTOverlaySlicer.geometry(boardSVG: boardSVG),
               let tiles = NYTOverlaySlicer.tiles(
                   imageData: image,
                   geometry: geometry,
                   width: width,
                   height: height
               ) else {
             return [:]
         }
 
         // NYT sometimes uses overlays to style information already carried by
         // playable cells (for example the REDR/REDU rebuses in 2021's "Ruby
         // Lips" puzzle). OCR is only useful for otherwise-empty block cells,
         // such as the ENERGY letters hidden in the 2026-07-23 grid. Keeping
         // this gate in terms of the raw NYT cells also prevents PUZ imports or
         // arbitrary decoration images from ever reaching the recognizer.
         if phase == .after, overlayTargetsOnlyEmptyBlocks(
             Set(tiles.keys),
             body: body,
             width: width,
             height: height
         ), let letters = NYTOverlayLetterRecognizer.letters(in: tiles) {
             return letters.mapValues { letter in
                 Puzzle.Decoration(content: .text(String(letter)), phase: .after)
             }
         }
 
         return rasterDecorations(for: tiles, phase: phase)
     }
 
     /// Whether every inked overlay tile lands on a NYT block represented by an
     /// empty cell dictionary. One ineligible tile rejects text conversion for
     /// the whole asset, so a mixed overlay is never partially guessed.
     static func overlayTargetsOnlyEmptyBlocks(
         _ positions: Set<GridPosition>,
         body: [String: Any],
         width: Int,
         height: Int
     ) -> Bool {
         guard !positions.isEmpty,
               width > 0,
               height > 0,
               let cells = body["cells"] as? [Any],
               case let (cellCount, false) = width.multipliedReportingOverflow(by: height),
               cells.count == cellCount else {
             return false
         }
         for position in positions {
             guard position.row >= 0,
                   position.row < height,
                   position.col >= 0,
                   position.col < width,
                   let cell = cells[position.row * width + position.col] as? [String: Any],
                   cell.isEmpty else {
                 return false
             }
         }
         return true
     }
 
     private static func rasterDecorations(
         for tiles: [GridPosition: Data],
         phase: Puzzle.Decoration.Phase
     ) -> [GridPosition: Puzzle.Decoration] {
         tiles.mapValues { png in
             if let hex = NYTOverlaySlicer.uniformBackgroundHex(imageData: png) {
                 return Puzzle.Decoration(
                     content: .color(layer: .background, light: hex, dark: nil),
                     phase: phase
                 )
             }
             return Puzzle.Decoration(
                 content: .data(
                     mimeType: "image/png",
                     encoding: "base64",
                     payload: png.base64EncodedString()
                 ),
                 phase: phase
             )
         }
     }
 
     /// Projects the NYT's circled/shaded cell indices onto positions carrying a
     /// `mark` decoration. Both are `before`-phase — they're visible from the
     /// start, exactly as the `Specials:` header they replace always was.
     private static func decorations(
         circled: Set<Int>,
         shaded: Set<Int>,
         width: Int
     ) -> [GridPosition: [Puzzle.Decoration]] {
         var result: [GridPosition: [Puzzle.Decoration]] = [:]
         func add(_ indices: Set<Int>, _ special: Puzzle.Special) {
             for index in indices {
                 let position = GridPosition(row: index / width, col: index % width)
                 result[position, default: []].append(
                     Puzzle.Decoration(content: .mark(special), phase: .before)
                 )
             }
         }
         add(circled, .circled)
         add(shaded, .shaded)
         return result
     }
 
     /// NYT image-based clues mirror the image's aria-label in the `plain`
     /// field, prefixed with the literal token `[aria-label]`. The prefix is a
     /// machine marker, not part of the clue itself, so strip it.
     private static func stripAriaLabelPrefix(_ text: String) -> String {
         let trimmed = text.drop(while: { $0 == " " })
         guard trimmed.lowercased().hasPrefix("[aria-label]") else { return text }
         let afterToken = trimmed.dropFirst("[aria-label]".count)
         return String(afterToken.drop(while: { $0 == " " }))
     }
 
     /// Extracts an Int from a JSON value that may be NSNumber, Int, or Double.
     private static func intValue(_ value: Any?) -> Int? {
         if let n = value as? Int { return n }
         if let s = value as? String { return Int(s) }
         if let n = value as? NSNumber { return n.intValue }
         if let n = value as? Double { return Int(n) }
         return nil
     }
 }