crossmate

NYTToXDConverter.swift (30026B)

---

 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 }
     }
 
     /// Single-character grid placeholders for multi-letter (rebus) fills. The
     /// `.xd` grid is one character per cell, so a cell whose fill is longer than
     /// one letter shows one of these in the grid and is expanded via the
     /// `Rebus:` header (the `1` in `1=LW`). These are *not* NYT data — they're
     /// our `.xd` serialization. The `.xd` spec allows "digits, most symbols,
     /// and printable unicode characters (if needed)" here; we take digits first
     /// (the conventional, readable encoding) then the symbols, where "most"
     /// means every printable ASCII symbol *except* the ones the grid/header
     /// parser already reserves — letters (grid fill), `#`/`_`/`.` (block/empty),
     /// `@`/`*` (special markers), and `=`/space (`Rebus:` `key=value` syntax).
     /// We stop at ASCII rather than walking into unicode and throw past the
     /// ceiling; real puzzles use a handful of distinct fills, nowhere near it.
     /// (Walking ASCII naïvely from `'1'` overflows into `=` by the 13th key,
     /// which produced an unparseable `==VALUE` entry and a rejected grid char.)
     private static let rebusPlaceholders: [Character] = {
         let reserved: Set<Character> = ["#", "_", ".", "@", "*", "=", " "]
         let symbols = (UInt8(33)...UInt8(126))
             .map { Character(UnicodeScalar($0)) }
             .filter { !$0.isLetter && !$0.isNumber && !reserved.contains($0) }
         return Array("123456789") + symbols
     }()
 
     /// 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)
     }
 
     /// Converts raw JSON data from the NYT puzzle endpoint to an `.xd` source string.
     static func convert(jsonData: Data) 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 let cells = body["cells"] as? [Any] else {
             throw ConversionError(message: "Missing cells.")
         }
 
         guard cells.count == width * height 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 rawAnswer = dict["answer"] as? String ?? ""
             // NYT encodes a "Schrödinger" square — one correct as either of two
             // letters — as a slash-joined answer like "L/W", with every
             // acceptable keystroke enumerated in moreAnswers.valid. The slash
             // is NYT notation, not a grid character (and isn't on our
             // keyboard), so collapse it: the letters together ("LW") become the
             // canonical rebus fill, and each single letter rides along as an
             // accepted alternate via the moreAnswers handling below.
             let isSchrodinger = rawAnswer.contains("/")
             let answer = isSchrodinger
                 ? rawAnswer.replacingOccurrences(of: "/", with: "")
                 : rawAnswer
             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] {
                 // For Schrödinger cells, strip the slash from each alternate too
                 // so only keyboard-enterable letter forms survive, then
                 // dedupe/sort for stable output. Other cells pass their
                 // alternates through unchanged so arbitrary accepted strings
                 // still round-trip.
                 let candidates = isSchrodinger
                     ? valid.map { $0.replacingOccurrences(of: "/", with: "") }
                     : valid
                 let cleaned = candidates.filter { !$0.isEmpty && $0 != answer }
                 if !cleaned.isEmpty {
                     acceptedAnswersByCellIndex[index] = isSchrodinger
                         ? Array(Set(cleaned)).sorted()
                         : cleaned
                 }
             }
         }
 
         // -- Build rebus header if needed --
 
         // Check for multi-character answers. Each distinct multi-letter fill
         // claims the next grid placeholder from `rebusPlaceholders`.
         var rebusEntries: [(key: Character, value: String)] = []
         var rebusLookup: [String: Character] = [:]
 
         for answer in answers {
             guard let answer, needsRebusEncoding(answer) else { continue }
             if rebusLookup[answer] == nil {
                 guard rebusLookup.count < rebusPlaceholders.count else {
                     throw ConversionError(
                         message: "Too many distinct rebus fills (\(rebusLookup.count + 1)); ran out of grid placeholders."
                     )
                 }
                 let key = rebusPlaceholders[rebusLookup.count]
                 rebusLookup[answer] = key
                 rebusEntries.append((key: key, value: answer))
             }
         }
 
         // -- Find special (shaded/circled) cells from NYT cell data --
 
         let specialCells = specialCellInfo(body: body)
 
         // -- 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 specialCells.circled.contains(index) {
                     line += "@"
                     continue
                 }
                 if specialCells.shaded.contains(index) {
                     line += "*"
                     continue
                 }
                 if needsRebusEncoding(answer) {
                     line += String(rebusLookup[answer]!)
                 } else {
                     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] ?? []
             let answerStr = cellIndices.compactMap { answers[$0] }.joined()
 
             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("CmVer: \(XD.currentCmVersion)")
         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.value))" }
                 .joined(separator: " ")
             metadata.append("Rebus: \(rebusStr)")
         }
 
         let specialMappings = specialMappings(circled: specialCells.circled, shaded: specialCells.shaded)
         if !specialMappings.isEmpty {
             metadata.append("Specials: \(specialMappings)")
         }
 
         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"))
 
         // 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)
     }
 
     private static func specialMappings(circled: Set<Int>, shaded: Set<Int>) -> String {
         var parts: [String] = []
         if !circled.isEmpty {
             parts.append("@=circle")
         }
         if !shaded.isEmpty {
             parts.append("*=shaded")
         }
         return parts.joined(separator: " ")
     }
 
     /// 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
     }
 }