@oh-my-pi/pi-tui 16.4.6 → 16.5.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [16.5.0] - 2026-07-13
+
+### Changed
+
+ - Improved native scrollback history management by introducing an optional erase-and-replay mechanism to rebuild scrollback when mutated rows (such as finalized tool blocks or collapsed transcripts) diverge. This is now gated behind the `tui.scrollbackRebuild` setting and defaults to off.
+
+### Fixed
+
+- Fixed a rendering issue where resizing the terminal during forced renders (such as tool finalization or image reconciliation) caused the entire transcript to visibly replay and flicker. Forced renders are now consolidated into a single paint once the resize settles.
+
+## [16.4.7] - 2026-07-12
+
+### Fixed
+
+- Fixed keyboard navigation paying an extra frame of input latency after idle; the queue-drain grace now applies only to Ctrl+C and Escape double-press gestures.
+
 ## [16.4.6] - 2026-07-12
 
 ### Added

package/dist/types/tui.d.ts

@@ -280,9 +280,11 @@ export declare function coalesceAdjacentSgr(line: string): string;
  *       source just became declared-final (the block finalized / a barrier
  *       cleared). Hard-scanned in FULL with no tolerance: any content change
  *       (a pending header settling, a preview replaced by its result, a tail
- *       shifting up after a barrier removal) re-anchors so the final content
- *       recommits below the frozen snapshot — duplication, never loss —
- *       instead of being committed nowhere and painted nowhere.
+ *       shifting up after a barrier removal) re-anchors so the engine can
+ *       erase-and-replay history with the final content exactly once (or, on
+ *       ED3-unsafe multiplexers, recommit it below the frozen snapshot —
+ *       duplication, never loss) instead of committing it nowhere and
+ *       painting it nowhere.
  *   [finalTo, prefix.length) FROZEN visual snapshots of still-live rows —
  *       exempt: their drift is expected (a collapsing preview, a ticking
  *       progress tree) and must never spray re-anchors mid-run.
@@ -335,6 +337,17 @@ export declare class TUI extends Container {
      * plus a full redraw on the frame after a new image exceeds the cap.
      */
     setMaxInlineImages(cap: number): void;
+    /**
+     * Get whether scrollback divergence rebuild is enabled.
+     */
+    getScrollbackRebuild(): boolean;
+    /**
+     * Enable or disable scrollback divergence rebuild (default off).
+     * When enabled, the engine will erase and replay the terminal's
+     * scrollback (using ED3 / alt buffer / scrollback replay) to avoid
+     * duplicate blocks when a block's final form replaces its live preview.
+     */
+    setScrollbackRebuild(enabled: boolean): void;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.4.6",
+	"version": "16.5.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,10 +37,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.4.6",
-		"@oh-my-pi/pi-utils": "16.4.6",
-		"lru-cache": "11.5.1",
-		"marked": "^18.0.5"
+		"@oh-my-pi/pi-natives": "16.5.0",
+		"@oh-my-pi/pi-utils": "16.5.0",
+		"lru-cache": "11.5.2",
+		"marked": "^18.0.6"
 	},
 	"devDependencies": {
 		"chalk": "^5.6.2",

package/src/tui.ts

@@ -5,11 +5,15 @@
  * immutable — the tape is the terminal's visual record. Whatever scrolls
  * above the window enters history exactly once, in order: as exact-final
  * bytes when the component seam (`NativeScrollbackLiveRegion`) declared them
- * final, else as a frozen snapshot of what was on screen. ED3 (`CSI 3 J`) is
- * emitted only for gesture-driven replays (session replace, resize,
- * resetDisplay) where snapping the viewport is acceptable. The engine never
- * probes or guesses the terminal's scroll position, and the hot path clamps
- * over-wide lines instead of throwing. See `docs/tui-core-renderer.md`.
+ * final, else as a frozen snapshot of what was on screen. When recorded
+ * history diverges from the frame (a finalized block replacing its
+ * scrolled-off live render), the engine erases and replays (ED3, `CSI 3 J`)
+ * so history holds the content exactly once — the same replay used for
+ * gestures (session replace, resize, resetDisplay). Multiplexer panes, where
+ * ED3 is unsafe, instead re-anchor and recommit below the stale fragment —
+ * duplication, never loss. The engine never probes or guesses the terminal's
+ * scroll position, and the hot path clamps over-wide lines instead of
+ * throwing. See `docs/tui-core-renderer.md`.
  */
 import * as fs from "node:fs";
 import { performance } from "node:perf_hooks";
@@ -783,9 +787,11 @@ const RESYNC_TAIL_SAMPLES = 8;
  *       source just became declared-final (the block finalized / a barrier
  *       cleared). Hard-scanned in FULL with no tolerance: any content change
  *       (a pending header settling, a preview replaced by its result, a tail
- *       shifting up after a barrier removal) re-anchors so the final content
- *       recommits below the frozen snapshot — duplication, never loss —
- *       instead of being committed nowhere and painted nowhere.
+ *       shifting up after a barrier removal) re-anchors so the engine can
+ *       erase-and-replay history with the final content exactly once (or, on
+ *       ED3-unsafe multiplexers, recommit it below the frozen snapshot —
+ *       duplication, never loss) instead of committing it nowhere and
+ *       painting it nowhere.
  *   [finalTo, prefix.length) FROZEN visual snapshots of still-live rows —
  *       exempt: their drift is expected (a collapsing preview, a ticking
  *       progress tree) and must never spray re-anchors mid-run.
