From bb579be2072798ae4fc2a73d9b2e21ac13cb423c Mon Sep 17 00:00:00 2001
From: Amr Gharbeia <amr@gharbeia.net>
Date: Thu, 14 May 2026 19:36:21 -0400
Subject: [PATCH] fix: remove per-call finish-output from backend-write (flush
 once per frame via end-sync)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

backend-write flushed output after every single draw-text/draw-rect
call, causing hundreds of individual flushes per frame. This caused
visible flicker on slow terminals.

Remove finish-output from backend-write — all critical flush points
(initialize-backend, shutdown-backend, enable-mouse, enable-bracketed-paste,
end-sync) already call finish-output explicitly.

DECICM sync (begin-sync/end-sync) wraps every frame boundary,
making the frame render atomically with a single flush at end-sync.
---
 org/backend-protocol.org | 8 +++-----
 org/modern-backend.org   | 6 +++---
 src/backend/modern.lisp  | 1 -
 src/backend/simple.lisp  | 1 -
 4 files changed, 6 insertions(+), 10 deletions(-)

diff --git a/org/backend-protocol.org b/org/backend-protocol.org
index a14b103..d17271f 100644
--- a/org/backend-protocol.org
+++ b/org/backend-protocol.org
@@ -886,16 +886,14 @@ a hard-coded 80x24 at the end:
 
 *** Backend Write (Simple)
 
-Writes a string to the backend's output stream, forces the stream to
-flush, and returns the length of the string. Uses ~finish-output~ to
-ensure the data is actually sent, which matters for pipe and network
-output.
+Writes a string to the backend's output stream and returns its length.
+Does NOT flush — explicit sync points (~initialize-backend~,
+~end-sync~, etc.) call ~finish-output~ as needed.
 
 #+BEGIN_SRC lisp :tangle ../src/backend/simple.lisp
 (defmethod backend-write ((b simple-backend) string)
   (let ((stream (backend-output-stream b)))
     (write-string string stream)
-    (finish-output stream)
     (length string)))
 #+END_SRC
 
diff --git a/org/modern-backend.org b/org/modern-backend.org
index 07b4278..334fb19 100644
--- a/org/modern-backend.org
+++ b/org/modern-backend.org
@@ -701,15 +701,15 @@ Uses a fallback chain to determine terminal dimensions:
 
 *** backend-write
 
-Writes a string to the backend's output stream, flushing after each
-write to ensure the terminal receives the escape sequence immediately.
+Writes a string to the backend's output stream. Does NOT flush — the
+caller is responsible for calling ~finish-output~ at appropriate sync
+points (frame boundaries via ~end-sync~, initialization, shutdown).
 Returns the string length for protocol compatibility.
 
 #+BEGIN_SRC lisp :tangle ../src/backend/modern.lisp
 (defmethod backend-write ((b modern-backend) string)
   (let ((stream (backend-output-stream b)))
     (write-string string stream)
-    (finish-output stream)
     (length string)))
 #+END_SRC
 
diff --git a/src/backend/modern.lisp b/src/backend/modern.lisp
index 5d1c056..f10e360 100644
--- a/src/backend/modern.lisp
+++ b/src/backend/modern.lisp
@@ -204,7 +204,6 @@ as a fallback when a keyword is not in *named-colors*.")
 (defmethod backend-write ((b modern-backend) string)
   (let ((stream (backend-output-stream b)))
     (write-string string stream)
-    (finish-output stream)
     (length string)))
 
 (defmethod capable-p ((b modern-backend) feature)
diff --git a/src/backend/simple.lisp b/src/backend/simple.lisp
index a6e75ec..936761a 100644
--- a/src/backend/simple.lisp
+++ b/src/backend/simple.lisp
@@ -77,7 +77,6 @@
 (defmethod backend-write ((b simple-backend) string)
   (let ((stream (backend-output-stream b)))
     (write-string string stream)
-    (finish-output stream)
     (length string)))
 
 (defmethod draw-text ((b simple-backend) x y string fg bg