wip: TextKit 2 fragment redraw issue on insert (diagnostics included)

This commit folds two iterations together:
1. Remove `textView.isContinuousSpellCheckingEnabled = false` toggle
   that caused a recursive textDidChange cascade.
2. Add `[SC]` diagnostic prints + try four fragment-redraw strategies
   to fix the on-insert underline disappearance — none worked.

--- Part 1: recursive cascade fix (kept) ---

Setting `textView.isContinuousSpellCheckingEnabled = false` in
`scheduleSpellCheck` caused a recursive cascade on macOS 15.x:
  1. AppKit synchronously clears `.spellingState` attributes
  2. Attribute change triggers `textDidChange` delegate
  3. `textDidChange` calls `clearSpellMisspellings` (cache empty) +
     `scheduleSpellCheck` (cancels the current debounced pass)
  4. Original work item is cancelled before it fires.

Deletion masked the bug because by the time the user deletes, the
flag is already false, so re-setting is a no-op — no recursive
trigger. Insert reliably reproduced it on the first keystroke after
mount.

The system's own continuous spell-check pass is now left enabled.
On macOS 15.x it paints on the default fragment (which our custom
`MarkdownTextLayoutFragment` replaces), so its `.spellingState`
underlines are invisible. Our cache-based drawing in
`drawSpellMisspellings` is the sole visible painter.

This change is independent of the redraw issue described below;
even after removing it, the on-insert disappearance still occurs.

--- Part 2: redraw issue (still open) ---

Symptom on macOS 15.7.7:
- Open a note with misspellings -> underlines drawn correctly on
  initial layout.
- Type any character -> all underlines disappear and never come back
  until something forces a full layout re-run (panel show/hide,
  select-all, big scroll, etc.).
- Delete a character -> underlines blink and reappear after the
  400 ms debounce (works correctly).
- The 400 ms-debounced spell-check pipeline itself is verified
  correct via `[SC]` diagnostic prints (left in for maintainer
  review):
    textDidChange -> update was=N now=0 -> schedule -> run -> done -> update was=0 now=N
  The cache `spellMisspelledRanges` repopulates with the right count
  after every keystroke. NSSpellChecker returns the same ranges as
  before the edit.

Root-cause hypothesis:
TextKit 2 maintains a per-fragment rendering cache. After an
insert, only the edited paragraph's fragments redraw on the next
display pass; the other fragments containing misspellings reuse
their pre-update imagery (no underlines) even though
`coordinator.spellMisspelledRanges` is correct.

Attempted fixes (all rebuilt and tested — none worked for insert):
  1. `textView.needsDisplay = true` (original) -> only edited
     fragment redraws.
  2. `setNeedsDisplay(fragment.layoutFragmentFrame)` per
     overlapping fragment -> rect goes stale during typing bursts
     as fragments shift.
  3. `tlm.invalidateRenderingAttributes(for: textRange)` per
     misspelled range -> silently no-ops; no `draw(at:in:)`
     follows.
  4. `tlm.invalidateLayout(for: textRange)` per misspelled range
     -> only the range overlapping the edited fragment redraws
     (e.g. {349,7} drawing 54 times in our log); other fragments
     still reuse cached imagery.

In all four attempts, the diagnostic confirms
`coordinator.spellMisspelledRanges` is correctly repopulated; the
failure is purely in the redraw pipeline.

Diagnostics added (kept for maintainer review):
- NativeTextViewCoordinator+TextDelegate.swift:
    `[SC] textDidChange:` entry
- NativeTextViewCoordinator+SpellCheck.swift:
    `[SC] schedule:` (queued / toggle-off-clearing)
    `[SC] run: start | empty | done rawHits=N kept=N tag=T`
    `[SC] update: was=N now=N`
- MarkdownTextLayoutFragment.swift:
    `[SC] draw frag={loc,len} cacheCount=N`

Repro recipe:
1. Build EdgeMark (or any TextKit 2 host) against this branch on
   macOS 15.x.
2. Run with Console filtered by `[SC]`.
3. Open a note with several misspellings spread across paragraphs.
4. Insert one character; observe `[SC] update: was=0 now=N`
   followed by draws covering only the edited fragment (and
   possibly the prev paragraph from restyle scope), not the
   fragments holding the other misspellings. Visually all
   underlines vanish.
