feat: macOS 15.x spell-check fallback — engine-driven underlines

## Summary

- On macOS 15.x the system's own TextKit 2 continuous-spell-check pass
  neither writes nor paints `.spellingState` rendering attributes on
  custom `NSTextLayoutFragment` subclasses (confirmed by the harness
  attached to #59: red=0 on both arms, byte-identical PNGs).
  This left `isContinuousSpellCheckingEnabled` silently no-op in the
  editor on 15.x.
- Drive `NSSpellChecker.requestChecking(of:…)` asynchronously on the
  coordinator (400 ms debounce, no main-thread XPC stalls). Hits are
  filtered through the existing zone helpers (`isInsideCode`,
  `isInsideLatex`, `isInsideSpellcheckSuppressedToken`) so code,
  LaTeX, links, and image embeds stay clean.
- Paint dotted-red underlines in
  `MarkdownTextLayoutFragment.draw(at:in:)` as step 7 of the draw
  pipeline. The cache is cleared **synchronously** on every
  `textDidChange` so no stale-offset underlines paint during the
  debounce window.
- Version-gated: `#unavailable(macOS 26)` at the coordinator entry
  points keeps the driver a no-op on 26+ where AppKit's native pass
  works. No double underlines.
- Uses `textView.spellCheckerDocumentTag` (not a private tag) so the
  system "Ignore Spelling" action clears the underline.
- Print/PDF exclusion via `NSPrintOperation.current` — underlines are
  for on-screen editing only.
- RTL-safe: computes absolute x1/x2, swaps when the text direction
  flips the order.
- Theme integration: `MarkdownEditorTheme.misspellingUnderlineColor`
  (default `.systemRed`) so apps with a custom palette can override.
- `MarkdownASTStyler` stamps `.spellingState: 0` on fenced code blocks
  and inline `code` spans, completing the existing suppression
  convention (belt-and-suspenders with the coordinator-side filter).

Behavior toggles from #36 (`SpellCheckingPolicy`, context-menu
overrides, `userPrefersContinuousSpellChecking`) are unchanged — this PR
only adds the missing render pass and routes through the same preference.

Supersedes the render-pass portion of #59.

Author: Ender-Wang

CHANGELOG.md

