From f2b92059cf2d973d3253d21917e16260939207d0 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Tue, 16 Jun 2026 12:16:40 +0000
Subject: [PATCH] fix(tui): reduced loader repaint flicker

Throttled animated loader message-only repaints when synchronized output is unavailable so unsupported terminals only repaint on spinner frame changes.

Fixes #2771
---
 packages/tui/CHANGELOG.md             |  5 +++++
 packages/tui/src/components/loader.ts |  7 +++++--
 packages/tui/test/loader.test.ts      | 22 +++++++++++++++++++++-
 3 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 1d7721716..fb9de7f86 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+
+### Fixed
+
+- Fixed animated working-message loader frames repainting at 30fps on terminals without synchronized-output support, which could cause visible flicker during normal prompt rendering ([#2771](https://github.com/can1357/oh-my-pi/issues/2771)).
+
 ## [16.0.1] - 2026-06-15
 
 ### Added
diff --git a/packages/tui/src/components/loader.ts b/packages/tui/src/components/loader.ts
index 65a5c1292..387d5c4c7 100644
--- a/packages/tui/src/components/loader.ts
+++ b/packages/tui/src/components/loader.ts
@@ -57,12 +57,15 @@ export class Loader extends Text {
 		this.#intervalId = setInterval(() => {
 			const now = performance.now();
 			const elapsed = now - this.#lastSpinnerTick;
-			if (elapsed >= SPINNER_ADVANCE_MS) {
+			const shouldAdvanceSpinner = elapsed >= SPINNER_ADVANCE_MS;
+			if (shouldAdvanceSpinner) {
 				const steps = Math.floor(elapsed / SPINNER_ADVANCE_MS);
 				this.#currentFrame = (this.#currentFrame + steps) % this.#frames.length;
 				this.#lastSpinnerTick += steps * SPINNER_ADVANCE_MS;
 			}
-			this.#updateDisplay();
+			if (shouldAdvanceSpinner || this.#ui?.synchronizedOutput === true) {
+				this.#updateDisplay();
+			}
 		}, intervalMs);
 	}
 
diff --git a/packages/tui/test/loader.test.ts b/packages/tui/test/loader.test.ts
index 77c341a1f..e200e1b24 100644
--- a/packages/tui/test/loader.test.ts
+++ b/packages/tui/test/loader.test.ts
@@ -92,7 +92,7 @@ describe("Loader component", () => {
 	it("requests render when animated message bytes change between spinner frames", () => {
 		vi.useFakeTimers();
 		setSystemTime(new Date(1_000));
-		const ui = { requestComponentRender: vi.fn() } as unknown as TUI;
+		const ui = { synchronizedOutput: true, requestComponentRender: vi.fn() } as unknown as TUI;
 		const colorMessage = ((text: string) => `${text}-${Date.now()}`) as LoaderMessageColorFn & { animated: true };
 		colorMessage.animated = true;
 		const loader = new Loader(ui, text => text, colorMessage, "Checking", ["0"]);
@@ -106,6 +106,26 @@ describe("Loader component", () => {
 		loader.stop();
 	});
 
+	it("holds animated message-only frames when synchronized output is unavailable", () => {
+		vi.useFakeTimers();
+		setSystemTime(new Date(1_000));
+		const ui = { synchronizedOutput: false, requestComponentRender: vi.fn() } as unknown as TUI;
+		const colorMessage = ((text: string) => `${text}-${Date.now()}`) as LoaderMessageColorFn & { animated: true };
+		colorMessage.animated = true;
+		const loader = new Loader(ui, text => text, colorMessage, "Checking", ["0", "1"]);
+
+		expect(ui.requestComponentRender).toHaveBeenCalledTimes(1);
+
+		vi.advanceTimersByTime(34);
+		expect(ui.requestComponentRender).toHaveBeenCalledTimes(1);
+
+		vi.advanceTimersByTime(67);
+		expect(ui.requestComponentRender).toHaveBeenCalledTimes(2);
+		expect(loader.render(40).join("\n")).toContain("1 Checking-");
+
+		loader.stop();
+	});
+
 	it("dispose() stops the animation so no further renders are scheduled", async () => {
 		const term = new VirtualTerminal(20, 4);
 		const tui = new TUI(term);