Add adaptive text layout preparation

Author: cavs1910

README.md

@@ -6,9 +6,9 @@
 
 CodeViewerKit is a minimal, read-only source-code viewer for SwiftUI on iOS,
 iPadOS, and macOS. It uses native TextKit views for selection and scrolling,
-with viewport-based layout instead of rendering a complete document as one
-SwiftUI `Text` value. Noncontiguous layout keeps distant jumps through very
-large files responsive on every supported platform.
+with viewport-based layout by default instead of rendering a complete document
+as one SwiftUI `Text` value. Noncontiguous layout keeps distant jumps through
+very large files responsive on every supported platform.
 
 ## Features
 
@@ -18,7 +18,7 @@ large files responsive on every supported platform.
 - Menlo with a monospaced system fallback;
 - native selection and horizontal and vertical scrolling;
 - Command-Plus and Command-Minus font scaling;
-- sparse, viewport-driven layout on iOS, iPadOS, and macOS;
+- configurable progressive, complete, or size-adaptive native text layout;
 - shared highlighting cache for navigation-heavy apps.
 
 ## Requirements
@@ -170,6 +170,32 @@ CodeViewer(
 On macOS, each legacy scrollbar is hidden automatically when the content fits
 along its axis.
 
+### Layout preparation
+
+Layout is automatic by default: sources up to 64,000 UTF-16 code units receive
+complete layout, while larger sources remain progressive so distant jumps do
+not synchronously typeset every intervening line. Progressive layout can refine
+the scrollbar extent the first time a previously unlaid range becomes visible.
+
+Use complete layout when an exact initial scrollbar extent is more important
+than the up-front layout cost. Automatic mode lets the application choose that
+tradeoff by the source's UTF-16 length, which is the native `NSTextStorage`
+unit:
+
+```swift
+CodeViewer(
+    documentID: "adaptive-layout",
+    sourceCode: source,
+    highlightStore: highlights,
+    lineWrapping: .word,
+    layoutPreparation: .automatic(maximumUTF16Length: 64_000)
+)
+```
+
+Sources at or below the configured limit receive complete layout. Larger
+sources keep progressive, viewport-driven layout. Pass `.complete` or
+`.progressive` to select either behavior without a size threshold.
+
 The viewer is visually neutral: apply your own frame, material, or Liquid Glass
 container around it. Source ranges without a syntax color use black in light
 mode and white in dark mode; override that fallback with `plainTextColor`:

Sources/CodeViewerKit/CodeLayoutPreparation.swift

@@ -0,0 +1,35 @@
+/// Controls how much native text layout `CodeViewer` prepares before scrolling.
+public enum CodeLayoutPreparation: Hashable, Sendable {
+    /// The UTF-16 threshold used by `CodeViewer` when no explicit layout
+    /// preparation policy is supplied.
+    public static let defaultAutomaticMaximumUTF16Length = 64_000
+
+    /// Lays out visible ranges on demand. This is the default and keeps very
+    /// large documents responsive, but the scroll extent can be refined as
+    /// previously unlaid ranges become visible.
+    case progressive
+
+    /// Lays out the complete document once the native text container has a
+    /// usable width. This produces an exact initial scroll extent, but can
+    /// block the main thread for large documents.
+    case complete
+
+    /// Uses complete layout when the document's UTF-16 length is at or below
+    /// `maximumUTF16Length`, and progressive layout otherwise.
+    ///
+    /// Negative limits are treated as zero.
+    case automatic(maximumUTF16Length: Int)
+}
+
+extension CodeLayoutPreparation {
+    func preparesCompleteLayout(forUTF16Length length: Int) -> Bool {
+        switch self {
+        case .progressive:
+            false
+        case .complete:
+            true
+        case let .automatic(maximumUTF16Length):
+            length <= max(0, maximumUTF16Length)
+        }
+    }
+}

Sources/CodeViewerKit/CodeTextView.swift

@@ -20,6 +20,7 @@ struct CodeTextView: View {
     let text: String
     let plainTextColor: Color
     let lineWrapping: CodeLineWrapping
+    let layoutPreparation: CodeLayoutPreparation
     let highlightLanguage: CodeLanguage
     let highlightAppearance: CodeHighlightAppearance
     let highlightBatches: [CodeHighlightBatch]
@@ -34,6 +35,7 @@ struct CodeTextView: View {
                 plainTextColor: plainTextColor,
                 fontSize: fontSize,
                 lineWrapping: lineWrapping,
+                layoutPreparation: layoutPreparation,
                 highlightLanguage: highlightLanguage,
                 highlightAppearance: highlightAppearance,
                 highlightBatches: highlightBatches
@@ -104,6 +106,7 @@ private struct CodeTextRenderRequest {
     let plainTextColor: Color
     let fontSize: CGFloat
     let lineWrapping: CodeLineWrapping
+    let layoutPreparation: CodeLayoutPreparation
     let highlightLanguage: CodeLanguage
     let highlightAppearance: CodeHighlightAppearance
     let highlightBatches: [CodeHighlightBatch]
@@ -327,6 +330,31 @@ private struct CodeTextPreparedUpdate {
     let lineCount: Int
 }
 
+private struct CodeCompleteLayoutKey: Equatable {
+    let generation: Int
+    let containerWidth: CGFloat
+}
+
+@MainActor
+enum CodeNativeLayoutPreparation {
+    @discardableResult
+    static func prepare(
+        _ preparation: CodeLayoutPreparation,
+        layoutManager: NSLayoutManager,
+        textContainer: NSTextContainer
+    ) -> Bool {
+        let textLength = layoutManager.textStorage?.length ?? 0
+        guard preparation.preparesCompleteLayout(
+            forUTF16Length: textLength
+        ) else { return false }
+
+        layoutManager.ensureLayout(
+            forCharacterRange: NSRange(location: 0, length: textLength)
+        )
+        return true
+    }
+}
+
 private extension CodeTextDocumentState {
     mutating func prepareUpdate(
         for request: CodeTextRenderRequest
@@ -454,6 +482,9 @@ private final class MacCodeTextContainer: NSView {
     private let gutterUpdates = CodeGutterUpdateCoordinator()
     private var lastAppliedHighlightSequence = -1
     private var lineWrapping: CodeLineWrapping?
+    private var layoutPreparation = CodeLayoutPreparation.progressive
+    private var layoutGeneration = 0
+    private var completeLayoutKey: CodeCompleteLayoutKey?
 
     override var isFlipped: Bool { true }
 
@@ -514,21 +545,26 @@ private final class MacCodeTextContainer: NSView {
         )
         gutterView.frame = frames.gutter
         scrollView.frame = frames.text
+        prepareCompleteLayoutIfNeeded()
         scheduleGutterUpdate()
     }
 
     func update(_ request: CodeTextRenderRequest) {
+        updateLayoutPreparation(request.layoutPreparation)
         updateLineWrapping(request.lineWrapping)
 
         guard let update = documentState.prepareUpdate(for: request) else {
             applyNewHighlightBatches(from: request)
+            prepareCompleteLayoutIfNeeded()
             scheduleGutterUpdate()
             return
         }
 
         let visibleOrigin = scrollView.contentView.bounds.origin
         let selectedRanges = textView.selectedRanges
 
+        layoutGeneration &+= 1
+        completeLayoutKey = nil
         textView.textStorage?.setAttributedString(update.attributedText)
         lastAppliedHighlightSequence = request.highlightBatches.last?.sequence ?? -1
         gutterView.updateMetrics(
@@ -541,6 +577,7 @@ private final class MacCodeTextContainer: NSView {
         }
 
         layoutSubtreeIfNeeded()
+        prepareCompleteLayoutIfNeeded()
         let destination = update.change.isNewDocument
             ? CGPoint.zero
             : visibleOrigin
@@ -563,6 +600,7 @@ private final class MacCodeTextContainer: NSView {
             to: textStorage
         )
         textStorage.endEditing()
+        completeLayoutKey = nil
         lastAppliedHighlightSequence = batches.last?.sequence
             ?? lastAppliedHighlightSequence
     }
@@ -573,6 +611,7 @@ private final class MacCodeTextContainer: NSView {
         else { return }
 
         self.lineWrapping = lineWrapping
+        completeLayoutKey = nil
         textContainer.lineBreakMode = .byWordWrapping
 
         switch lineWrapping {
@@ -593,6 +632,45 @@ private final class MacCodeTextContainer: NSView {
         textView.needsLayout = true
     }
 
+    private func updateLayoutPreparation(
+        _ layoutPreparation: CodeLayoutPreparation
+    ) {
+        guard self.layoutPreparation != layoutPreparation else { return }
+        self.layoutPreparation = layoutPreparation
+        completeLayoutKey = nil
+    }
+
+    private func prepareCompleteLayoutIfNeeded() {
+        guard let layoutManager = textView.layoutManager,
+              let textContainer = textView.textContainer
+        else { return }
+
+        let textLength = layoutManager.textStorage?.length ?? 0
+        guard layoutPreparation.preparesCompleteLayout(
+            forUTF16Length: textLength
+        ) else { return }
+
+        let containerWidth = lineWrapping == .word
+            ? scrollView.contentSize.width
+            : 0
+        guard lineWrapping != .word || containerWidth > 0 else { return }
+
+        let key = CodeCompleteLayoutKey(
+            generation: layoutGeneration,
+            containerWidth: containerWidth
+        )
+        guard key != completeLayoutKey else { return }
+        completeLayoutKey = key
+
+        CodeNativeLayoutPreparation.prepare(
+            layoutPreparation,
+            layoutManager: layoutManager,
+            textContainer: textContainer
+        )
+        textView.layoutSubtreeIfNeeded()
+        scrollView.reflectScrolledClipView(scrollView.contentView)
+    }
+
     @objc private func clipViewBoundsDidChange() {
         scheduleGutterUpdate()
     }
@@ -689,6 +767,9 @@ private final class MobileCodeTextContainer: UIView, UITextViewDelegate {
     private let gutterUpdates = CodeGutterUpdateCoordinator()
     private var lastAppliedHighlightSequence = -1
     private var lineWrapping: CodeLineWrapping?
+    private var layoutPreparation = CodeLayoutPreparation.progressive
+    private var layoutGeneration = 0
+    private var completeLayoutKey: CodeCompleteLayoutKey?
 
     override init(frame: CGRect) {
         super.init(frame: frame)
@@ -718,21 +799,26 @@ private final class MobileCodeTextContainer: UIView, UITextViewDelegate {
         )
         gutterView.frame = frames.gutter
         textView.frame = frames.text
+        prepareCompleteLayoutIfNeeded()
         scheduleGutterUpdate()
     }
 
     func update(_ request: CodeTextRenderRequest) {
+        updateLayoutPreparation(request.layoutPreparation)
         updateLineWrapping(request.lineWrapping)
 
         guard let update = documentState.prepareUpdate(for: request) else {
             applyNewHighlightBatches(from: request)
+            prepareCompleteLayoutIfNeeded()
             scheduleGutterUpdate()
             return
         }
 
         let contentOffset = textView.contentOffset
         let selectedRange = textView.selectedRange
 
+        layoutGeneration &+= 1
+        completeLayoutKey = nil
         textView.textStorage.setAttributedString(update.attributedText)
         lastAppliedHighlightSequence = request.highlightBatches.last?.sequence ?? -1
         gutterView.updateMetrics(
@@ -745,6 +831,7 @@ private final class MobileCodeTextContainer: UIView, UITextViewDelegate {
         }
 
         layoutIfNeeded()
+        prepareCompleteLayoutIfNeeded()
         textView.setContentOffset(
             update.change.isNewDocument ? .zero : contentOffset,
             animated: false
@@ -765,6 +852,7 @@ private final class MobileCodeTextContainer: UIView, UITextViewDelegate {
             to: textView.textStorage
         )
         textView.textStorage.endEditing()
+        completeLayoutKey = nil
         lastAppliedHighlightSequence = batches.last?.sequence
             ?? lastAppliedHighlightSequence
     }
@@ -773,6 +861,7 @@ private final class MobileCodeTextContainer: UIView, UITextViewDelegate {
         guard self.lineWrapping != lineWrapping else { return }
 
         self.lineWrapping = lineWrapping
+        completeLayoutKey = nil
         textView.textContainer.lineBreakMode = .byWordWrapping
         textView.textContainer.widthTracksTextView = lineWrapping == .word
 
@@ -786,6 +875,42 @@ private final class MobileCodeTextContainer: UIView, UITextViewDelegate {
         textView.setNeedsLayout()
     }
 
+    private func updateLayoutPreparation(
+        _ layoutPreparation: CodeLayoutPreparation
+    ) {
+        guard self.layoutPreparation != layoutPreparation else { return }
+        self.layoutPreparation = layoutPreparation
+        completeLayoutKey = nil
+    }
+
+    private func prepareCompleteLayoutIfNeeded() {
+        let textLength = textView.textStorage.length
+        guard layoutPreparation.preparesCompleteLayout(
+            forUTF16Length: textLength
+        ) else { return }
+
+        let containerWidth = lineWrapping == .word
+            ? textView.bounds.width
+            : 0
+        guard lineWrapping != .word || containerWidth > 0 else { return }
+
+        let key = CodeCompleteLayoutKey(
+            generation: layoutGeneration,
+            containerWidth: containerWidth
+        )
+        guard key != completeLayoutKey else { return }
+        completeLayoutKey = key
+
+        textView.layoutIfNeeded()
+        CodeNativeLayoutPreparation.prepare(
+            layoutPreparation,
+            layoutManager: textView.layoutManager,
+            textContainer: textView.textContainer
+        )
+        textView.setNeedsLayout()
+        textView.layoutIfNeeded()
+    }
+
     func scrollViewDidScroll(_ scrollView: UIScrollView) {
         scheduleGutterUpdate()
     }