Customizable Gutter

Sources/STTextViewAppKit/Gutter/STGutterView.swift

@@ -38,7 +38,7 @@ open class STGutterView: NSView, NSDraggingSource {
     private var _didMouseDownAddMarker = false
 
     /// Delegate
-    weak var delegate: (any STGutterViewDelegate)?
+    public weak var delegate: (any STGutterViewDelegate)?
 
     /// The font used to draw line numbers.
     ///

Sources/STTextViewAppKit/STGutterLineViewDataSource.swift

@@ -0,0 +1,47 @@
+//  Created by Marcin Krzyzanowski
+//  https://github.com/krzyzanowskim/STTextView/blob/main/LICENSE.md
+
+import AppKit
+
+/// A data source that provides custom views for the gutter area of a text view.
+///
+/// Implement this protocol to supply one `NSView` per visible line in the
+/// custom gutter. The data source is queried during layout for each line
+/// that is currently in the viewport.
+///
+/// Use together with ``STTextView/customGutterWidth`` to reserve horizontal
+/// space for the gutter area.
+public protocol STGutterLineViewDataSource: AnyObject {
+
+    /// Returns the view to display in the custom gutter for the given line.
+    ///
+    /// - Parameters:
+    ///   - textView: The text view requesting the view.
+    ///   - lineNumber: The 1-based line number.
+    ///   - content: The plain-text content of the line (trailing newline stripped).
+    /// - Returns: An `NSView` to be positioned in the gutter alongside the line.
+    func textView(_ textView: STTextView, viewForGutterLine lineNumber: Int, content: String) -> NSView
+
+    /// Attempts to update an existing gutter line view in-place rather than recreating it.
+    ///
+    /// Implement this method to update the content of an already-visible gutter view without
+    /// destroying and recreating it (which is expensive for NSHostingView). If the view cannot
+    /// be updated in-place, return `false` — the caller will fall back to creating a new view.
+    ///
+    /// The default implementation returns `false` (no in-place update).
+    ///
+    /// - Parameters:
+    ///   - textView: The text view requesting the update.
+    ///   - existingView: The view currently displayed for this line.
+    ///   - lineNumber: The 1-based line number.
+    ///   - content: The current plain-text content of the line.
+    /// - Returns: `true` if the view was updated successfully; `false` to trigger recreation.
+    func textView(_ textView: STTextView, updateView existingView: NSView, forGutterLine lineNumber: Int, content: String) -> Bool
+}
+
+public extension STGutterLineViewDataSource {
+    /// Default: no in-place update — caller recreates the view.
+    func textView(_ textView: STTextView, updateView existingView: NSView, forGutterLine lineNumber: Int, content: String) -> Bool {
+        false
+    }
+}

Sources/STTextViewAppKit/STTextView+NSTextViewportLayoutControllerDelegate.swift

@@ -7,7 +7,7 @@ import STTextKitPlus
 extension STTextView: NSTextViewportLayoutControllerDelegate {
 
     public func textViewportLayoutControllerWillLayout(_ textViewportLayoutController: NSTextViewportLayoutController) {
-        lastUsedFragmentViews = Set(fragmentViewMap.objectEnumerator()?.allObjects as? [STTextLayoutFragmentView] ?? [])
+        lastUsedFragments = Set(fragmentViewMap.keyEnumerator().allObjects as! [NSTextLayoutFragment])
 
         if ProcessInfo().environment["ST_LAYOUT_DEBUG"] == "YES" {
             let viewportDebugView = NSView(frame: viewportBounds(for: textViewportLayoutController))
@@ -56,7 +56,7 @@ extension STTextView: NSTextViewportLayoutControllerDelegate {
         if let cachedFragmentView = fragmentViewMap.object(forKey: textLayoutFragment) {
             cachedFragmentView.layoutFragment = textLayoutFragment
             fragmentView = cachedFragmentView
-            lastUsedFragmentViews.remove(cachedFragmentView)
+            lastUsedFragments.remove(textLayoutFragment)
         } else {
             fragmentView = STTextLayoutFragmentView(layoutFragment: textLayoutFragment, frame: layoutFragmentFrame.pixelAligned)
             fragmentViewMap.setObject(fragmentView, forKey: textLayoutFragment)
@@ -79,10 +79,13 @@ extension STTextView: NSTextViewportLayoutControllerDelegate {
     }
 
     public func textViewportLayoutControllerDidLayout(_ textViewportLayoutController: NSTextViewportLayoutController) {
-        for staleView in lastUsedFragmentViews {
-            staleView.removeFromSuperview()
+        for staleFragment in lastUsedFragments {
+            if let view = fragmentViewMap.object(forKey: staleFragment) {
+                view.removeFromSuperview()
+            }
+            fragmentViewMap.removeObject(forKey: staleFragment)
         }
-        lastUsedFragmentViews.removeAll()
+        lastUsedFragments.removeAll()
 
         updateContentSizeIfNeeded()
 

Sources/STTextViewAppKit/STTextView.swift

@@ -378,6 +378,93 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
     /// Gutter view
     public var gutterView: STGutterView?
 
+    /// Extra whitespace inserted above line 1 by pushing text down via an exclusion path.
+    ///
+    /// TextKit 2 prepends `lineSpacing` to lines 2+ but NOT line 1, so without this the first line
+    /// starts at y=0 with no breathing room. An exclusion path at y=0 with height=`topContentInset`
+    /// pushes line 1 down by exactly `lineSpacing`, creating equal whitespace above line 1 as
+    /// between all other lines. This is preferable to `contentInsets.top` because the offset is
+    /// baked into layout itself — no scroll-position dependency (Xcode Preview always snapshots
+    /// at y=0, so a contentInsets approach makes the fix invisible in previews).
+    open var topContentInset: CGFloat = 0 {
+        didSet {
+            if topContentInset > 0 {
+                let exclusionRect = CGRect(x: 0, y: 0, width: 1e6, height: topContentInset)
+                textContainer.exclusionPaths = [NSBezierPath(rect: exclusionRect)]
+            } else {
+                textContainer.exclusionPaths = []
+            }
+            needsLayout = true
+        }
+    }
+
+    /// Fraction of the visible viewport height added as extra scrollable space below the last line.
+    ///
+    /// For example, `0.5` allows the last line to scroll up to the vertical midpoint of the editor
+    /// (half-page overscroll). Set to `0` (the default) to disable overscroll.
+    ///
+    /// The extra space is only appended when the text content already overflows the viewport,
+    /// so short documents that fit entirely on screen are not affected and show no scrollbar.
+    open var overscrollFraction: CGFloat = 0 {
+        didSet {
+            updateContentSizeIfNeeded()
+        }
+    }
+
+    /// Width of the custom gutter area. When greater than 0, ``contentView.frame.origin.x``
+    /// is offset by this amount, allowing custom gutter content without the built-in ``STGutterView``.
+    ///
+    /// Use together with ``gutterLineViewDataSource`` to supply a custom NSView per visible line.
+    /// When the built-in ``gutterView`` is present, its width takes precedence.
+    open var customGutterWidth: CGFloat = 0 {
+        didSet {
+            if customGutterWidth <= 0 {
+                customGutterContainerView?.removeFromSuperview()
+                customGutterContainerView = nil
+            }
+            needsLayout = true
+        }
+    }
+
+    /// A data source that provides custom views for each visible line in the gutter area.
+    ///
+    /// The data source is queried during layout for every line currently in the viewport.
+    /// Set ``customGutterWidth`` to reserve horizontal space for the gutter.
+    ///
+    /// - SeeAlso: ``STGutterLineViewDataSource``
+    open weak var gutterLineViewDataSource: (any STGutterLineViewDataSource)? {
+        didSet {
+            if gutterLineViewDataSource == nil {
+                customGutterContainerView?.removeFromSuperview()
+                customGutterContainerView = nil
+            }
+            needsLayout = true
+        }
+    }
+
+    /// Container view for custom gutter line views (created lazily during layout).
+    /// Access this after the first layout pass to apply additional styling.
+    public internal(set) var customGutterContainerView: NSView?
+
+    /// Background color for the custom gutter area.
+    /// Applied to the container view's backing layer.
+    open var customGutterBackgroundColor: NSColor? {
+        didSet {
+            customGutterContainerView?.layer?.backgroundColor = customGutterBackgroundColor?.cgColor
+        }
+    }
+
+    /// Color of the vertical separator drawn on the trailing edge of the custom gutter.
+    /// Set to `nil` to hide the separator.
+    open var customGutterSeparatorColor: NSColor? {
+        didSet { needsLayout = true }
+    }
+
+    /// Width of the trailing separator line. Default 2.
+    open var customGutterSeparatorWidth: CGFloat = 2 {
+        didSet { needsLayout = true }
+    }
+
     /// The highlight color of the selected line.
     ///
     /// Note: Needs ``highlightSelectedLine`` to be set to `true`
@@ -514,7 +601,7 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
     let selectionView: STSelectionView
 
     var fragmentViewMap: NSMapTable<NSTextLayoutFragment, STTextLayoutFragmentView>
-    var lastUsedFragmentViews: Set<STTextLayoutFragmentView> = []
+    var lastUsedFragments: Set<NSTextLayoutFragment> = []
     private var _usageBoundsForTextContainerObserver: NSKeyValueObservation?
 
     lazy var _speechSynthesizer = AVSpeechSynthesizer()
@@ -967,7 +1054,7 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
     override open var intrinsicContentSize: NSSize {
         // usageBoundsForTextContainer already includes lineFragmentPadding via STTextLayoutManager workaround
         let textSize = textLayoutManager.usageBoundsForTextContainer.size
-        let gutterWidth = gutterView?.frame.width ?? 0
+        let gutterWidth = gutterView?.frame.width ?? customGutterWidth
 
         return NSSize(
             width: textSize.width + gutterWidth,
@@ -1393,7 +1480,7 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
             return
         }
 
-        let gutterWidth = gutterView?.frame.width ?? 0
+        let gutterWidth = gutterView?.frame.width ?? customGutterWidth
         let scrollerInset = proposedSize == nil ? (scrollView?.contentView.contentInsets.right ?? 0) : 0
         let referenceSize = proposedSize ?? effectiveVisibleRect.size
 
@@ -1456,7 +1543,7 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
             return false
         }
 
-        let gutterWidth = gutterView?.frame.width ?? 0
+        let gutterWidth = gutterView?.frame.width ?? customGutterWidth
         var newFrame = CGRect(origin: frame.origin, size: usageBoundsForTextContainerSize)
         newFrame.size.width += gutterWidth
 
@@ -1478,8 +1565,10 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
     override open func setFrameSize(_ newSize: NSSize) {
         super.setFrameSize(newSize)
 
-        // contentView should always fill the entire STTextView
-        contentView.frame.origin.x = gutterView?.frame.width ?? 0
+        // contentView should always fill the entire STTextView.
+        // Built-in gutterView width takes precedence; fall back to customGutterWidth
+        // so that custom gutter views can offset the content without enabling showsLineNumbers.
+        contentView.frame.origin.x = gutterView?.frame.width ?? customGutterWidth
         contentView.frame.size = newSize
 
         updateTextContainerSize(proposedSize: newSize)
@@ -1491,7 +1580,7 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
     }
 
     func updateContentSizeIfNeeded() {
-        let gutterWidth = gutterView?.frame.width ?? 0
+        let gutterWidth = gutterView?.frame.width ?? customGutterWidth
         let scrollerInset = scrollView?.contentView.contentInsets.right ?? 0
 
         var estimatedSize = textLayoutManager.usageBoundsForTextContainer.size
@@ -1522,6 +1611,16 @@ open class STTextView: NSView, NSTextInput, NSTextContent, STTextViewProtocol {
             estimatedSize.width = max(estimatedSize.width, scrollView.contentView.bounds.width - scrollerInset)
         }
 
+        // Apply overscroll: extend document height so the last line can scroll
+        // up to `overscrollFraction` of the viewport height from the top.
+        // Only when text already overflows the viewport — short documents are unaffected.
+        if isVerticallyResizable, overscrollFraction > 0, let scrollView {
+            let viewportHeight = scrollView.contentView.bounds.height
+            if estimatedSize.height > viewportHeight {
+                estimatedSize.height += viewportHeight * overscrollFraction
+            }
+        }
+
         let newFrame = backingAlignedRect(
             CGRect(origin: frame.origin, size: estimatedSize),
             options: .alignAllEdgesOutward