@@ -1001,6 +1007,8 @@ export class TUI extends Container {
 	#clearScrollbackOnNextRender = false;
 	#forceViewportRepaintOnNextRender = false;
 	#hasEverRendered = false;
+	#scrollbackRebuildEnabled =
+		Bun.env.PI_TUI_SCROLLBACK_REBUILD === "1" || Bun.env.PI_TUI_SCROLLBACK_REBUILD === "true";
 	// Set by the terminal resize callback; consumed by the next render. A resize
 	// event invalidates the committed screen even when the dimensions net out
 	// unchanged by render time (e.g. a 6→4→6 round trip coalesced into one frame
@@ -1290,6 +1298,23 @@ export class TUI extends Container {
 		this.#imageBudget.setCap(cap);
 	}
 
+	/**
+	 * Get whether scrollback divergence rebuild is enabled.
+	 */
+	getScrollbackRebuild(): boolean {
+		return this.#scrollbackRebuildEnabled;
+	}
+
+	/**
+	 * Enable or disable scrollback divergence rebuild (default off).
+	 * When enabled, the engine will erase and replay the terminal's
+	 * scrollback (using ED3 / alt buffer / scrollback replay) to avoid
+	 * duplicate blocks when a block's final form replaces its live preview.
+	 */
+	setScrollbackRebuild(enabled: boolean): void {
+		this.#scrollbackRebuildEnabled = enabled;
+	}
+
 	getShowHardwareCursor(): boolean {
 		return this.#showHardwareCursor;
 	}
@@ -2239,12 +2264,12 @@ export class TUI extends Container {
 	}
 
 	#handleInput(data: string): void {
-		// Raw-mode Ctrl+C/Esc arrive as stdin data, not process signals. If the
-		// first key in a double-key gesture schedules an immediate slow repaint,
-		// the queued second key can sit behind that repaint long enough for the
-		// app-level double-press window to expire. Give the input queue one frame
-		// before ordinary paints; forced repaints still bypass this path.
-		this.#inputRenderGraceUntilMs = this.#renderScheduler.now() + TUI.#INPUT_RENDER_GRACE_MS;
+		// Ctrl+C/Esc use app-level double-press windows. Give those gestures one
+		// frame to drain queued input before an ordinary repaint; delaying every
+		// key would make idle navigation pay a full frame of latency.
+		if (matchesKey(data, "ctrl+c") || matchesKey(data, "escape")) {
+			this.#inputRenderGraceUntilMs = this.#renderScheduler.now() + TUI.#INPUT_RENDER_GRACE_MS;
+		}
 		if (this.#inputListeners.size > 0) {
 			let current = data;
 			for (const listener of this.#inputListeners) {
@@ -2696,18 +2721,19 @@ export class TUI extends Container {
 		//     alternate screen to repaint the whole transcript on the normal
 		//     screen — then the next SIGWINCH re-enters the alt screen and paints
 		//     only the tail, so the block flashes in for one frame and vanishes.
-		// A forced render (tool finalization, reset, image reconciliation) must
-		// still preempt: it set #forceViewportRepaintOnNextRender via
-		// #prepareForcedRender and owns the next authoritative paint, so it falls
-		// through. A visible overlay composites over the transcript and needs the
-		// whole window, so it also falls through (overlay resizes are not on the
-		// drag-cost hot path).
-		if (
-			this.#resizeViewportActive &&
-			!this.#forceViewportRepaintOnNextRender &&
-			this.#hasEverRendered &&
-			this.#getTopmostVisibleOverlay() === undefined
-		) {
+		// A FORCED render mid-drag (tool finalization, resetDisplay, image
+		// reconciliation) also stays on the fast path: preempting would leave
+		// the borrowed alternate screen and run the geometry-rebuild full paint
+		// on the normal screen — ED3 plus an O(history) replay that visibly
+		// scrolls the whole transcript through the viewport, once per forced
+		// render and once more at settle. The forced intent is not lost: the
+		// fast path consumes neither #forceViewportRepaintOnNextRender nor
+		// #clearScrollbackOnNextRender, and the settle's authoritative
+		// requestRender(true) honors both — same fold-into-the-settle contract
+		// as the multiplexer resize debounce. A visible overlay composites over
+		// the transcript and needs the whole window, so it falls through
+		// (overlay resizes are not on the drag-cost hot path).
+		if (this.#resizeViewportActive && this.#hasEverRendered && this.#getTopmostVisibleOverlay() === undefined) {
 			this.#componentRenderTargets.clear();
 			this.#renderResizeViewport(width, height);
 			return;
@@ -2777,8 +2803,9 @@ export class TUI extends Container {
 		// verified once (a pending header settling, a barrier clearing above a
 		// shifted tail); rows past the boundary are still-live frozen snapshots,
 		// exempt so a collapsing preview can never spray re-anchors mid-run. A
-		// divergence re-anchors and recommits — duplication, never loss —
-		// instead of silently skipping rows (committed nowhere, painted
+		// divergence re-anchors — feeding the divergenceRebuild erase-and-replay
+		// below (mux fallback: recommit below the stale copy; duplication, never
+		// loss) — instead of silently skipping rows (committed nowhere, painted
 		// nowhere). Skipped on geometry frames (a rewrap legitimately reflows
 		// every row), and skipped when the composed frame's stable prefix
 		// covers every verified row and no rows newly became final.
@@ -2851,7 +2878,21 @@ export class TUI extends Container {
 		const firstPaint = !this.#hasEverRendered;
 		const replaceRequested = this.#clearScrollbackOnNextRender;
 		const geometryRebuild = geometryChanged && !resizeRepaintsInPlace();
-		const fullPaint = firstPaint || replaceRequested || geometryRebuild;
+		// Committed history no longer matches the frame: a finalized block
+		// replaced its scrolled-off live render, or the frame collapsed into
+		// recorded rows. Native scrollback is a render cache, not a court
+		// record — erase and replay so history holds the content exactly once,
+		// instead of recommitting the final form below the stale fragment
+		// (a visibly duplicated block). Multiplexer panes cannot ED3 safely
+		// and keep the repair-below fallback in the branches under this one.
+		const divergenceRebuild =
+			this.#scrollbackRebuildEnabled &&
+			!firstPaint &&
+			!replaceRequested &&
+			!geometryChanged &&
+			!isMultiplexerSession() &&
+			(committedRowsResynced || frameLength <= this.#committedRows);
+		const fullPaint = firstPaint || replaceRequested || geometryRebuild || divergenceRebuild;
 		let windowTop: number;
 		let chunkTo: number;
 		if (fullPaint) {
@@ -2864,16 +2905,17 @@ export class TUI extends Container {
 				frameLength - this.#committedRows < height &&
 				cursorMarkers.some(marker => marker.row >= this.#committedRows))
 		) {
-			// Either the frame shrank into the committed prefix, or a
-			// committed-prefix resync left a focused cursor tail shorter than the
-			// viewport. The latter happens when a streaming/live block had an
-			// append-only prefix committed, then collapses on abort/finalize:
-			// the audit re-anchors #committedRows at the first divergent row, but
-			// flooring windowTop there would pin the editor near the top and
-			// leave blank rows underneath. Re-show the frame tail instead. The
-			// stale committed copy stays in native history; duplicating a few rows
-			// is preferable to a live editor gap and matches the existing
-			// "duplication, never loss" resync contract.
+			// Multiplexer fallback (a direct terminal takes the divergenceRebuild
+			// full paint above): either the frame shrank into the committed
+			// prefix, or a committed-prefix resync left a focused cursor tail
+			// shorter than the viewport. The latter happens when a streaming/live
+			// block had an append-only prefix committed, then collapses on
+			// abort/finalize: the audit re-anchors #committedRows at the first
+			// divergent row, but flooring windowTop there would pin the editor
+			// near the top and leave blank rows underneath. Re-show the frame
+			// tail instead. The stale committed copy stays in native history;
+			// duplicating a few rows is preferable to a live editor gap —
+			// "duplication, never loss" is the ED3-unsafe fallback contract.
 			committedPrefixResliced = true;
 			windowTop = Math.max(0, frameLength - height);
 			chunkTo = windowTop;
@@ -2926,7 +2968,10 @@ export class TUI extends Container {
 		const cursorTrackingLineCount = hasVisibleOverlay ? Math.max(frame.length, windowTop + height) : frame.length;
 
 		const intent: RenderIntent = fullPaint
-			? { kind: "fullPaint", clearScrollback: replaceRequested || geometryRebuild ? !isMultiplexerSession() : false }
+			? {
+					kind: "fullPaint",
+					clearScrollback: divergenceRebuild || ((replaceRequested || geometryRebuild) && !isMultiplexerSession()),
+				}
 			: { kind: "update", chunkTo, windowTop };
 		this.#logRedraw(intent, frameLength, height);