@code-yeongyu/senpi-tui 2026.10.10 → 2026.10.11

package/dist/tui.d.ts

@@ -466,6 +466,16 @@ export declare abstract class TuiBase extends Container {
     setTerminalColorSchemeNotifications(enabled: boolean): void;
     private queryCellSize;
     stop(options?: TuiStopOptions): void;
+    /**
+     * While a reply streams, a frame that changes rows above the viewport would replay the whole scrollback
+     * (ESC[3J and a full rewrite), which throws a user who scrolled up back to the top (#2836). With the hold
+     * on, such a frame repaints only the viewport and leaves the off-screen rows stale. The terminal cannot
+     * report its scroll position in main-screen mode, so the catch-up replay waits for a moment the user is
+     * surely at the bottom: their next keypress, or `catchUpScrollback()` (the next turn start).
+     */
+    setScrollbackReplayHold(hold: boolean | "until-input"): void;
+    /** Replays the scrollback once if a held frame left rows above the viewport stale. */
+    catchUpScrollback(): void;
     renderNow(force?: boolean): void;
     requestRender(force?: boolean, source?: string): void;
     /**
@@ -539,6 +549,14 @@ export declare abstract class TuiBase extends Container {
     private createViewportInsertScrollPlan;
     private renderViewportInsertScroll;
     private renderScrollbackReplay;
+    /**
+     * The held frame of `setScrollbackReplayHold` (#2836): rows above the old viewport stay as the terminal
+     * shows them (possibly stale), and the frame is rewritten from the old viewport top down. Rows the
+     * document grew by scroll naturally into scrollback in their current form, so nothing is lost there and
+     * nothing is cleared, and a reader who scrolled up keeps their place. Returns false when an image row is
+     * involved, so the caller replays as before.
+     */
+    private renderHeldRepaint;
     private renderMuxViewportRepaint;
     /** Splice overlay content into a base line at a specific column. Single-pass optimized. */
     private compositeLineAt;

package/dist/tui.js

@@ -624,9 +624,15 @@ export function isViewportTUI(tui) {
     return tui[VIEWPORT_TUI] === true;
 }
 export class TuiBase extends Container {
+    /** A multiplexer pane regained focus: the next frame repaints its viewport once (senpi#1704). */
+    #muxViewportRepaintPending;
     /** Minimum interval between scheduled renders. Default preserves the historic ~60fps cap. */
     #minRenderIntervalMs;
     #lastCursorVisibility;
+    #holdScrollbackReplay;
+    #releaseHoldOnInput;
+    #scrollbackStale;
+    #scrollbackCatchUpPending;
     get hasOverlayEntries() {
         return this.overlayStack.length > 0;
     }
@@ -637,6 +643,8 @@ export class TuiBase extends Container {
         this.previousRawLines = [];
         this.normalizeMemo = new Map();
         this.previousKittyImageIds = new Set();
+        /** A multiplexer pane regained focus: the next frame repaints its viewport once (senpi#1704). */
+        this.#muxViewportRepaintPending = false;
         this.previousWidth = 0;
         this.previousHeight = 0;
         this.focusedComponent = null;
@@ -663,6 +671,10 @@ export class TuiBase extends Container {
         this.pendingTerminalColorQueries = [];
         this.terminalColorSchemeListeners = new Set();
         this.terminalColorSchemeNotificationsEnabled = false;
+        this.#holdScrollbackReplay = false;
+        this.#releaseHoldOnInput = false;
+        this.#scrollbackStale = false;
+        this.#scrollbackCatchUpPending = false;
         // Overlay stack for modal components rendered on top of base content
         this.focusOrderCounter = 0;
         this.overlayStack = [];
@@ -1260,6 +1272,11 @@ export class TuiBase extends Container {
     }
     stop(options = {}) {
         this.stopped = true;
+        // The hold itself belongs to the turn (interactive mode sets and releases it); a stop()/start() handover
+        // for an external editor or a suspend in the middle of a turn must not drop it.
+        this.#scrollbackStale = false;
+        this.#scrollbackCatchUpPending = false;
+        this.#muxViewportRepaintPending = false;
         this.renderRequested = false;
         this.inputRenderPending = false;
         this.cancelRenderTimer();
@@ -1303,6 +1320,25 @@ export class TuiBase extends Container {
         this.maxLinesRendered = 0;
         this.previousViewportTop = 0;
     }
+    /**
+     * While a reply streams, a frame that changes rows above the viewport would replay the whole scrollback
+     * (ESC[3J and a full rewrite), which throws a user who scrolled up back to the top (#2836). With the hold
+     * on, such a frame repaints only the viewport and leaves the off-screen rows stale. The terminal cannot
+     * report its scroll position in main-screen mode, so the catch-up replay waits for a moment the user is
+     * surely at the bottom: their next keypress, or `catchUpScrollback()` (the next turn start).
+     */
+    setScrollbackReplayHold(hold) {
+        this.#holdScrollbackReplay = hold !== false;
+        this.#releaseHoldOnInput = hold === "until-input";
+    }
+    /** Replays the scrollback once if a held frame left rows above the viewport stale. */
+    catchUpScrollback() {
+        if (!this.#scrollbackStale)
+            return;
+        this.#scrollbackStale = false;
+        this.#scrollbackCatchUpPending = true;
+        this.requestRender();
+    }
     renderNow(force = false) {
         if (force)
             this.resetForcedRenderState();
@@ -1366,6 +1402,7 @@ export class TuiBase extends Container {
     }
     /** Drop every cached frame so the next render repaints from a clean slate. */
     resetForcedRenderState() {
+        this.#scrollbackCatchUpPending = false;
         this.resetRenderState();
         this.dropPreviousLines();
         this.previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
@@ -1422,9 +1459,22 @@ export class TuiBase extends Container {
         if (this.mode !== "fullscreen") {
             const focus = consumeTmuxFocusEvent(data);
             if (focus.event !== null) {
-                resetCapabilitiesCache();
-                this.invalidate();
-                this.requestRender(true);
+                if (this.shouldPreserveMuxScrollback()) {
+                    // senpi#1704: a forced render re-emitted the whole transcript into the pane's history on every
+                    // focus event. A pane losing focus is not visible, so it repaints nothing; a pane gaining focus
+                    // refreshes the terminal capabilities and repaints its viewport only.
+                    if (focus.event === "in") {
+                        resetCapabilitiesCache();
+                        this.invalidate();
+                        this.#muxViewportRepaintPending = true;
+                        this.requestRender();
+                    }
+                }
+                else {
+                    resetCapabilitiesCache();
+                    this.invalidate();
+                    this.requestRender(true);
+                }
                 if (focus.data.length === 0)
                     return;
                 data = focus.data;
@@ -1436,6 +1486,15 @@ export class TuiBase extends Container {
         if (this.consumeTerminalColorSchemeReport(data)) {
             return;
         }
+        // A key press means the user is at the bottom again. Terminal reports (mouse/wheel, OSC/DCS replies,
+        // DEC private reports, window and cell-size reports) are not the user and must not trigger it.
+        if (!isTerminalReport(data)) {
+            if (this.#releaseHoldOnInput) {
+                this.#releaseHoldOnInput = false;
+                this.#holdScrollbackReplay = false;
+            }
+            this.catchUpScrollback();
+        }
         if (this.inputListeners.size > 0) {
             let current = data;
             for (const listener of this.inputListeners) {
@@ -2110,6 +2169,7 @@ export class TuiBase extends Container {
         this.placementEpoch++;
     }
     renderScrollbackReplay(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow) {
+        this.#scrollbackStale = false;
         let buffer = TUI.FRAME_BEGIN;
         buffer += this.deleteKittyImages(this.previousKittyImageIds);
         if (!this.shouldPreserveMuxScrollback()) {
@@ -2137,16 +2197,59 @@ export class TuiBase extends Container {
         this.previousHeight = height;
         this.placementEpoch++;
     }
-    renderMuxViewportRepaint(newLines, rawLines, cursorPos, width, height, viewportTop = Math.max(0, newLines.length - height)) {
+    /**
+     * The held frame of `setScrollbackReplayHold` (#2836): rows above the old viewport stay as the terminal
+     * shows them (possibly stale), and the frame is rewritten from the old viewport top down. Rows the
+     * document grew by scroll naturally into scrollback in their current form, so nothing is lost there and
+     * nothing is cleared, and a reader who scrolled up keeps their place. Returns false when an image row is
+     * involved, so the caller replays as before.
+     */
+    renderHeldRepaint(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow) {
+        const start = Math.min(prevViewportTop, Math.max(0, newLines.length - height));
+        const rowCount = Math.max(height, newLines.length - start);
+        const rows = Array.from({ length: rowCount }, (_, index) => newLines[start + index] ?? "");
+        const previousVisible = this.getViewportRows(this.previousLines, prevViewportTop, height);
+        if (rows.some(isImageLine) || previousVisible.some(isImageLine))
+            return false;
+        let buffer = TUI.FRAME_BEGIN;
+        const currentScreenRow = Math.max(0, Math.min(height - 1, hardwareCursorRow - prevViewportTop));
+        if (currentScreenRow > 0)
+            buffer += `\x1b[${currentScreenRow}A`;
+        for (let row = 0; row < rows.length; row++) {
+            if (row > 0)
+                buffer += "\r\n";
+            buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
+            buffer += rows[row];
+        }
+        const lastRow = start + rows.length - 1;
+        buffer = this.finishFrame(buffer, cursorPos, newLines.length, lastRow);
+        writeBounded(this.terminal, buffer);
+        this.#scrollbackStale = true;
+        this.cursorRow = Math.max(0, newLines.length - 1);
+        this.maxLinesRendered = newLines.length;
+        this.previousViewportTop = Math.max(0, lastRow + 1 - height);
+        this.setPreviousLines(newLines, rawLines);
+        this.previousKittyImageIds = this.collectKittyImageIds(newLines);
+        this.previousWidth = width;
+        this.previousHeight = height;
+        this.placementEpoch++;
+        return true;
+    }
+    renderMuxViewportRepaint(newLines, rawLines, cursorPos, width, height, viewportTop = Math.max(0, newLines.length - height), home = "relative") {
         const previousVisible = this.getViewportRows(this.previousLines, this.previousViewportTop, height);
         const nextVisible = this.getViewportRows(newLines, viewportTop, height);
         if (previousVisible.some(isImageLine) || nextVisible.some(isImageLine)) {
             return false;
         }
         let buffer = TUI.FRAME_BEGIN;
-        const currentScreenRow = Math.max(0, Math.min(height - 1, this.hardwareCursorRow - this.previousViewportTop));
-        if (currentScreenRow > 0) {
-            buffer += `\x1b[${currentScreenRow}A`;
+        if (home === "absolute") {
+            buffer += "\x1b[H";
+        }
+        else {
+            const currentScreenRow = Math.max(0, Math.min(height - 1, this.hardwareCursorRow - this.previousViewportTop));
+            if (currentScreenRow > 0) {
+                buffer += `\x1b[${currentScreenRow}A`;
+            }
         }
         for (let row = 0; row < height; row++) {
             if (row > 0)
@@ -2293,11 +2396,24 @@ export class TuiBase extends Container {
         const normalizedLines = this.applyViewportLineResets(rawLines, prevViewportTop, height, !widthChanged && !heightChanged);
         newLines = normalizedLines.lines;
         const preserveMuxScrollback = this.shouldPreserveMuxScrollback();
+        if (this.#scrollbackCatchUpPending) {
+            this.#scrollbackCatchUpPending = false;
+            if (!preserveMuxScrollback && !widthChanged && !heightChanged) {
+                this.renderScrollbackReplay(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow);
+                return;
+            }
+            // A resize frame takes its own path below; if that path does not rewrite the scrollback, the
+            // rows are still stale and the next key press catches up.
+            if (!preserveMuxScrollback)
+                this.#scrollbackStale = true;
+        }
         // Helper to clear scrollback and viewport and render all new lines
         const fullRender = (clear, clearScrollback = clear) => {
             this.fullRedrawCount += 1;
             let buffer = TUI.FRAME_BEGIN;
             if (clear) {
+                if (clearScrollback)
+                    this.#scrollbackStale = false;
                 buffer += this.deleteKittyImages(this.previousKittyImageIds);
                 buffer += "\x1b[2J\x1b[H";
                 if (clearScrollback && !preserveMuxScrollback && process.platform !== "win32") {
@@ -2362,11 +2478,37 @@ export class TuiBase extends Container {
         }
         // Width changes always need a full re-render because wrapping changes.
         if (widthChanged) {
+            // A width change (or a forced render) repaints everything below; a focus repaint queued in the
+            // same tick is satisfied by it.
+            this.#muxViewportRepaintPending = false;
             logRedraw(`terminal width changed (${this.previousWidth} -> ${width})`);
-            // In multiplexers, re-emit the viewport without 3J so pane history survives; an older copy may remain above.
+            // In a multiplexer only the re-wrapped viewport is repainted: re-emitting every line of the buffer scrolled a
+            // copy of the whole transcript into the pane's history on each width change (senpi#1704). Rows already in
+            // that history keep their old wrapping. The pane re-wrapped the screen itself, so the repaint homes there.
+            if (preserveMuxScrollback && this.previousWidth > 0) {
+                if (this.renderMuxViewportRepaint(newLines, rawLines, cursorPos, width, height, undefined, "absolute"))
+                    return;
+            }
             fullRender(true, !preserveMuxScrollback);
             return;
         }
+        if (this.#muxViewportRepaintPending) {
+            this.#muxViewportRepaintPending = false;
+            if (preserveMuxScrollback && !heightChanged) {
+                logRedraw("multiplexer pane focus regained");
+                // A frame queued before the focus event may have grown the content: follow it exactly as an
+                // ordinary frame does, so rows added below (the editor, the status line) stay on screen.
+                // After a shrink the viewport keeps its top (as the deleted-lines path does), so the repaint does
+                // not scroll rows already in the pane's history into view a second time.
+                const focusViewportTop = newLines.length > prevViewportTop
+                    ? Math.max(prevViewportTop, newLines.length - height)
+                    : Math.max(0, newLines.length - height);
+                if (!this.renderMuxViewportRepaint(newLines, rawLines, cursorPos, width, height, focusViewportTop)) {
+                    fullRender(true, false);
+                }
+                return;
+            }
+        }
         // Height changes normally need a full re-render to keep the visible viewport aligned,
         // but Termux changes height when the software keyboard shows or hides.
         // In that environment, a full redraw causes the entire history to replay on every toggle.
@@ -2514,6 +2656,10 @@ export class TuiBase extends Container {
                             fullRender(true, false);
                         }
                     }
+                    else if (this.#holdScrollbackReplay &&
+                        this.renderHeldRepaint(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow)) {
+                        // Held: rows above the old viewport stay stale until the catch-up replay.
+                    }
                     else {
                         this.renderScrollbackReplay(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow);
                     }
@@ -2539,6 +2685,10 @@ export class TuiBase extends Container {
                             fullRender(true, false);
                         }
                     }
+                    else if (this.#holdScrollbackReplay &&
+                        this.renderHeldRepaint(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow)) {
+                        // Held: rows above the old viewport stay stale until the catch-up replay.
+                    }
                     else {
                         this.renderScrollbackReplay(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow);
                     }
@@ -2793,6 +2943,18 @@ export class TuiBase extends Container {
         });
     }
 }
+/**
+ * Input that the terminal sends on its own rather than the user typing: mouse reports, OSC/DCS/APC
+ * replies, DEC private reports (`ESC[?...`) and window/cell-size reports (`ESC[...t`). OSC/DCS/APC need
+ * a body after the introducer, so a legacy Alt+] / Alt+Shift+P / Alt+_ key press is still a key.
+ */
+function isTerminalReport(data) {
+    return (data.startsWith("\x1b[<") ||
+        data.startsWith("\x1b[M") ||
+        (data.length > 2 && (data.startsWith("\x1b]") || data.startsWith("\x1bP") || data.startsWith("\x1b_"))) ||
+        data.startsWith("\x1b[?") ||
+        /^\x1b\[\d+(;\d+)*t$/.test(data));
+}
 /** Legacy main-screen renderer export. */
 export class TUI extends TuiBase {
     constructor() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-tui",
-	"version": "2026.10.10",
+	"version": "2026.10.11",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "dist/index.js",