@@ -21,6 +21,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ```
 
 ### Added
+- `MarkdownEditorTheme.misspellingUnderlineColor` (default `.systemRed`),
+  routed through the engine's macOS 15.x spell-check fallback so custom
+  palettes control the dotted-red underline color.
+- macOS 15.x spell-check fallback. On macOS 15.x the system's own
+  TextKit 2 pass neither writes nor paints `.spellingState` rendering
+  attributes on custom `NSTextLayoutFragment` subclasses. The engine now
+  drives `NSSpellChecker.requestChecking(of:…)` itself (400 ms debounce,
+  async, no main-thread stalls) and paints dotted-red underlines in
+  `MarkdownTextLayoutFragment.draw(at:in:)`. The cache is cleared
+  synchronously on every `textDidChange` so no stale-offset underlines
+  paint during the debounce window. On macOS 26+ the fallback is a
+  no-op (AppKit's native pass handles everything). Uses
+  `textView.spellCheckerDocumentTag` so "Ignore Spelling" works,
+  respects the existing `SpellCheckingPolicy` toggles from #36, and
+  excludes underlines from print/PDF output via `NSPrintOperation.current`.
+- `MarkdownASTStyler` now stamps `.spellingState: 0` on fenced code
+  blocks and inline `code` spans, completing the engine's existing
+  spell-check suppression convention (links, wiki-links, LaTeX, and
+  tables already carry the same attribute). Code regions stay clean
+  under both the system's native pass (macOS 26+) and the engine's
+  own 15.x fallback driver.
 - `SafeAreaInsets` struct exposing `top` / `leading` / `trailing` / `bottom`
   inset knobs for the editor's enclosing scroll view, configurable via
   `MarkdownEditorConfiguration.safeAreaInsets`.

Sources/MarkdownEngine/Configuration/MarkdownEditorTheme.swift

@@ -74,6 +74,14 @@ public struct MarkdownEditorTheme: Sendable {
     /// (e.g. completed task list items, horizontal rules).
     public var strikethroughColor: NSColor
 
+    /// Stroke color used for misspelling underlines drawn by the engine's
+    /// macOS 15.x fallback (when AppKit's own TextKit 2 pass does not
+    /// paint `.spellingState` rendering attributes). Defaults to
+    /// `.systemRed` to match the system's native misspelling marks; apps
+    /// with a custom palette should override this alongside the rest of
+    /// the theme.
+    public var misspellingUnderlineColor: NSColor
+
     // MARK: Init
 
     public init(
@@ -87,7 +95,8 @@ public struct MarkdownEditorTheme: Sendable {
         findCurrentMatchHighlight: NSColor = .systemYellow,
         latexLightModeText: NSColor = .black,
         latexDarkModeText: NSColor = .white,
-        strikethroughColor: NSColor = .labelColor
+        strikethroughColor: NSColor = .labelColor,
+        misspellingUnderlineColor: NSColor = .systemRed
     ) {
         self.bodyText = bodyText
         self.mutedText = mutedText
@@ -100,6 +109,7 @@ public struct MarkdownEditorTheme: Sendable {
         self.latexLightModeText = latexLightModeText
         self.latexDarkModeText = latexDarkModeText
         self.strikethroughColor = strikethroughColor
+        self.misspellingUnderlineColor = misspellingUnderlineColor
     }
 
     /// System-native palette built from `NSColor` dynamic system colors.

Sources/MarkdownEngine/Renderer/MarkdownTextLayoutFragment.swift

@@ -94,6 +94,11 @@ final class MarkdownTextLayoutFragment: NSTextLayoutFragment {
 
         // 6. Blockquote bars (left gutter, behind nothing — text is indented)
         drawBlockquoteBars(at: point, in: context)
+
+        // 7. Spell-check underlines (macOS 15.x fallback). On macOS 26+
+        //    AppKit's own TextKit 2 pass paints `.spellingState` via the
+        //    default fragment; the engine's driver is a no-op there.
+        drawSpellMisspellings(at: point, in: context)
     }
 
     // MARK: - Helpers
@@ -589,6 +594,89 @@ final class MarkdownTextLayoutFragment: NSTextLayoutFragment {
             }
         }
     }
+
+    // MARK: - Spell-check underlines (macOS 15.x fallback)
+
+    /// Paint dotted red underlines beneath every misspelled range that
+    /// intersects this fragment. Reads the cache populated by
+    /// `NativeTextViewCoordinator+SpellCheck` (see
+    /// `scheduleSpellCheck` / `runSpellCheckPass`).
+    ///
+    /// Required on macOS 15.x: the system's own continuous-spell-check
+    /// pass neither writes nor paints `.spellingState` rendering
+    /// attributes on TextKit 2 custom fragments (confirmed by
+    /// `spellcheck-pipeline-test.swift` in the fork's `.tmp/`). On
+    /// macOS 26+ AppKit handles this natively and the cache stays empty.
+    ///
+    /// Anti-pattern fixes vs. PR #59:
+    /// - Routes color through `MarkdownEditorTheme.misspellingUnderlineColor`.
+    /// - RTL-safe: computes absolute `x1`/`x2` and swaps when needed.
+    /// - Skips when the current graphics context is for print/PDF so
+    ///   misspelling marks don't bleed into exported documents.
+    /// - No version gate here: on 26+ the cache is empty because the
+    ///   engine's `scheduleSpellCheck` driver is gated in the coordinator.
+    private func drawSpellMisspellings(at point: CGPoint, in context: CGContext) {
+        // Print/PDF exclusion: underlines are for on-screen editing only.
+        // `NSPrintOperation.current` is set while the fragment is being
+        // drawn into a print/PDF context; screen drawing leaves it nil.
+        if NSPrintOperation.current != nil { return }
+        // On macOS 26+ the coordinator keeps this empty.
+        guard let textView = textLayoutManager?.textContainer?.textView as? NativeTextView,
+              let coordinator = textView.delegate as? NativeTextViewCoordinator,
+              !coordinator.spellMisspelledRanges.isEmpty
+        else { return }
+        guard let fragRange = fragmentNSRange, fragRange.length > 0 else { return }
+        let fragStart = fragRange.location
+        let fragEnd = NSMaxRange(fragRange)
+
+        let theme = textView.configuration.theme
+        NSGraphicsContext.saveGraphicsState()
+        defer { NSGraphicsContext.restoreGraphicsState() }
+        let nsContext = NSGraphicsContext(cgContext: context, flipped: true)
+        NSGraphicsContext.current = nsContext
+
+        theme.misspellingUnderlineColor.withAlphaComponent(0.7).setStroke()
+        let path = NSBezierPath()
+        path.lineWidth = 1.5
+        path.lineCapStyle = .round
+        path.setLineDash([1.5, 1.5], count: 2, phase: 0)
+
+        for misspelled in coordinator.spellMisspelledRanges {
+            let mStart = misspelled.location
+            let mEnd = NSMaxRange(misspelled)
+            if mEnd <= fragStart || mStart >= fragEnd { continue }
+            let docLo = max(mStart, fragStart)
+            let docHi = min(mEnd, fragEnd)
+            let localLo = docLo - fragStart
+            let localHi = docHi - fragStart
+
+            for lineFragment in textLineFragments {
+                let lr = lineFragment.characterRange
+                let lrLo = lr.location
+                let lrHi = lr.location + lr.length
+                let lo = max(localLo, lrLo)
+                let hi = min(localHi, lrHi)
+                guard lo < hi else { continue }
+
+                let startPos = lineFragment.locationForCharacter(at: lo)
+                let endPos = lineFragment.locationForCharacter(at: hi)
+                let tb = lineFragment.typographicBounds
+                var x1 = point.x + tb.origin.x + startPos.x
+                var x2 = point.x + tb.origin.x + endPos.x
+                // RTL-safe: swap if the text direction flipped the order.
+                if x2 < x1 { swap(&x1, &x2) }
+                guard x1 != x2 else { continue }
+                // baselineY = line-top + baseline offset within the line.
+                let baselineY = point.y + tb.origin.y + startPos.y
+                // Place the underline ~1.5pt below the baseline, matching
+                // where AppKit's own misspelling marks typically sit.
+                let y = baselineY + 1.5
+                path.move(to: NSPoint(x: x1, y: y))
+                path.line(to: NSPoint(x: x2, y: y))
+            }
+        }
+        path.stroke()
+    }
 }
 
 // MARK: - Layout Manager Delegate

Sources/MarkdownEngine/Styling/MarkdownASTStyler.swift

@@ -367,6 +367,10 @@ enum MarkdownASTStyler {
         attrs.append((parts.codeRange, [
             .font: ctx.codeFont, .backgroundColor: ctx.codeBackground, .paragraphStyle: ctx.codeParagraphStyle,
         ]))
+        // Suppress spell-check underlines on the whole fenced block —
+        // code is not prose. Completes the existing link / wiki-link
+        // convention (see `styleLink` / `styleWikiLink`).
+        attrs.append((parts.codeRange, [.spellingState: 0]))
         let codeContent = ctx.ns.substring(with: parts.content)
         if !codeContent.isEmpty,
            let highlighted = ctx.config.services.syntaxHighlighter.highlight(code: codeContent, language: parts.language) {
@@ -431,6 +435,10 @@ enum MarkdownASTStyler {
 
             case .code(let range, let contentRange):
                 attrs.append((contentRange, [.font: ctx.codeFont, .backgroundColor: ctx.codeBackground]))
+                // Suppress spell-check underlines on inline `code` spans
+                // (markers + content) — same convention as `styleLink` /
+                // `styleWikiLink` / `styleTable` / `styleLatex`.
+                attrs.append((range, [.spellingState: 0]))
                 let markerAttrs: [NSAttributedString.Key: Any] = ctx.isActive(range)
                     ? [.foregroundColor: ctx.theme.mutedText, .font: ctx.codeFont]
                     : [.foregroundColor: ctx.theme.mutedText.withAlphaComponent(ctx.config.markers.inlineCodeMarkerAlpha),

Sources/MarkdownEngine/TextView/Coordinator/NativeTextViewCoordinator+SpellCheck.swift

@@ -0,0 +1,138 @@
+//
+//  NativeTextViewCoordinator+SpellCheck.swift
+//  MarkdownEngine
+//
+//  macOS 15.x fallback spell-check driver. On macOS 26+ AppKit's own
+//  TextKit 2 pass paints `.spellingState` underlines via the default
+//  fragment. On 15.x that path is broken (the system neither writes nor
+//  renders `.spellingState` on custom fragments), so the engine drives
+//  `NSSpellChecker` itself and paints dotted-red underlines from the
+//  coordinator's misspelled-range cache in
+//  `MarkdownTextLayoutFragment.draw(at:in:)`.
+//
+//  Design (see devlog-0610-spellcheck-15x-fallback-design.md):
+//  - Async `NSSpellChecker.requestChecking(of:…)` — no main-thread XPC.
+//  - 400 ms debounce. Cache is cleared **synchronously** on every
+//    `textDidChange` before the next pass is scheduled, so the stale-
+//    offset bug class never surfaces.
+//  - Reuses existing zone helpers (`isInsideCode`, `isInsideLatex`,
+//    `isInsideSpellcheckSuppressedToken`) — same gates as
+//    `NativeTextView+SpellingPolicy`. Belt-and-suspenders with the
+//    `.spellingState: 0` stamps added by PR #64.
+//  - Uses `textView.spellCheckerDocumentTag` (not a private tag) so
+//    the system "Ignore Spelling" action clears the underline.
+//  - `didToggleSpellCheckingPolicy` cancels the pending pass on
+//    toggle-off and schedules an immediate pass on toggle-on.
+//
+
+import AppKit
+
+extension NativeTextViewCoordinator {
+    /// Debounce window between the last edit and the spell-check pass.
+    /// Long enough to avoid stalling fast typists, short enough that the
+    /// underline appears almost as soon as the word boundary is crossed.
+    private static let spellCheckDebounce: TimeInterval = 0.4
+
+    /// Schedule a (debounced) spell-check pass over the entire document.
+    /// Subsequent calls within the debounce window cancel the previous
+    /// scheduled pass.
+    ///
+    /// The coordinator's `spellMisspelledRanges` cache is assumed to have
+    /// been cleared by the caller (typically `textDidChange`) BEFORE this
+    /// method is invoked — that's what prevents stale-offset underlines
+    /// from painting during the debounce window.
+    func scheduleSpellCheck(textView: NSTextView) {
+        spellCheckWorkItem?.cancel()
+        // On macOS 26+ AppKit's own TextKit 2 pass paints the underline
+        // via the default fragment. Running the engine driver here would
+        // produce double underlines (the system pass + our cache-based
+        // fragment pass).
+        guard #unavailable(macOS 26) else {
+            spellMisspelledRanges.removeAll()
+            return
+        }
+        guard userPrefersContinuousSpellChecking else {
+            // Toggle is off — make sure stale marks aren't left around.
+            clearSpellMisspellings(textView: textView)
+            return
+        }
+        let work = DispatchWorkItem { [weak self, weak textView] in
+            guard let self, let textView else { return }
+            self.runSpellCheckPass(textView: textView)
+        }
+        spellCheckWorkItem = work
+        DispatchQueue.main.asyncAfter(
+            deadline: .now() + Self.spellCheckDebounce,
+            execute: work
+        )
+    }
+
+    /// Run an async full-document scan via `NSSpellChecker.requestChecking`.
+    /// Filters results against the engine's existing zone helpers so code,
+    /// LaTeX, links, and image embeds never end up underlined.
+    func runSpellCheckPass(textView: NSTextView) {
+        guard #unavailable(macOS 26) else { return }
+        guard userPrefersContinuousSpellChecking else {
+            clearSpellMisspellings(textView: textView)
+            return
+        }
+        let string = textView.string
+        let length = (string as NSString).length
+        guard length > 0 else {
+            updateSpellMisspelledRanges([], textView: textView)
+            return
+        }
+
+        let checker = NSSpellChecker.shared
+        let docTag = textView.spellCheckerDocumentTag
+        let wholeDocument = NSRange(location: 0, length: length)
+
+        checker.requestChecking(
+            of: string,
+            range: wholeDocument,
+            types: NSTextCheckingTypes(NSTextCheckingResult.CheckingType.spelling.rawValue),
+            options: [:],
+            inSpellDocumentWithTag: docTag,
+            completionHandler: { [weak self, weak textView] (_ seq: Int, results: [NSTextCheckingResult], _ orthography: NSOrthography, _ wordCount: Int) in
+                guard let self, let textView else { return }
+                let filtered = results.compactMap { result -> NSRange? in
+                    guard result.resultType == .spelling else { return nil }
+                    return self.shouldSuppressSpellMark(range: result.range, in: string)
+                        ? nil
+                        : result.range
+                }
+                self.updateSpellMisspelledRanges(filtered, textView: textView)
+            }
+        )
+    }
+
+    /// Empties the misspelling set and triggers a redraw so any leftover
+    /// underlines disappear immediately. Called synchronously from
+    /// `textDidChange` and from `didToggleSpellCheckingPolicy` (off).
+    func clearSpellMisspellings(textView: NSTextView) {
+        guard !spellMisspelledRanges.isEmpty else { return }
+        updateSpellMisspelledRanges([], textView: textView)
+    }
+
+    /// Replaces the stored set and asks the text view to redraw. The
+    /// fragment's `draw(at:in:)` reads from `spellMisspelledRanges` on
+    /// each repaint, so a simple `needsDisplay = true` is enough — no
+    /// layout invalidation required.
+    private func updateSpellMisspelledRanges(_ ranges: [NSRange], textView: NSTextView) {
+        spellMisspelledRanges = ranges
+        textView.needsDisplay = true
+    }
+
+    /// True when the candidate misspelling falls inside a zone where the
+    /// engine deliberately disables spell marks (code, LaTeX, link, embed).
+    /// Same gates as `NativeTextView+SpellingPolicy`.
+    private func shouldSuppressSpellMark(range: NSRange, in text: String) -> Bool {
+        if text.contains("`"), isInsideCode(range: range, in: text) {
+            return true
+        }
+        if text.contains("$"), isInsideLatex(location: range.location, in: text) {
+            return true
+        }
+        return isInsideSpellcheckSuppressedToken(range: range, in: text)
+    }
+}

