From 624859e687b2adec287c0a69c8b5e44cef636f19 Mon Sep 17 00:00:00 2001
From: Matt <85322+mattmassicotte@users.noreply.github.com>
Date: Thu, 28 Mar 2024 15:48:22 -0400
Subject: [PATCH] Some more perf notes

---
 README.md | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 9caf347..6bcea6d 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,18 @@ The top-level module includes systems for managing text styling. It is also text
 
 There is also an example project that demonstrates how to use `TextViewHighlighter` for macOS and iOS.
 
+#### TextKit Integration
+
+In a traditional `NSTextStorage`-backed system (TextKit 1 and 2), it can be challenging to achieve flicker-free on-keypress highlighting. You need to know when a text change has been processed by enough of the system that styling is possible. This point in the text change lifecycle is not natively supported by `NSTextStorage` or `NSLayoutManager`. It requires an `NSTextStorage` subclass. Such a subclass, `TSYTextStorage` is available in [TextStory](https://github.com/ChimeHQ/TextStory).
+
+But, even that isn't quite enough unfortunately. You still need to precisely control the timing of invalidation and styling. This is where `RangeInvalidationBuffer` comes in.
+
+I have not yet figured out a way to do this with TextKit 2, and it may not be possible without new API.
+
+#### Performance
+
+Neon's performance is highly dependant on the text system integration. Every aspect is important as there are performance cliffs all around. But, priority range calcations (the visible set for most text views) are of particular importance. This is surprisingly challenging to do correctly with TextKit 1, and extremely hard with TextKit 2.
+
 ### TreeSitterClient
 
 This library is a hybrid sync/async interface to [SwiftTreeSitter][SwiftTreeSitter]. It features:
@@ -99,14 +111,6 @@ A highlighting theme is really just a mapping from semantic labels to styles. To
 
 This separation makes it very easy for you to do this look-up in a way that makes the most sense for whatever theming formats you'd like to support. This is also a convenient spot to adapt/modify the semantic labels coming from your data sources into a normalized form.
 
-### TextKit Integration
-
-In a traditional `NSTextStorage`-backed system (TextKit 1 and 2), it can be challenging to achieve flicker-free on-keypress highlighting. You need to know when a text change has been processed by enough of the system that styling is possible. This point in the text change lifecycle is not natively supported by `NSTextStorage` or `NSLayoutManager`. It requires an `NSTextStorage` subclass. Such a subclass, `TSYTextStorage` is available in [TextStory](https://github.com/ChimeHQ/TextStory).
-
-But, even that isn't quite enough unfortunately. You still need to precisely control the timing of invalidation and styling. This is where `RangeInvalidationBuffer` comes in.
-
-I have not yet figured out a way to do this with TextKit 2, and it may not be possible without new API.
-
 ## Usage
 
 ### TreeSitterClient