sl0ppty: the graphics stream gives the cursor back

Reported as "the cursor is not rendered in zsh" in a newly spawned pane. It
was not about zsh, or about that pane: it was about the pane next to it,
which was animating an image.

Placing an image means parking the cursor on its target cell first, and the
graphics bytes go out *after* the cell diff -- deliberately, so a repainted
cell cannot land on top of a placement. That is also after the frame has put
the real cursor where the focused pane wants it. So with any image on screen,
the last instruction the terminal received every frame was "go to wherever
that image is", and the cursor sat there: in another pane, moving about with
the picture. With a bouncing DVD logo next door it is quite a sight.

gfx_begin() now opens the stream with DECSC and gfx_flush() closes it with
DECRC, so the whole thing is cursor-neutral no matter what it contains. The
save has to be written at the start of the frame rather than at flush time,
because transmissions are emitted as images are recorded and are already in
the buffer by then. A frame with nothing to say drops both and still emits
not one byte, which the test asserts, because a save/restore pair on every
idle frame is exactly the sort of cost that creeps in unnoticed.

Two tests: that the stream is bracketed (and that it really does move the
cursor, or the assertion proves nothing), and that an idle frame is empty.

One C trap worth the comment it now has: "\x1b7" is a *single* hex escape,
0x1b7, not ESC followed by 7. The compiler catches that one because it is out
of range -- and would not catch "\x1b1", which compiles quietly into one
wrong byte. Escape then digit is always two strings.

1 files changed, 10 insertions, 0 deletions

diff --git a/HANDOVER.md b/HANDOVER.md
index d1876b6..73b3331 100644
--- a/HANDOVER.md
+++ b/HANDOVER.md
@@ -206,6 +206,16 @@ it answers with the escape sequences the client is actually sent, so a test
 can assert on the bytes rather than on the model that produced them. If you
 touch graphics, assert on the bytes.
 
+**Anything written after the frame must leave the cursor where the frame put
+it.** Images go out after the cell diff on purpose (a repainted cell must not
+land on top of a placement), and placing an image parks the cursor on its
+target cell first — so the last thing the terminal heard each frame was "go
+to wherever that image is". The cursor then sat in another pane, wandering
+about with the picture, and it was reported as "the shell I am typing in has
+no cursor". The graphics stream now opens with DECSC and closes with DECRC,
+and emits nothing at all when there is nothing to say. Any future
+after-the-frame output owes the same debt.
+
 ## Things left on the table
 
 - **A `reload` keybinding.** The config watcher made it less pressing.