@code-yeongyu/senpi-tui 2026.10.10-4 → 2026.10.10-6

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

@@ -627,6 +627,10 @@ export class TuiBase extends Container {
     /** Minimum interval between scheduled renders. Default preserves the historic ~60fps cap. */
     #minRenderIntervalMs;
     #lastCursorVisibility;
+    #holdScrollbackReplay;
+    #releaseHoldOnInput;
+    #scrollbackStale;
+    #scrollbackCatchUpPending;
     get hasOverlayEntries() {
         return this.overlayStack.length > 0;
     }
@@ -663,6 +667,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 +1268,10 @@ 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.renderRequested = false;
         this.inputRenderPending = false;
         this.cancelRenderTimer();
@@ -1303,6 +1315,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 +1397,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
@@ -1436,6 +1468,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 +2151,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,6 +2179,44 @@ export class TuiBase extends Container {
         this.previousHeight = height;
         this.placementEpoch++;
     }
+    /**
+     * 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)) {
         const previousVisible = this.getViewportRows(this.previousLines, this.previousViewportTop, height);
         const nextVisible = this.getViewportRows(newLines, viewportTop, height);
@@ -2293,11 +2373,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") {
@@ -2514,6 +2607,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 +2636,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 +2894,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-4",
+	"version": "2026.10.10-6",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "dist/index.js",