@hank-warren/pi-statusline 0.1.0 → 0.1.2

package/README.md

@@ -26,6 +26,14 @@ It uses a fixed true-color palette with context warning thresholds.
 
 PR lookups use the `gh` CLI when available and degrade gracefully without it.
 
+## Fullscreen TUI mode
+
+Pi's fullscreen renderer only re-emits terminal rows whose rendered content changed. The worktree and session-ID lines are static for the life of a session, so if their cells ever desync from Pi's row cache — stale transcript text, a process sharing the tty, a stray escape sequence — nothing repaints them and the artifact persists.
+
+To repair that promptly without repeatedly clearing the screen, a one-second sweep changes an invisible marker on the fullscreen footer and requests a targeted differential render. Only the statusline rows compare as changed, so they repaint at most once per second even while the rest of Pi is actively rendering. A 30-second forced full redraw remains as a fallback for corruption outside the footer, throttled to at most one every five seconds and also requested at turn boundaries.
+
+Both repair layers are skipped entirely in regular TUI mode, which reprints its whole block each frame and therefore self-heals. Only the slower forced fallback can drop a scrollback text selection highlight for a single frame.
+
 ## Install
 
 ```bash

package/index.ts

@@ -1,6 +1,7 @@
 import { basename } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
+import { FullRedrawScheduler } from "./redraw.ts";
 import {
 	type GitRepositoryStatus,
 	readGitStatus,
@@ -96,6 +97,7 @@ export function renderStatusline(data: StatuslineData, width: number): string[]
 
 export default function statuslineExtension(pi: ExtensionAPI): void {
 	let requestRender: (() => void) | undefined;
+	const fullRedraw = new FullRedrawScheduler();
 	let tracker: SessionWorktreeTracker | undefined;
 	let cwdGit: GitRepositoryStatus | null = null;
 	let cwdStatusAbort: AbortController | undefined;
@@ -156,6 +158,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 
 		ctx.ui.setFooter((tui, _theme, footerData) => {
 			requestRender = () => tui.requestRender();
+			// Fullscreen mode never repaints unchanged rows; the session id line is
+			// static, so it needs periodic forced redraws to shed stale cells.
+			fullRedraw.attach(tui);
 			const stopBranchUpdates = footerData.onBranchChange(() => {
 				runInBackground(refreshCwdStatus(ctx));
 				tui.requestRender();
@@ -164,6 +169,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 			return {
 				dispose(): void {
 					stopBranchUpdates();
+					fullRedraw.detach();
 					requestRender = undefined;
 				},
 				invalidate(): void {},
@@ -172,17 +178,19 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 					const cwd = basename(ctx.cwd) || ctx.cwd;
 					const model = ctx.model?.id.split("/").pop() || "no-model";
 
-					return renderStatusline(
-						{
-							model,
-							cwd,
-							cwdGit,
-							contextTokens: usage?.tokens ?? null,
-							contextWindow: usage?.contextWindow ?? ctx.model?.contextWindow ?? 0,
-							worktrees: tracker?.getWorktrees() ?? [],
-							sessionId: ctx.sessionManager.getSessionId(),
-						},
-						width,
+					return fullRedraw.decorate(
+						renderStatusline(
+							{
+								model,
+								cwd,
+								cwdGit,
+								contextTokens: usage?.tokens ?? null,
+								contextWindow: usage?.contextWindow ?? ctx.model?.contextWindow ?? 0,
+								worktrees: tracker?.getWorktrees() ?? [],
+								sessionId: ctx.sessionManager.getSessionId(),
+							},
+							width,
+						),
 					);
 				},
 			};
@@ -195,6 +203,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		if (tracker) runInBackground(tracker.observeToolInput(event.toolName, event.input));
 	});
 	pi.on("turn_end", (_event, ctx) => {
+		fullRedraw.request();
 		requestRender?.();
 		runInBackground(refreshCwdStatus(ctx));
 		if (tracker) runInBackground(tracker.refresh());
@@ -202,6 +211,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	pi.on("model_select", () => requestRender?.());
 	pi.on("session_tree", (_event, ctx) => resetTracker(ctx));
 	pi.on("session_shutdown", () => {
+		fullRedraw.detach();
 		tracker?.dispose();
 		tracker = undefined;
 		cwdStatusAbort?.abort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Compact Pi footer statusline: model ID, git branch/dirty/behind state, linked worktrees with PR numbers, context usage, and session ID.",
   "type": "module",
   "keywords": [
@@ -32,6 +32,7 @@
   },
   "files": [
     "index.ts",
+    "redraw.ts",
     "worktrees.ts",
     "README.md",
     "LICENSE"

package/redraw.ts

@@ -0,0 +1,137 @@
+/**
+ * Fullscreen TUI artifact repair.
+ *
+ * Pi's fullscreen (alt-screen) renderer writes rows differentially: a row whose
+ * rendered content is byte-identical to the previous frame is never re-emitted.
+ * Once terminal cells desync from Pi's row cache, static statusline rows can
+ * therefore retain stale text indefinitely.
+ *
+ * This scheduler repairs the footer in two layers:
+ *
+ * 1. A short timer alternates between two visually equivalent ANSI reset
+ *    prefixes and requests a normal render. Only the statusline rows compare as
+ *    changed, even when Pi is otherwise idle.
+ * 2. `request()` keeps the slower forced full redraw fallback for corruption
+ *    outside the footer.
+ *
+ * Both layers are fullscreen-only. Regular mode already reprints its block and
+ * does not need a periodic render.
+ */
+
+/** Minimum spacing between forced full redraws. */
+export const DEFAULT_MIN_GAP_MS = 5_000;
+/** Idle cadence for targeted statusline-row repainting. */
+export const DEFAULT_ROW_REFRESH_INTERVAL_MS = 1_000;
+/** Slow fallback cadence for corruption outside the footer. */
+export const DEFAULT_IDLE_INTERVAL_MS = 30_000;
+
+const ANSI_RESET = "\x1b[0m";
+
+/** The subset of Pi's TUI surface this scheduler needs. */
+export interface RedrawTarget {
+	readonly mode: string;
+	requestRender(force?: boolean): void;
+}
+
+export interface FullRedrawSchedulerOptions {
+	minGapMs?: number;
+	rowRefreshIntervalMs?: number;
+	idleIntervalMs?: number;
+	now?: () => number;
+	schedule?: (callback: () => void, intervalMs: number) => unknown;
+	cancel?: (handle: unknown) => void;
+}
+
+function defaultSchedule(callback: () => void, intervalMs: number): unknown {
+	const timer = setInterval(callback, intervalMs);
+	// Never hold the process open just to repair cosmetic artifacts.
+	(timer as { unref?: () => void }).unref?.();
+	return timer;
+}
+
+function defaultCancel(handle: unknown): void {
+	clearInterval(handle as ReturnType<typeof setInterval>);
+}
+
+export class FullRedrawScheduler {
+	private target: RedrawTarget | undefined;
+	private rowRefreshHandle: unknown;
+	private fullRedrawHandle: unknown;
+	private lastRedrawAt = Number.NEGATIVE_INFINITY;
+	private decorationPhase = 0;
+	private readonly minGapMs: number;
+	private readonly rowRefreshIntervalMs: number;
+	private readonly idleIntervalMs: number;
+	private readonly now: () => number;
+	private readonly schedule: (callback: () => void, intervalMs: number) => unknown;
+	private readonly cancel: (handle: unknown) => void;
+
+	constructor(options: FullRedrawSchedulerOptions = {}) {
+		this.minGapMs = options.minGapMs ?? DEFAULT_MIN_GAP_MS;
+		this.rowRefreshIntervalMs = options.rowRefreshIntervalMs ?? DEFAULT_ROW_REFRESH_INTERVAL_MS;
+		this.idleIntervalMs = options.idleIntervalMs ?? DEFAULT_IDLE_INTERVAL_MS;
+		this.now = options.now ?? Date.now;
+		this.schedule = options.schedule ?? defaultSchedule;
+		this.cancel = options.cancel ?? defaultCancel;
+	}
+
+	/** Bind to the TUI that owns the footer and start both repair sweeps. */
+	attach(target: RedrawTarget): void {
+		this.detach();
+		this.target = target;
+		this.lastRedrawAt = Number.NEGATIVE_INFINITY;
+		this.decorationPhase = 0;
+		this.rowRefreshHandle = this.schedule(() => {
+			this.requestRowRefresh();
+		}, this.rowRefreshIntervalMs);
+		this.fullRedrawHandle = this.schedule(() => {
+			this.request();
+		}, this.idleIntervalMs);
+	}
+
+	detach(): void {
+		if (this.rowRefreshHandle !== undefined) this.cancel(this.rowRefreshHandle);
+		if (this.fullRedrawHandle !== undefined) this.cancel(this.fullRedrawHandle);
+		this.rowRefreshHandle = undefined;
+		this.fullRedrawHandle = undefined;
+		this.target = undefined;
+	}
+
+	/**
+	 * Make footer rows byte-different without changing their visible contents.
+	 * Pi will then clear and repaint those rows during an ordinary differential
+	 * render instead of requiring a full-screen clear.
+	 */
+	decorate(lines: string[]): string[] {
+		if (this.target?.mode !== "fullscreen") return lines;
+		const prefix = this.decorationPhase === 0 ? ANSI_RESET : `${ANSI_RESET}${ANSI_RESET}`;
+		return lines.map((line) => `${prefix}${line}`);
+	}
+
+	/**
+	 * Advance the invisible footer marker and request an ordinary render. The
+	 * timer calls this at most once per interval, so active Pi frames do not
+	 * repeatedly repaint otherwise-static statusline rows.
+	 */
+	requestRowRefresh(): boolean {
+		const target = this.target;
+		if (!target || target.mode !== "fullscreen") return false;
+		this.decorationPhase = (this.decorationPhase + 1) % 2;
+		target.requestRender();
+		return true;
+	}
+
+	/**
+	 * Ask for a forced full redraw. No-ops outside fullscreen mode and while
+	 * throttled. Returns whether a redraw was actually requested.
+	 */
+	request(): boolean {
+		const target = this.target;
+		if (!target || target.mode !== "fullscreen") return false;
+		const now = this.now();
+		if (now - this.lastRedrawAt < this.minGapMs) return false;
+		this.lastRedrawAt = now;
+		target.requestRender(true);
+		return true;
+	}
+}