@gajae-code/tui 0.11.10 → 0.12.0

package/CHANGELOG.md

@@ -2,7 +2,21 @@
 
 ## [Unreleased]
 
-## [0.11.10] - 2026-07-25
+## [0.12.0] - 2026-07-28
+
+### Changed
+
+- Mouse wheel scrolling now moves the session viewport by exactly three lines (`DEFAULT_WHEEL_LINES = 3`) instead of a full page. PageUp/PageDown keep page-sized steps with edge pinning.
+- Manual transcript scrolling now keeps a valid registered status/composer boundary fixed at the bottom independently of output-source registration. Output sources control only the exact semantic new-output notice; transcript selection excludes pinned chrome, short transcript lanes emit blanks instead of duplicating suffix rows, and constrained heights retain the focused suffix component before decorative rows.
+- Manual viewport revisions now advance for semantic changes in a visible capped sidebar even without an inline component; duplicate, elided, hidden, geometry-only, and theme-only changes do not raise a false new-output notice. Equal output-source updates do not render, and constrained pinned suffixes avoid copying transcript-length prefixes.
+- A downward manual scroll (wheel or `PageDown`) that reaches the true transcript bottom now transitions through the existing live-follow transaction instead of repainting another manual frame, so wheel and PageDown automatically return to live output at the bottom. A partial downward movement retains manual ownership and the notice; upward movement never follows. The transition preserves editor focus, pinned chrome, notice clearing, and fatal terminal transaction semantics, clears manual anchor state through the existing transaction, and does not replay manual-era output into native/host scrollback.
+
+### Fixed
+
+- `waitForRenderCommit` / generation-scoped render tokens resolve only after a successful buffer write (or fail open on stopped/unavailable terminals), enabling awaitable progress frames for interactive resume without hanging (#2914).
+- Streaming layout contraction followed by regrowth no longer re-admits an already committed logical row into native terminal scrollback, preventing occasional duplicated assistant lines after Markdown reflow.
+- Repeated clearing of an already-clear viewport output source is now a render-request no-op, matching identical non-null source updates.
+- A terminal width change now ends in one forced full redraw 1000ms after the last observed resize event, repairing stale bands left by lines wrapped at the old column count — across the full transcript, including scrollback history, on every host. Interim resize frames keep their cheap per-host path; the debounce is what makes the one full replay safe, so drag-resizing still does not replay the transcript per `SIGWINCH`. While the user is reading scrollback (manual viewport), the repair is deferred and runs when they return to live output. Height-only changes are unaffected (#3360, #3361).
 
 ## [0.11.7] - 2026-07-22
 ### Fixed

package/README.md

@@ -56,6 +56,14 @@ tui.requestRender(); // Request a re-render
 tui.onDebug = () => console.log("Debug triggered");
 ```
 
+### Manual viewport and pinned suffix
+
+`setBottomPinnedComponent(component)` marks a direct-child boundary. During manual viewport ownership, that child and all later direct children remain fixed at the bottom while rows before it form the scrollable lane; this does not require an output source. `scrollViewportPages()` moves by the lane height minus one; `scrollViewportBy()` supports smaller row steps and rejects non-finite deltas.
+
+`setViewportOutputSource({ identity, revision })` reports semantic output changes without coupling the TUI to message types. A same-identity revision advance while manually scrolled displays the exact notice `New output — type to follow`; following live or changing/removing the identity clears it, while a stale same-identity revision rollback does not.
+
+Pinned rows and the notice are excluded from transcript mouse-selection coordinates. When the terminal is too short, the focused direct-child suffix component is retained before decorative or lower-priority suffix rows.
+
 ### Component Interface
 
 All components implement:

package/dist/types/components/select-list.d.ts

@@ -45,6 +45,7 @@ export declare class SelectList implements Component {
     constructor(items: ReadonlyArray<SelectItem>, maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
     setFilter(filter: string): void;
     setSelectedIndex(index: number): void;
+    handleNavigation(action: "tui.select.up" | "tui.select.down" | "tui.select.pageUp" | "tui.select.pageDown"): void;
     invalidate(): void;
     render(width: number): string[];
     handleInput(keyData: string): void;

package/dist/types/metrics.d.ts

@@ -48,6 +48,7 @@ export interface RenderMetricsSnapshot {
     timerGauges: Record<string, number>;
     helperStats: Record<string, HelperStat>;
     lineCounts: Record<string, LineCountGauge>;
+    structuralCounters: Record<string, number>;
 }
 export declare class RenderMetrics {
     #private;
@@ -73,6 +74,8 @@ export declare class RenderMetrics {
     recordHelper(name: string, durationMs: number): void;
     /** Record a per-render line-count gauge (e.g. "rendered", "normalized", "diffed"). */
     recordLineCount(name: string, value: number): void;
+    /** Accumulate deterministic structural render work without retaining frame data. */
+    recordStructuralCounter(name: string, value?: number): void;
     /**
      * Force a GC when the runtime exposes one and sample RSS as the post-run
      * "return" value used by the memory-leak gate. Callers should drop large

package/dist/types/tui.d.ts

@@ -1,5 +1,7 @@
 import type { Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
+/** Discrete mouse-wheel notch size in terminal rows (xterm/less-style). */
+export declare const DEFAULT_WHEEL_LINES = 3;
 type InputListenerResult = {
     consume?: boolean;
     data?: string;
@@ -9,7 +11,7 @@ type InputListener = (data: string) => InputListenerResult;
  * Component interface - all components must implement this
  */
 export type MouseEvent = {
-    kind: "wheel" | "click";
+    kind: "wheel" | "click" | "drag" | "release";
     direction?: -1 | 1;
     button?: 0;
     /** Terminal cell coordinates, one-based. */
@@ -27,7 +29,7 @@ type OverlayMouseBounds = {
     termWidth: number;
     termHeight: number;
 };
-/** Parse xterm SGR mouse reports. Drag and button-release reports are ignored. */
+/** Parse xterm SGR mouse reports for wheel, left-click, drag, and release events. */
 export declare function parseSgrMouseEvent(data: string): MouseEvent | undefined;
 export interface Component {
     /**
@@ -99,6 +101,11 @@ export interface ViewportAnchorProvider extends Component {
 export interface ViewportAnchorSource {
     id: ViewportAnchorId;
 }
+/** Identity and monotonic revision of the logical output producer. */
+export type ViewportOutputSource = {
+    identity: string;
+    revision: bigint;
+};
 export interface ViewportAnchorSourceRenderer extends Component {
     renderWithViewportAnchorSource(width: number, source: ViewportAnchorSource): ViewportAnchorRender;
 }
@@ -230,6 +237,14 @@ export declare class TUI extends Container {
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: {
         enableMouse?: boolean;
+        copySelection?: (text: string) => void | Promise<void>;
+        /**
+         * Trailing debounce for the settled width repair, in ms. `0` disables the
+         * settled repair (deterministic harnesses need this — a wall-clock-timed
+         * full replay lands at nondeterministic logical positions). Defaults to
+         * `GJC_TUI_WIDTH_SETTLE_MS` / `PI_TUI_WIDTH_SETTLE_MS`, then 1000.
+         */
+        widthSettleMs?: number;
     });
     dispose(): void;
     get fullRedraws(): number;
@@ -243,7 +258,11 @@ export declare class TUI extends Container {
      */
     setClearOnShrink(enabled: boolean): void;
     setFocus(component: Component | null): void;
+    removeChild(component: Component): void;
+    clear(): void;
     setBottomPinnedComponent(component: Component | null): void;
+    /** Report the logical output producer revision without coupling TUI to message types. */
+    setViewportOutputSource(source: ViewportOutputSource | null): void;
     /** Register the direct child whose rows are eligible for semantic viewport anchoring. */
     setViewportAnchorComponent(component: Component | null): void;
     /** Clear manual viewport ownership before replacing the transcript identity namespace. */
@@ -252,6 +271,10 @@ export declare class TUI extends Container {
     prepareViewportAnchorForTranscriptRebuild(): void;
     /** Reveal a semantic viewport anchor without changing the rendered content width. */
     revealViewportAnchor(id: ViewportAnchorId, alignment: "top" | "center" | "bottom"): boolean;
+    scrollViewportBy(deltaRows: number, options?: {
+        /** edge: PageUp/PageDown pin; stable: preserve/center pin for fine wheel motion */
+        pin?: "edge" | "stable";
+    }): boolean;
     scrollViewportPages(direction: -1 | 1): boolean;
     followLiveViewport(): boolean;
     /**
@@ -265,6 +288,15 @@ export declare class TUI extends Container {
     hasOverlay(): boolean;
     invalidate(): void;
     start(): void;
+    /**
+     * Wait for a specific render request generation to be written successfully.
+     *
+     * Render requests are coalesced, so committing a newer generation also commits
+     * every older generation represented by that frame. A stopped or unavailable
+     * terminal resolves waiters false so UI callers can fail open instead of
+     * holding a session operation behind a dead renderer.
+     */
+    waitForRenderCommit(generation: number, timeoutMs?: number): Promise<boolean>;
     get terminalAvailable(): boolean;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
@@ -293,6 +325,7 @@ export declare class TUI extends Container {
      */
     requestResizeRender(): void;
     requestRender(force?: boolean, source?: string): void;
+    requestRenderWithGeneration(force?: boolean, source?: string): number;
     getLineRenderCacheStats(): {
         normalizationSize: number;
         truncationSize: number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.11.10",
+	"version": "0.12.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.11.10",
-		"@gajae-code/utils": "0.11.10",
+		"@gajae-code/natives": "0.12.0",
+		"@gajae-code/utils": "0.12.0",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/components/select-list.ts

@@ -92,6 +92,22 @@ export class SelectList implements Component {
 			this.#findEnabledIndex(clamped, 1, false) ?? this.#findEnabledIndex(clamped, -1, false) ?? -1;
 		this.#syncViewportToIndex(this.#selectedIndex >= 0 ? this.#selectedIndex : clamped);
 	}
+	handleNavigation(action: "tui.select.up" | "tui.select.down" | "tui.select.pageUp" | "tui.select.pageDown"): void {
+		switch (action) {
+			case "tui.select.up":
+				this.#moveSelection(-1);
+				break;
+			case "tui.select.down":
+				this.#moveSelection(1);
+				break;
+			case "tui.select.pageUp":
+				this.#movePage(-1);
+				break;
+			case "tui.select.pageDown":
+				this.#movePage(1);
+				break;
+		}
+	}
 
 	invalidate(): void {
 		// No cached state to invalidate currently

package/src/metrics.ts

@@ -124,6 +124,7 @@ export interface RenderMetricsSnapshot {
 	timerGauges: Record<string, number>;
 	helperStats: Record<string, HelperStat>;
 	lineCounts: Record<string, LineCountGauge>;
+	structuralCounters: Record<string, number>;
 }
 
 function emptyDurationStats(): DurationStats {
@@ -160,6 +161,7 @@ export class RenderMetrics {
 	#timerGauges = new Map<string, number>();
 	#helpers = new Map<string, { count: number; totalMs: number }>();
 	#lineGauges = new Map<string, LineCountGauge>();
+	#structuralCounters = new Map<string, number>();
 	#rssReturn: number | null = null;
 	#heapBaseline: number | null = null;
 	#heapReturn: number | null = null;
@@ -200,6 +202,7 @@ export class RenderMetrics {
 		this.#timerGauges.clear();
 		this.#helpers.clear();
 		this.#lineGauges.clear();
+		this.#structuralCounters.clear();
 		this.#rssReturn = null;
 		this.#heapBaseline = null;
 		this.#heapReturn = null;
@@ -296,6 +299,13 @@ export class RenderMetrics {
 		this.#lineGauges.set(retained, cur);
 	}
 
+	/** Accumulate deterministic structural render work without retaining frame data. */
+	recordStructuralCounter(name: string, value = 1): void {
+		if (!this.#enabled) return;
+		const retained = retainedLabel(this.#structuralCounters, name);
+		this.#structuralCounters.set(retained, (this.#structuralCounters.get(retained) ?? 0) + value);
+	}
+
 	/**
 	 * Force a GC when the runtime exposes one and sample RSS as the post-run
 	 * "return" value used by the memory-leak gate. Callers should drop large
@@ -345,6 +355,10 @@ export class RenderMetrics {
 		return out;
 	}
 
+	#structuralCounterStats(): Record<string, number> {
+		return Object.fromEntries(this.#structuralCounters);
+	}
+
 	snapshot(): RenderMetricsSnapshot {
 		return {
 			enabled: this.#enabled,
@@ -374,6 +388,7 @@ export class RenderMetrics {
 			timerGauges: Object.fromEntries(this.#timerGauges),
 			helperStats: this.#helperStats(),
 			lineCounts: this.#lineCountStats(),
+			structuralCounters: this.#structuralCounterStats(),
 		};
 	}
 }

package/src/terminal.ts

@@ -3,7 +3,6 @@ import * as fs from "node:fs";
 import { $env, $flag, $pickenv } from "@gajae-code/utils";
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
-import { isUnderTerminalMultiplexer } from "./terminal-capabilities";
 
 const TERMINAL_PROGRESS_KEEPALIVE_MS = 1000;
 const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
@@ -52,6 +51,7 @@ export function emergencyTerminalRestore(): void {
 			process.stdout.write(
 				"\x1b[?2004l" + // Disable bracketed paste
 					"\x1b[?1000l" + // Disable normal mouse reporting
+					"\x1b[?1002l" + // Disable button-event mouse reporting
 					"\x1b[?1006l" + // Disable SGR extended mouse reporting
 					"\x1b[?2031l" + // Disable Mode 2031 appearance notifications
 					"\x1b[<u" + // Pop kitty keyboard protocol
@@ -244,8 +244,11 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	setMouseEnabled(enabled: boolean): void {
-		this.#mouseEnabled = enabled && !isUnderTerminalMultiplexer(Bun.env);
-		if (this.#started) this.#safeWrite(this.#mouseEnabled ? "\x1b[?1000h\x1b[?1006h" : "\x1b[?1000l\x1b[?1006l");
+		this.#mouseEnabled = enabled;
+		if (this.#started)
+			this.#safeWrite(
+				this.#mouseEnabled ? "\x1b[?1000l\x1b[?1002h\x1b[?1006h" : "\x1b[?1000l\x1b[?1002l\x1b[?1006l",
+			);
 	}
 
 	start(onInput: (data: string) => void, onResize: () => void): void {
@@ -271,8 +274,9 @@ export class ProcessTerminal implements Terminal {
 
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
 		this.#safeWrite("\x1b[?2004h");
-		// SGR mouse reporting is opt-in and never enabled inside tmux or screen.
-		if (this.#mouseEnabled) this.#safeWrite("\x1b[?1000h\x1b[?1006h");
+		// Button-event reporting preserves wheel input while also letting the TUI implement drag selection.
+		// Clear both tracking variants first so stale modes from another application cannot leak across startup.
+		this.#safeWrite(this.#mouseEnabled ? "\x1b[?1000l\x1b[?1002h\x1b[?1006h" : "\x1b[?1000l\x1b[?1002l\x1b[?1006l");
 
 		// Set up resize handler immediately
 		process.stdout.on("resize", this.#resizeHandler);
@@ -708,6 +712,7 @@ export class ProcessTerminal implements Terminal {
 		this.#mouseEnabled = false;
 		this.#safeWrite("\x1b[?2004l");
 		this.#safeWrite("\x1b[?1000l");
+		this.#safeWrite("\x1b[?1002l");
 		this.#safeWrite("\x1b[?1006l");
 
 		// Disable Mode 2031 appearance change notifications