words

Author: willmcgugan

docs/blog/posts/release1.0.0.md

@@ -3,7 +3,7 @@ draft: true
 date: 2024-12-05
 categories:
   - Release
-title: "Three algorithms for a high performance terminal apps"
+title: "Three algorithms for high performance terminal apps"
 authors:
   - willmcgugan
 ---
@@ -22,8 +22,7 @@ Often frustrating but never boring, the challenges arise because the terminal "s
 The building blocks are there: after some effort you can move the cursor, write colored text, read keys and mouse movements, but that's about it.
 Everything else we had to build from scratch, from the most basic [button](https://textual.textualize.io/widget_gallery/#button) to a syntax highlighted [TextArea](https://textual.textualize.io/widget_gallery/#textarea), and everything along the way.
 
-I wanted to write-up some of the more interesting solutions we came up with for a while.
-The 1.0 milestone we just passed makes this the perfect time.
+I wanted to write-up some of the more interesting solutions we came up with, and the 1.0 milestone we just passed makes this a perfect time.
 
 If you haven't followed along with Textual's development, here is a demo of what it can do.
 This is a Textual app, running remotely, served by your browser:
@@ -46,9 +45,9 @@ The first component of Textual I want to cover is the *compositor*.
 The job of the compositor is to combine widgets in to a single view.
 
 We do this because the terminal itself has no notion of overlapping windows in the way a desktop does.
-If an app wants to display overlapping components it must combine them into a single update.
+If an app wants to display overlapping components we must first combine (or compose) them into a single update.
 
-Here's a video I generated over a year ago, demonstrating the output of the compositor:
+Here's a video I generated over a year ago, demonstrating the compositor:
 
 <div class="video-wrapper">
 <iframe width="100%" height="auto" src="https://www.youtube.com/embed/T8PZjUVVb50" title="" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
@@ -68,13 +67,15 @@ Anything you print in Rich, first generates a list of [Segments](https://github.
 These Segments are only converted into text with [ansi escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) at the very last moment.
 
 
-Textual works with same Segment object.
-Widgets all produce a list of segments, which is further processed by the compositor.
+Textual builds its output from the same Segment object.
+The compositor takes lists of segments generated by widgets and further processes them, by dividing and combining, to produce the final output. 
+In fact almost everything Textual does involves processing these segments in one way or another,.
 
 !!! tip "Switch the Primitive"
 
-    If a problem is intractable, it can often be simplified by changing what you consider to be the fundamental atomic data and operations you are working with.
+    If a problem is intractable, it can often be simplified by changing what you consider to be the atomic data and operations you are working with.
     I call this "switching the primitive".
+    In Rich this was switching from thinking in characters to thinking in segments.
 
 ### Thinking in Segments 
 
@@ -101,14 +102,15 @@ It would appear something like the following:
 --8<-- "docs/blog/images/compositor/cuts0.excalidraw.svg"
 </div>
 
-We can't yet display the output as it would require writing each "layer" independantly, potentially making the terminal flicker, and certainly writing more data than neccesary.
+We can't yet display the output as it would require writing each "layer" independently, potentially making the terminal flicker, and certainly writing more data than necessary.
 
 We need a few more steps to combine these lines in to a single line.
 
 
 ### Step 1. Finding the cuts.
 
 First thing the compositor does is to find every offset where a list of segments begins or ends.
+We call these "cuts".
 
 <div class="excalidraw">
 --8<-- "docs/blog/images/compositor/cuts1.excalidraw.svg"
@@ -117,15 +119,14 @@ First thing the compositor does is to find every offset where a list of segments
 ### Step 2. Applying the cuts.
 
 The next step is to divide every list of segments at the cut offsets.
-This will produce smaller lists of segments, which in the compositor code we refer to as *chops*.
+This will produce smaller lists of segments, which we refer to as *chops*.
 
 <div class="excalidraw">
 --8<-- "docs/blog/images/compositor/cuts2.excalidraw.svg"
 </div>
 
-These chops have the property that nothing overlaps.
-If there is a chop below any give chop, then both will have the same size.
-This property makes the next step possible.
+After this step we have lists of chops where each chop is of the same size, and therefore nothing overlaps.
+It's the non-overlapping property that makes the next step possible.
 
 ### Step 3. Discard chops.
 
@@ -138,22 +139,26 @@ Anything not at the top will be occluded and can be thrown away.
 
 ### Step 4. Combine.
 
-Now all that's left is to combine the top-most chops in to a single list of Segments. It is this list of segments that becomes a line in the terminal.
+Now all that's left is to combine the top-most chops in to a single list of Segments.
+It is this list of segments that becomes a line in the terminal.
 
 <div class="excalidraw">
 --8<-- "docs/blog/images/compositor/cuts4.excalidraw.svg"
 </div>
 
-this is done for ever line in the output.
-At the end of it we have a list of segments for each line, ready to be converted in to escape sequences and written to the terminal.
+As this is the final step in the process, these lines of segments will ultimately be converted to text plus escape sequences and written to the output.
 
 ### What I omitted
 
 There is more going on than this explanation may suggest.
 Widgets may contain other widgets which are clipped to their *parent's* boundaries, and widgets that contain other widgets may also scroll &mdash; the compositor must take all of this in to account.
 
-Additionally, the compositor can do partial updates.
-In other words, if you click a button and it changes color the compositor can update just that button.
+!!! info "It's widgets all the way down"
+
+    Not to mention there can be multiple "screens" of widgets stacked on top of each other, with a modal fade effect applied to lower screens. 
+
+The compositor can do partial updates.
+In other words, if you click a button and it changes color, the compositor can update just the region occupied by the button.
 
 The compositor does all of this fast enough to enable smooth scrolling, even with a metric tonne of widgets on screen.
 
@@ -174,7 +179,7 @@ Not all of which widgets may be visible in the final view (if they are within a
     If you can think of a game that can be played in 2 characters &mdash; let me know!
 
 The *spatial map*[^1] is a data structure used by the compositor to very quickly discard widgets that are not visible within a given region.
-The algorithm is uses may be familiar if you have done any classic game-dev.
+The algorithm it uses may be familiar if you have done any classic game-dev.
 
 
 ### The problem 
@@ -185,8 +190,8 @@ Consider the following arrangement of widgets:
 --8<-- "docs/blog/images/compositor/spatial-map.excalidraw.svg"
 </div>
 
-Here we have 8 widgets, where only around 4 will be visible at any given time depending on the position of the scrollbar.
-We want to avoid doing any work on widgets which will not be seen in the next frame.
+Here we have 8 widgets, where only around 4 will be visible at any given time, depending on the position of the scrollbar.
+We want to avoid doing work on widgets which will not be seen in the next frame.
 
 A naive solution to this would be to check each widget's [Region][textual.geometry.Region] to see if it overlaps with the visible area.
 This is a perfectly reasonable solution, but it won't scale well.
@@ -223,15 +228,16 @@ If the widgets don't change their position or size such as when user is *scrolli
 ### Search the grid
 
 The speedups from the spatial map come when we want to know which widgets are visible.
-To do that, we first create a region that covers the area that is scrolling &mdash; which may be the entire screen, or a smaller scrollable container.
+To do that, we first create a region that covers the area we want to consider &mdash; which may be the entire screen, or a smaller scrollable container.
 
 In the following illustration we have scrolled the screen up[^3] a little so that Widget 3 is at the top of the screen:
 
 <div class="excalidraw">
 --8<-- "docs/blog/images/compositor/spatial-map-view1.excalidraw.svg"
 </div>
 
-We then determine which grid tiles are covered by the viewable area, which would be `(0,0)`, `(1,0)`, `(0,1)`, and `(1,1)`.
+We then determine which grid tiles overlap by the viewable area.
+In the above examples that would be the tiles with coordinates  `(0,0)`, `(1,0)`, `(0,1)`, and `(1,1)`.
 Once we have that information, we can then then look up those coordinates in the spatial map data structure, which would retrieve 4 lists:
 
 ```python
@@ -250,7 +256,7 @@ Combining those together and de-duplicating we get:
 ```
 
 These widgets are either within the viewable area, or close by.
-The widgets not included in the list (`widget7`, `widget8`) we can confidently conclude that they are not visible.
+We can confidently conclude that the widgets *not* ion that list are hidden from view.
 If we need to know precisely which widgets are visible we can check their regions individually.
 
 The useful property of this algorithm is that as the number of widgets increases, the time it takes to figure out which are visible stays relatively constant. Scrolling a view of 8 widgets, takes much the same time as a view of 1000 widgets or more.