Fix scroll jitter during text selection

Optimize scroll-to-selection logic in layout() to avoid unnecessary
viewport jumps:
- Skip scrolling if selection already intersects visible viewport
- Scroll to nearest selection edge instead of entire range
- Extract adjustedScrollRect() to deduplicate gutter-aware rect logic

Based on PR krzyzanowskim#108 by brandonbloom.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ruslanhirychau

Sources/STTextViewAppKit/STTextView+Scrolling.swift

@@ -10,44 +10,42 @@ extension STTextView {
         contentView.scroll(point.applying(.init(translationX: -(gutterView?.frame.width ?? 0), y: 0)))
     }
 
+    /// Adjusts a rect for scrolling by adding line fragment padding and gutter offset.
+    private func adjustedScrollRect(_ rect: CGRect) -> CGRect {
+        var adjusted = rect
+        if adjusted.width.isZero {
+            adjusted = adjusted.inset(by: .init(top: 0, left: -textContainer.lineFragmentPadding, bottom: 0, right: -textContainer.lineFragmentPadding))
+        }
+        adjusted.origin.x -= gutterView?.frame.width ?? 0
+        adjusted.size.width += gutterView?.frame.width ?? 0
+        return adjusted
+    }
+
     @discardableResult
     func scrollToVisible(_ textRange: NSTextRange, type: NSTextLayoutManager.SegmentType) -> Bool {
-        guard var rect = textLayoutManager.textSegmentFrame(in: textRange, type: type) else {
+        guard let rect = textLayoutManager.textSegmentFrame(in: textRange, type: type) else {
             return false
         }
+        return contentView.scrollToVisible(adjustedScrollRect(rect))
+    }
 
-        if rect.width.isZero {
-            // add padding around the point to ensure the visibility the segment
-            // since the width of the segment is 0 for a selection
-            rect = rect.inset(by: .init(top: 0, left: -textContainer.lineFragmentPadding, bottom: 0, right: -textContainer.lineFragmentPadding))
+    @discardableResult
+    func scrollToVisible(_ location: NSTextLocation, type: NSTextLayoutManager.SegmentType) -> Bool {
+        guard let rect = textLayoutManager.textSegmentFrame(at: location, type: type) else {
+            return false
         }
-
-        // scroll to visible IN clip view (ignoring gutter view overlay)
-        // adjust rect to mimick it's size to include gutter overlay
-        rect.origin.x -= gutterView?.frame.width ?? 0
-        rect.size.width += gutterView?.frame.width ?? 0
-        return contentView.scrollToVisible(rect)
+        return contentView.scrollToVisible(adjustedScrollRect(rect))
     }
 
     override open func centerSelectionInVisibleArea(_ sender: Any?) {
         guard let selectionTextRange = textLayoutManager.textSelections.last?.textRanges.last,
-              var rect = textLayoutManager.textSegmentFrame(in: selectionTextRange, type: .selection) else {
+              let rect = textLayoutManager.textSegmentFrame(in: selectionTextRange, type: .selection) else {
             return
         }
 
-        if rect.width.isZero {
-            // add padding around the point to ensure the visibility the segment
-            // since the width of the segment is 0 for a selection
-            rect = rect.inset(by: .init(top: 0, left: -textContainer.lineFragmentPadding, bottom: 0, right: -textContainer.lineFragmentPadding))
-        }
-
-        // scroll to visible IN clip view (ignoring gutter view overlay)
-        // adjust rect to mimick it's size to include gutter overlay
-        rect.origin.x -= gutterView?.frame.width ?? 0
-        rect.size.width += gutterView?.frame.width ?? 0
-
+        let adjusted = adjustedScrollRect(rect)
         // put rect origin in the center
-        contentView.scroll(rect.origin.applying(.init(translationX: 0, y: -visibleRect.height / 2)))
+        contentView.scroll(adjusted.origin.applying(.init(translationX: 0, y: -visibleRect.height / 2)))
     }
 
     override open func pageUp(_ sender: Any?) {

Sources/STTextViewAppKit/STTextView.swift

@@ -1340,12 +1340,39 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
         layoutText()
 
         if needsScrollToSelection, let textRange = textLayoutManager.textSelections.last?.textRanges.last {
-            scrollToVisible(textRange, type: .standard)
+            if let scrollLocation = textLocationForScrollingSelection(toVisible: textRange) {
+                scrollToVisible(scrollLocation, type: .standard)
+            }
         }
 
         needsScrollToSelection = false
     }
 
+    /// Determines the optimal text location to scroll to for making a selection visible.
+    /// Returns nil if the selection is already visible, avoiding unnecessary scrolling.
+    /// When scrolling is needed, returns the nearest edge of the selection to minimize viewport disruption.
+    private func textLocationForScrollingSelection(toVisible textRange: NSTextRange) -> NSTextLocation? {
+        guard let selectionRect = textLayoutManager.textSegmentFrame(in: textRange, type: .standard) else {
+            return nil
+        }
+
+        let viewportRect = contentView.documentVisibleRect
+
+        // If the selection already intersects the viewport, no scroll needed
+        if viewportRect.intersects(selectionRect) {
+            return nil
+        }
+
+        // Scroll to the nearest edge of the selection
+        if selectionRect.minY < viewportRect.minY {
+            // Selection is above viewport — scroll to the start
+            return textRange.location
+        } else {
+            // Selection is below viewport — scroll to the end
+            return textRange.endLocation
+        }
+    }
+
     /// Performs text layout including container sizing, viewport layout, and related updates.
     private func layoutText() {
         guard shouldUpdateLayout else { return }