Sources/MarkdownEngine/TextView/Coordinator/NativeTextViewCoordinator+TextDelegate.swift

@@ -55,6 +55,11 @@ extension NativeTextViewCoordinator {
         let rawSelRange = tv.selectedRange()
         let fullLength = (tv.string as NSString).length
         guard !tv.hasMarkedText() else { return }
+        // Spell-check fallback: synchronously clear the misspelling cache
+        // so no stale-offset underlines paint during the debounce window.
+        // The next `scheduleSpellCheck` call (at the end of this method)
+        // will recompute fresh ranges once the user stops typing.
+        clearSpellMisspellings(textView: tv)
         let safeLocation = min(rawSelRange.location, fullLength)
         let safeSelRange = NSRange(location: safeLocation, length: 0)
         previousCaretLocation = safeSelRange.location
@@ -155,6 +160,11 @@ extension NativeTextViewCoordinator {
             bottomTextView.recalcOverscroll(for: scrollView, debugTag: "textDidChange")
             (scrollView as? ClampedScrollView)?.clampToInsets()
         }
+        // Spell-check fallback: kick off the debounced scan now that the
+        // edit has settled. The cache is already empty from the top of
+        // this method, so no stale underlines can paint in the 400 ms
+        // window before the async pass completes.
+        scheduleSpellCheck(textView: tv)
         previousActiveTokenIndices = activeTokenIndices
     }