document this very important lesson

I had it once already in my grasp, in pensieve.love, but it slipped
through my fingers. Let's see if this attempt sticks.

0022-on.text_input

@@ -4,6 +4,17 @@ on.text_input = function(t)
 		edit.text_input(Cursor_node.editor, t)
 		if not eq(Cursor_node.editor.screen_top1, old_top) then
 			Viewport.y = Cursor_node.y + y_of_schema1(Cursor_node.editor, Cursor_node.editor.screen_top1)
+			-- Most of the time, we update the screen_top of nodes from Viewport.y.
+			-- But here we went the other way.
+			-- It's very important to avoid creating a recurrence, to avoid running
+			-- both sides of this feedback loop in a single frame. These apps are
+			-- not very numerically precise (e.g. we force text lines to start at
+			-- integer pixels regardless of zoom, because that keeps text crisp),
+			-- and the computations of Viewport.y and node.top will almost certainly
+			-- not converge. The resulting bugs are extremely difficult to chase
+			-- down.
+			-- The optional skip_updating_screen_top_for arg ensures we don't run
+			-- the other side of the feedback loop.
 			A(--[[skip updating screen_top for]] Cursor_node)
 			return
 		end

0023-on.keychord_press

@@ -21,6 +21,17 @@ on.keychord_press = function(chord, key)
 		edit.keychord_press(Cursor_node.editor, chord, key)
 		if not eq(Cursor_node.editor.screen_top1, old_top) then
 			Viewport.y = Cursor_node.y + y_of_schema1(Cursor_node.editor, Cursor_node.editor.screen_top1)
+			-- Most of the time, we update the screen_top of nodes from Viewport.y.
+			-- But here we went the other way.
+			-- It's very important to avoid creating a recurrence, to avoid running
+			-- both sides of this feedback loop in a single frame. These apps are
+			-- not very numerically precise (e.g. we force text lines to start at
+			-- integer pixels regardless of zoom, because that keeps text crisp),
+			-- and the computations of Viewport.y and node.top will almost certainly
+			-- not converge. The resulting bugs are extremely difficult to chase
+			-- down.
+			-- The optional skip_updating_screen_top_for arg ensures we don't run
+			-- the other side of the feedback loop.
 			A(--[[skip updating screen_top for]] Cursor_node)
 			return
 		end