Layout Invalidation Performance (#118)

### Description

Made the layout manager *move* lines that weren't invalidated instead of re-typesetting them. Also made the reuse queue just make views tiny and hide them instead of removing them from the view hierarchy, and queue more views.

After these changes, layout in the source editor goes from taking up *36% of the CPU* time while editing, to taking up **5% of main thread CPU time**.

- Added a new debug mode for visualizing line fragment invalidation.
- Adjusted the layout pass to avoid typesetting lines that don't need layout.
  - Made a distinction between 'forced layout' via `setNeedsLayout` and 'continued' layout where a line previously scanned in the layout pass was updated.
  - Due to that, I was able to check if a line fragment actually needed typesetting or just potentially needed to have it's position adjusted.
  - Added a new method to update a line's view's positions during layout.
- Removed the unnecessary `lineRange` variable on the `LineFragment` class.
- Adjusted the use of `documentRange` on the `LineFragment` class. It's now updated during layout, simplifying various methods.

### Related Issues

* N/A

### Checklist

- [x] I read and understood the [contributing guide](https://github.com/CodeEditApp/CodeEdit/blob/main/CONTRIBUTING.md) as well as the [code of conduct](https://github.com/CodeEditApp/CodeEdit/blob/main/CODE_OF_CONDUCT.md)
- [x] The issues this PR addresses are related to each other
- [x] My changes generate no new warnings
- [x] My code builds and runs on my machine
- [x] My changes are all related to the related issue above
- [x] I documented my code

### Screenshots

Before:

https://github.com/user-attachments/assets/05027712-5690-4970-b1ab-e0b4fe9553ec

After:

https://github.com/user-attachments/assets/36350ea1-66d8-43d0-a676-1bb770a733d7

Author: thecoolwinter

Sources/CodeEditTextView/Extensions/NSRange+/NSRange+translate.swift

@@ -0,0 +1,14 @@
+//
+//  NSRange+translate.swift
+//  CodeEditTextView
+//
+//  Created by Khan Winter on 7/21/25.
+//
+
+import Foundation
+
+extension NSRange {
+    func translate(location: Int) -> NSRange {
+        NSRange(location: self.location + location, length: length)
+    }
+}

Sources/CodeEditTextView/TextLayoutManager/TextLayoutManager+Invalidation.swift

@@ -25,6 +25,12 @@ extension TextLayoutManager {
             linePosition.data.setNeedsLayout()
         }
 
+        // Special case where we've deleted from the very end, `linesInRange` correctly does not return any lines
+        // So we need to invalidate the last line specifically.
+        if range.location == textStorage?.length, !lineStorage.isEmpty {
+            lineStorage.last?.data.setNeedsLayout()
+        }
+
         layoutView?.needsLayout = true
     }
 

Sources/CodeEditTextView/TextLayoutManager/TextLayoutManager+Layout.swift

@@ -79,7 +79,8 @@ extension TextLayoutManager {
         let maxY = max(visibleRect.maxY + verticalLayoutPadding, 0)
         let originalHeight = lineStorage.height
         var usedFragmentIDs = Set<LineFragment.ID>()
-        var forceLayout: Bool = needsLayout
+        let forceLayout: Bool = needsLayout
+        var didLayoutChange = false
         var newVisibleLines: Set<TextLine.ID> = []
         var yContentAdjustment: CGFloat = 0
         var maxFoundLineWidth = maxLineWidth
@@ -95,29 +96,17 @@ extension TextLayoutManager {
             let wasNotVisible = !visibleLineIds.contains(linePosition.data.id)
             let lineNotEntirelyLaidOut = linePosition.height != linePosition.data.lineFragments.height
 
-            if forceLayout || linePositionNeedsLayout || wasNotVisible || lineNotEntirelyLaidOut {
-                let lineSize = layoutLine(
+            defer { newVisibleLines.insert(linePosition.data.id) }
+
+            func fullLineLayout() {
+                let (yAdjustment, wasLineHeightChanged) = layoutLine(
                     linePosition,
+                    usedFragmentIDs: &usedFragmentIDs,
                     textStorage: textStorage,
-                    layoutData: LineLayoutData(minY: minY, maxY: maxY, maxWidth: maxLineLayoutWidth),
-                    laidOutFragmentIDs: &usedFragmentIDs
+                    yRange: minY..<maxY,
+                    maxFoundLineWidth: &maxFoundLineWidth
                 )
-                let wasLineHeightChanged = lineSize.height != linePosition.height
-                if wasLineHeightChanged {
-                    lineStorage.update(
-                        atOffset: linePosition.range.location,
-                        delta: 0,
-                        deltaHeight: lineSize.height - linePosition.height
-                    )
-
-                    if linePosition.yPos < minY {
-                        // Adjust the scroll position by the difference between the new height and old.
-                        yContentAdjustment += lineSize.height - linePosition.height
-                    }
-                }
-                if maxFoundLineWidth < lineSize.width {
-                    maxFoundLineWidth = lineSize.width
-                }
+                yContentAdjustment += yAdjustment
 #if DEBUG
                 laidOutLines.insert(linePosition.data.id)
 #endif
@@ -128,12 +117,24 @@ extension TextLayoutManager {
                 // - New lines being inserted & Lines being deleted (lineNotEntirelyLaidOut)
                 // - Line updated for width change (wasLineHeightChanged)
 
-                forceLayout = forceLayout || wasLineHeightChanged || lineNotEntirelyLaidOut
+                didLayoutChange = didLayoutChange || wasLineHeightChanged || lineNotEntirelyLaidOut
+            }
+
+            if forceLayout || linePositionNeedsLayout || wasNotVisible || lineNotEntirelyLaidOut {
+                fullLineLayout()
             } else {
+                if didLayoutChange || yContentAdjustment > 0 {
+                    // Layout happened and this line needs to be moved but not necessarily re-added
+                    let needsFullLayout = updateLineViewPositions(linePosition)
+                    if needsFullLayout {
+                        fullLineLayout()
+                        continue
+                    }
+                }
+
                 // Make sure the used fragment views aren't dequeued.
                 usedFragmentIDs.formUnion(linePosition.data.lineFragments.map(\.data.id))
             }
-            newVisibleLines.insert(linePosition.data.id)
         }
 
         // Enqueue any lines not used in this layout pass.
@@ -171,14 +172,50 @@ extension TextLayoutManager {
 
     // MARK: - Layout Single Line
 
+    private func layoutLine(
+        _ linePosition: TextLineStorage<TextLine>.TextLinePosition,
+        usedFragmentIDs: inout Set<LineFragment.ID>,
+        textStorage: NSTextStorage,
+        yRange: Range<CGFloat>,
+        maxFoundLineWidth: inout CGFloat
+    ) -> (CGFloat, wasLineHeightChanged: Bool) {
+        let lineSize = layoutLineViews(
+            linePosition,
+            textStorage: textStorage,
+            layoutData: LineLayoutData(minY: yRange.lowerBound, maxY: yRange.upperBound, maxWidth: maxLineLayoutWidth),
+            laidOutFragmentIDs: &usedFragmentIDs
+        )
+        let wasLineHeightChanged = lineSize.height != linePosition.height
+        var yContentAdjustment: CGFloat = 0.0
+        var maxFoundLineWidth = maxFoundLineWidth
+
+        if wasLineHeightChanged {
+            lineStorage.update(
+                atOffset: linePosition.range.location,
+                delta: 0,
+                deltaHeight: lineSize.height - linePosition.height
+            )
+
+            if linePosition.yPos < yRange.lowerBound {
+                // Adjust the scroll position by the difference between the new height and old.
+                yContentAdjustment += lineSize.height - linePosition.height
+            }
+        }
+        if maxFoundLineWidth < lineSize.width {
+            maxFoundLineWidth = lineSize.width
+        }
+
+        return (yContentAdjustment, wasLineHeightChanged)
+    }
+
     /// Lays out a single text line.
     /// - Parameters:
     ///   - position: The line position from storage to use for layout.
     ///   - textStorage: The text storage object to use for text info.
     ///   - layoutData: The information required to perform layout for the given line.
     ///   - laidOutFragmentIDs: Updated by this method as line fragments are laid out.
     /// - Returns: A `CGSize` representing the max width and total height of the laid out portion of the line.
-    private func layoutLine(
+    private func layoutLineViews(
         _ position: TextLineStorage<TextLine>.TextLinePosition,
         textStorage: NSTextStorage,
         layoutData: LineLayoutData,
@@ -226,8 +263,13 @@ extension TextLayoutManager {
 //        ) {
         for lineFragmentPosition in line.lineFragments {
             let lineFragment = lineFragmentPosition.data
+            lineFragment.documentRange = lineFragmentPosition.range.translate(location: position.range.location)
 
-            layoutFragmentView(for: lineFragmentPosition, at: position.yPos + lineFragmentPosition.yPos)
+            layoutFragmentView(
+                inLine: position,
+                for: lineFragmentPosition,
+                at: position.yPos + lineFragmentPosition.yPos
+            )
 
             width = max(width, lineFragment.width)
             height += lineFragment.scaledHeight
@@ -244,16 +286,32 @@ extension TextLayoutManager {
     ///   - lineFragment: The line fragment position to lay out a view for.
     ///   - yPos: The y value at which the line should begin.
     private func layoutFragmentView(
+        inLine line: TextLineStorage<TextLine>.TextLinePosition,
         for lineFragment: TextLineStorage<LineFragment>.TextLinePosition,
         at yPos: CGFloat
     ) {
+        let fragmentRange = lineFragment.range.translate(location: line.range.location)
         let view = viewReuseQueue.getOrCreateView(forKey: lineFragment.data.id) {
             renderDelegate?.lineFragmentView(for: lineFragment.data) ?? LineFragmentView()
         }
         view.translatesAutoresizingMaskIntoConstraints = true // Small optimization for lots of subviews
-        view.setLineFragment(lineFragment.data, renderer: lineFragmentRenderer)
+        view.setLineFragment(lineFragment.data, fragmentRange: fragmentRange, renderer: lineFragmentRenderer)
         view.frame.origin = CGPoint(x: edgeInsets.left, y: yPos)
         layoutView?.addSubview(view, positioned: .below, relativeTo: nil)
         view.needsDisplay = true
     }
+
+    private func updateLineViewPositions(_ position: TextLineStorage<TextLine>.TextLinePosition) -> Bool {
+        let line = position.data
+        for lineFragmentPosition in line.lineFragments {
+            guard let view = viewReuseQueue.getView(forKey: lineFragmentPosition.data.id) else {
+                return true
+            }
+            lineFragmentPosition.data.documentRange = lineFragmentPosition.range.translate(
+                location: position.range.location
+            )
+            view.frame.origin = CGPoint(x: edgeInsets.left, y: position.yPos + lineFragmentPosition.yPos)
+        }
+        return false
+    }
 }

Sources/CodeEditTextView/TextLayoutManager/TextLayoutManager+Public.swift

@@ -112,12 +112,13 @@ extension TextLayoutManager {
         fragmentPosition: TextLineStorage<LineFragment>.TextLinePosition,
         in linePosition: TextLineStorage<TextLine>.TextLinePosition
     ) -> Int? {
-        let endPosition = fragmentPosition.data.documentRange.max
+        let fragmentRange = fragmentPosition.range.translate(location: linePosition.range.location)
+        let endPosition = fragmentRange.max
 
         // If the endPosition is at the end of the line, and the line ends with a line ending character
         // return the index before the eol.
         if fragmentPosition.index == linePosition.data.lineFragments.count - 1,
-           let lineEnding = LineEnding(line: textStorage?.substring(from: fragmentPosition.data.documentRange) ?? "") {
+           let lineEnding = LineEnding(line: textStorage?.substring(from: fragmentRange) ?? "") {
             return endPosition - lineEnding.length
         } else if fragmentPosition.index != linePosition.data.lineFragments.count - 1 {
             // If this isn't the last fragment, we want to place the cursor at the offset right before the break
@@ -175,7 +176,7 @@ extension TextLayoutManager {
         guard let fragmentPosition = linePosition.data.typesetter.lineFragments.getLine(
             atOffset: offset - linePosition.range.location
         ) else {
-            return nil
+            return CGRect(x: edgeInsets.left, y: linePosition.yPos, width: 0, height: linePosition.height)
         }
 
         // Get the *real* length of the character at the offset. If this is a surrogate pair it'll return the correct
@@ -190,11 +191,11 @@ extension TextLayoutManager {
 
         let minXPos = characterXPosition(
             in: fragmentPosition.data,
-            for: realRange.location - fragmentPosition.data.documentRange.location
+            for: realRange.location - linePosition.range.location - fragmentPosition.range.location
         )
         let maxXPos = characterXPosition(
             in: fragmentPosition.data,
-            for: realRange.max - fragmentPosition.data.documentRange.location
+            for: realRange.max - linePosition.range.location - fragmentPosition.range.location
         )
 
         return CGRect(

Sources/CodeEditTextView/TextLine/LineFragment.swift

@@ -47,8 +47,7 @@ public final class LineFragment: Identifiable, Equatable {
     }
 
     public let id = UUID()
-    public let lineRange: NSRange
-    public let documentRange: NSRange
+    public var documentRange: NSRange = .notFound
     public var contents: [FragmentContent]
     public var width: CGFloat
     public var height: CGFloat
@@ -61,16 +60,12 @@ public final class LineFragment: Identifiable, Equatable {
     }
 
     init(
-        lineRange: NSRange,
-        documentRange: NSRange,
         contents: [FragmentContent],
         width: CGFloat,
         height: CGFloat,
         descent: CGFloat,
         lineHeightMultiplier: CGFloat
     ) {
-        self.lineRange = lineRange
-        self.documentRange = documentRange
         self.contents = contents
         self.width = width
         self.height = height

Sources/CodeEditTextView/TextLine/LineFragmentRenderer.swift

@@ -122,7 +122,7 @@ public final class LineFragmentRenderer {
             context: context
         )
 
-        let range = createTextRange(for: drawingContext)
+        let range = createTextRange(for: drawingContext).clamped(to: (textStorage.string as NSString).length)
         let string = (textStorage.string as NSString).substring(with: range)
 
         processInvisibleCharacters(
@@ -177,7 +177,7 @@ public final class LineFragmentRenderer {
         guard let style = delegate.invisibleStyle(
             for: character,
             at: NSRange(start: range.location + index, end: range.max),
-            lineRange: drawingContext.lineFragment.lineRange
+            lineRange: drawingContext.lineFragment.documentRange
         ) else {
             return
         }

Sources/CodeEditTextView/TextLine/LineFragmentView.swift

@@ -11,6 +11,9 @@ import AppKit
 open class LineFragmentView: NSView {
     public weak var lineFragment: LineFragment?
     public weak var renderer: LineFragmentRenderer?
+#if DEBUG_LINE_INVALIDATION
+    private var backgroundAnimation: CABasicAnimation?
+#endif
 
     open override var isFlipped: Bool {
         true
@@ -22,15 +25,55 @@ open class LineFragmentView: NSView {
 
     open override func hitTest(_ point: NSPoint) -> NSView? { nil }
 
-    /// Prepare the view for reuse, clears the line fragment reference.
+    public override init(frame frameRect: NSRect) {
+        super.init(frame: frameRect)
+    }
+
+    required public init?(coder: NSCoder) {
+        super.init(coder: coder)
+    }
+
+#if DEBUG_LINE_INVALIDATION
+    /// Setup background animation from random color to clear when this fragment is invalidated.
+    private func setupBackgroundAnimation() {
+        self.wantsLayer = true
+
+        let randomColor = NSColor(
+            red: CGFloat.random(in: 0...1),
+            green: CGFloat.random(in: 0...1),
+            blue: CGFloat.random(in: 0...1),
+            alpha: 0.3
+        )
+
+        self.layer?.backgroundColor = randomColor.cgColor
+
+        let animation = CABasicAnimation(keyPath: "backgroundColor")
+        animation.fromValue = randomColor.cgColor
+        animation.toValue = NSColor.clear.cgColor
+        animation.duration = 1.0
+        animation.timingFunction = CAMediaTimingFunction(name: .easeOut)
+        animation.fillMode = .forwards
+        animation.isRemovedOnCompletion = false
+        self.layer?.add(animation, forKey: "backgroundColorAnimation")
+
+        DispatchQueue.main.asyncAfter(deadline: .now() + animation.duration) {
+            self.layer?.backgroundColor = NSColor.clear.cgColor
+        }
+    }
+#endif
+
     open override func prepareForReuse() {
         super.prepareForReuse()
         lineFragment = nil
+
+#if DEBUG_LINE_INVALIDATION
+        setupBackgroundAnimation()
+#endif
     }
 
     /// Set a new line fragment for this view, updating view size.
     /// - Parameter newFragment: The new fragment to use.
-    open func setLineFragment(_ newFragment: LineFragment, renderer: LineFragmentRenderer) {
+    open func setLineFragment(_ newFragment: LineFragment, fragmentRange: NSRange, renderer: LineFragmentRenderer) {
         self.lineFragment = newFragment
         self.renderer = renderer
         self.frame.size = CGSize(width: newFragment.width, height: newFragment.scaledHeight)

Sources/CodeEditTextView/TextLine/TextLine.swift

@@ -36,8 +36,6 @@ public final class TextLine: Identifiable, Equatable {
             // Both max widths we're comparing are finite
             maxWidth.isFinite
             && (self.maxWidth ?? 0.0).isFinite
-            // We can't use `<` here because we want to calculate layout again if this was previously constrained to a
-            // small layout size and needs to grow.
             && maxWidth != (self.maxWidth ?? 0.0)
         )
     }
@@ -57,14 +55,14 @@ public final class TextLine: Identifiable, Equatable {
         attachments: [AnyTextAttachment]
     ) {
         let string = stringRef.attributedSubstring(from: range)
-        self.maxWidth = displayData.maxWidth
-        typesetter.typeset(
+        let maxWidth = typesetter.typeset(
             string,
             documentRange: range,
             displayData: displayData,
             markedRanges: markedRanges,
             attachments: attachments
         )
+        self.maxWidth = displayData.maxWidth
         needsLayout = false
     }
 

Sources/CodeEditTextView/TextLine/Typesetter/TypesetContext.swift

@@ -61,11 +61,6 @@ struct TypesetContext {
     /// Pop the current fragment state into a new line fragment, and reset the fragment state.
     mutating func popCurrentData() {
         let fragment = LineFragment(
-            lineRange: documentRange,
-            documentRange: NSRange(
-                location: fragmentContext.start + documentRange.location,
-                length: currentPosition - fragmentContext.start
-            ),
             contents: fragmentContext.contents,
             width: fragmentContext.width,
             height: fragmentContext.height,