5. Select-all (or hide/show side panel). Logs show all relevant
   fragments redraw; underlines reappear.

Open question for engine authors:
Is there a TextKit 2 invalidation API that reliably forces
fragments overlapping an arbitrary document range to re-execute
`draw(at:in:)` without re-laying out (which would clobber the
styler's `.spellingState: 0` stamps the styler just put down)? Or
is the recommended pattern to drive fragment redraw via
`setRenderingAttributes` (and have the spell-check underline live
as a rendering attribute rather than custom drawing)?

Local SPM dependency note:
This branch is being iterated against EdgeMark via a local SPM
path (`XCLocalSwiftPackageReference`); no Package.resolved pin
needed.

Author: Ender-Wang

Sources/MarkdownEngine/Renderer/MarkdownTextLayoutFragment.swift

@@ -628,6 +628,7 @@ final class MarkdownTextLayoutFragment: NSTextLayoutFragment {
         guard let fragRange = fragmentNSRange, fragRange.length > 0 else { return }
         let fragStart = fragRange.location
         let fragEnd = NSMaxRange(fragRange)
+        print("[SC] draw frag={\(fragStart),\(fragRange.length)} cacheCount=\(coordinator.spellMisspelledRanges.count)")
 
         let theme = textView.configuration.theme
         NSGraphicsContext.saveGraphicsState()

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

@@ -11,15 +11,16 @@
 //  `MarkdownTextLayoutFragment.draw(at:in:)`.
 //
 //  Design (see devlog-0610-spellcheck-15x-fallback-design.md):
-//  - Synchronous `checkSpelling(of:startingAt:)` walk on a background
-//    queue — deterministic, no unreliable completion handlers.
+//  - Synchronous `checkSpelling(of:startingAt:)` walk on the main
+//    thread — deterministic, no background-queue data races.
 //  - 400 ms debounce. Cache is cleared **synchronously** on every
 //    `textDidChange` before the next pass is scheduled, so the stale-
 //    offset bug class never surfaces.
-//  - System's own continuous-spell-check pass is disabled on 15.x so it
-//    can't race with the engine's driver (the unreliable underlines that
-//    sometimes appeared after selection changes were from the system's
-//    pass, not ours).
+//  - The system's own continuous spell-check pass is left enabled.
+//    On macOS 15.x it paints on the default fragment (which our custom
+//    fragment replaces), so it can't interfere with our cache-based
+//    drawing. Disabling it was tried and caused a recursive
+//    textDidChange cascade that cancelled the debounced pass.
 //  - Reuses existing zone helpers (`isInsideCode`, `isInsideLatex`,
 //    `isInsideSpellcheckSuppressedToken`) — same gates as
 //    `NativeTextView+SpellingPolicy`. Belt-and-suspenders with the
@@ -58,16 +59,21 @@ extension NativeTextViewCoordinator {
         }
         guard userPrefersContinuousSpellChecking else {
             // Toggle is off — make sure stale marks aren't left around.
+            print("[SC] schedule: toggle OFF, clearing")
             clearSpellMisspellings(textView: textView)
             return
         }
-        // Disable the system's own continuous spell-check pass on 15.x
-        // so it can't race with the engine's driver. On macOS 15.7.7 the
-        // system's pass paints `.spellingState` unreliably (sometimes
-        // after mount, sometimes after selection, rarely after edits),
-        // producing the inconsistent underlines reported in testing.
-        // The engine is the sole painter on 15.x.
-        textView.isContinuousSpellCheckingEnabled = false
+        print("[SC] schedule: queued, len=\((textView.string as NSString).length)")
+        // NOTE: the system's own continuous spell-check pass is left
+        // enabled. On macOS 15.x it paints on the default fragment
+        // (which our custom MarkdownTextLayoutFragment replaces), so
+        // its `.spellingState` underlines are invisible. Our cache-
+        // based drawing in drawSpellMisspellings is the sole visible
+        // painter. Disabling the system pass via
+        // `textView.isContinuousSpellCheckingEnabled = false` was tried
+        // but caused a recursive textDidChange cascade (AppKit clears
+        // .spellingState attributes synchronously, which triggers a
+        // delegate call that cancels the debounced pass).
         let work = DispatchWorkItem { [weak self, weak textView] in
             guard let self, let textView else { return }
             self.runSpellCheckPass(textView: textView)
@@ -101,13 +107,16 @@ extension NativeTextViewCoordinator {
     func runSpellCheckPass(textView: NSTextView) {
         guard #unavailable(macOS 26) else { return }
         guard userPrefersContinuousSpellChecking else {
+            print("[SC] run: toggle OFF")
             clearSpellMisspellings(textView: textView)
             return
         }
         let string = textView.string
         let ns = string as NSString
         let length = ns.length
+        print("[SC] run: start len=\(length)")
         guard length > 0 else {
+            print("[SC] run: empty doc")
             updateSpellMisspelledRanges([], textView: textView)
             return
         }
@@ -118,6 +127,7 @@ extension NativeTextViewCoordinator {
         // Synchronous walk on the main thread — avoids all threading
         // issues with NSTextView.string and the parsedDocument cache.
         var misspelledRanges: [NSRange] = []
+        var rawHits = 0
         var searchStart = 0
         while searchStart < length {
             let misspelled = checker.checkSpelling(
@@ -129,11 +139,13 @@ extension NativeTextViewCoordinator {
                 wordCount: nil
             )
             guard misspelled.location != NSNotFound else { break }
+            rawHits += 1
             if !shouldSuppressSpellMark(range: misspelled, in: string) {
                 misspelledRanges.append(misspelled)
             }
             searchStart = NSMaxRange(misspelled)
         }
+        print("[SC] run: done rawHits=\(rawHits) kept=\(misspelledRanges.count) tag=\(docTag)")
         updateSpellMisspelledRanges(misspelledRanges, textView: textView)
     }
 
@@ -145,12 +157,42 @@ extension NativeTextViewCoordinator {
         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.
+    /// Replaces the stored set and forces every fragment overlapping an
+    /// affected range to re-execute its draw. `textView.needsDisplay = true`
+    /// alone is insufficient on macOS 15.x because TextKit 2 maintains
+    /// per-fragment rendering caches: a paragraph that wasn't restyled or
+    /// re-laid-out simply re-blits its old imagery, so newly-discovered
+    /// misspellings outside the edited paragraph never paint until
+    /// something forces a full re-layout (panel show/hide, selection
+    /// change, etc.).
+    ///
+    /// `invalidateRenderingAttributes(for:)` is too soft — the layout
+    /// manager treats it as a hint and may silently no-op when no
+    /// rendering-attribute spans actually changed in the range. We saw
+    /// this in repro logs: the call returned, no `draw(at:in:)` followed,
+    /// and underlines stayed gone until a selection change forced a
+    /// fresh display pass.
+    ///
+    /// `invalidateLayout(for:)` always busts the fragment's drawing
+    /// cache and re-runs `draw(at:in:)` on the next display tick. Layout
+    /// re-runs only over the small misspelling ranges, so cost is
+    /// bounded. We pair it with `textView.needsDisplay = true` so the
+    /// containing view actually schedules the next display pass.
     private func updateSpellMisspelledRanges(_ ranges: [NSRange], textView: NSTextView) {
+        print("[SC] update: was=\(spellMisspelledRanges.count) now=\(ranges.count)")
+        let previous = spellMisspelledRanges
         spellMisspelledRanges = ranges
+
+        guard let tlm = textView.textLayoutManager,
+              let tcs = tlm.textContentManager as? NSTextContentStorage else {
+            textView.needsDisplay = true
+            return
+        }
+
+        for nsRange in (previous + ranges) where nsRange.length > 0 {
+            guard let textRange = TextStylingService.textRange(from: nsRange, in: tcs) else { continue }
+            tlm.invalidateLayout(for: textRange)
+        }
         textView.needsDisplay = true
     }
 

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

@@ -59,6 +59,9 @@ extension NativeTextViewCoordinator {
         // 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.
+        let editedLen = tv.textStorage?.editedRange.length ?? 0
+        let editedLoc = tv.textStorage?.editedRange.location ?? -1
+        print("[SC] textDidChange: editedRange={\(editedLoc),\(editedLen)} fullLen=\(fullLength) hasMarked=\(tv.hasMarkedText())")
         clearSpellMisspellings(textView: tv)
         let safeLocation = min(rawSelRange.location, fullLength)
         let safeSelRange = NSRange(location: safeLocation, length: 0)