@code-yeongyu/senpi-tui 2026.10.10 → 2026.10.12

package/dist/components/editor-line-render.d.ts

@@ -4,10 +4,17 @@ export interface EditorLineCursor {
     readonly marker: string;
     readonly drawFakeCursor: boolean;
 }
+/** A keyword-run piece on one row; `runStart` may be negative when the run began on an earlier row. */
+export interface EditorKeywordRange extends MentionRange {
+    readonly runStart: number;
+    readonly runLength: number;
+}
 export interface EditorLineRenderInput {
     readonly text: string;
     readonly mentions: readonly MentionRange[];
     readonly mentionStyle: (text: string) => string;
+    readonly keywords?: readonly EditorKeywordRange[];
+    readonly keywordStyle?: (text: string, index: number, length: number) => string;
     readonly cursor: EditorLineCursor | undefined;
     readonly firstGrapheme: (text: string) => string;
 }
@@ -16,6 +23,8 @@ export interface EditorLineRenderResult {
     /** True when a fake cursor cell was appended past the text (adds one column). */
     readonly cursorAppended: boolean;
 }
+/** Splits runs found in `lines.join("\n")` into per-logical-line pieces keyed by line index. */
+export declare function keywordRangesByLine(lines: readonly string[], runs: readonly MentionRange[]): Map<number, EditorKeywordRange[]>;
 /**
  * Compose one visible editor row: mention ranges get `mentionStyle`, the
  * cursor grapheme gets reverse video, and every fragment is styled on its

package/dist/components/editor-line-render.js

@@ -4,6 +4,39 @@ function clampMentions(mentions, length) {
         .map((range) => ({ start: Math.max(0, range.start), end: Math.min(length, range.end) }))
         .filter((range) => range.start < range.end);
 }
+/** Splits runs found in `lines.join("\n")` into per-logical-line pieces keyed by line index. */
+export function keywordRangesByLine(lines, runs) {
+    const byLine = new Map();
+    let lineStart = 0;
+    for (let line = 0; line < lines.length; line++) {
+        const lineEnd = lineStart + (lines[line]?.length ?? 0);
+        for (const run of runs) {
+            const start = Math.max(run.start, lineStart);
+            const end = Math.min(run.end, lineEnd);
+            if (start >= end)
+                continue;
+            const pieces = byLine.get(line) ?? [];
+            pieces.push({
+                start: start - lineStart,
+                end: end - lineStart,
+                runStart: run.start - lineStart,
+                runLength: run.end - run.start,
+            });
+            byLine.set(line, pieces);
+        }
+        lineStart = lineEnd + 1;
+    }
+    return byLine;
+}
+function styleKeywordSegment(segment, from, range, style) {
+    let out = "";
+    let offset = from;
+    for (const char of segment) {
+        out += style(char, offset - range.runStart, range.runLength);
+        offset += char.length;
+    }
+    return out;
+}
 function cutPoints(length, mentions, cursorGlyph) {
     const cuts = new Set([0, length]);
     for (const range of mentions) {
@@ -24,11 +57,16 @@ function cutPoints(length, mentions, cursorGlyph) {
 export function renderEditorLine(input) {
     const { text, cursor } = input;
     const mentions = clampMentions(input.mentions, text.length);
+    const keywordStyle = input.keywordStyle;
+    const keywords = keywordStyle
+        ? (input.keywords ?? []).filter((range) => Math.max(0, range.start) < Math.min(text.length, range.end) &&
+            !mentions.some((mention) => range.start < mention.end && mention.start < range.end))
+        : [];
     const cursorInText = cursor !== undefined && cursor.pos < text.length;
     const cursorGlyph = cursorInText && cursor.drawFakeCursor
         ? { start: cursor.pos, end: cursor.pos + input.firstGrapheme(text.slice(cursor.pos)).length }
         : undefined;
-    const points = cutPoints(text.length, mentions, cursorGlyph);
+    const points = cutPoints(text.length, [...mentions, ...clampMentions(keywords, text.length)], cursorGlyph);
     let out = "";
     for (let index = 0; index < points.length - 1; index++) {
         const from = points[index] ?? 0;
@@ -42,6 +80,10 @@ export function renderEditorLine(input) {
         else if (mentions.some((range) => from >= range.start && to <= range.end)) {
             out += input.mentionStyle(segment);
         }
+        else if (keywordStyle) {
+            const keyword = keywords.find((range) => from >= range.start && to <= range.end);
+            out += keyword ? styleKeywordSegment(segment, from, keyword, keywordStyle) : segment;
+        }
         else {
             out += segment;
         }

package/dist/components/editor.d.ts

@@ -1,4 +1,4 @@
-import type { AutocompleteProvider } from "../autocomplete.ts";
+import type { AutocompleteProvider, MentionRange } from "../autocomplete.ts";
 import type { EditorSubmitDetails } from "../editor-component.ts";
 import { type EditorImageState } from "../image-markers.ts";
 import { type EditorPasteState } from "../paste-markers.ts";
@@ -27,10 +27,22 @@ export interface TextChunk {
  * @returns Array of chunks with text and position information
  */
 export declare function wordWrapLine(line: string, maxWidth: number, preSegmented?: Intl.SegmentData[]): TextChunk[];
+/**
+ * Per-character decoration for keyword runs found in the whole editor text
+ * (lines joined with "\n"). `style` receives one character plus its offset
+ * within the run and the run length, so a gradient stays continuous across
+ * wrapped rows and logical lines. Decoration only: it never changes widths.
+ */
+export interface EditorKeywordHighlight {
+    find: (text: string) => readonly MentionRange[];
+    style: (text: string, index: number, length: number) => string;
+}
 export interface EditorTheme {
     borderColor: (str: string) => string;
     /** Style for resolved mention tokens (for example a known `$skill`); omit to render them plain. */
     mention?: (str: string) => string;
+    /** Optional keyword-run decoration; a mention or the cursor grapheme takes precedence over it. */
+    keywordHighlight?: EditorKeywordHighlight;
     /**
      * Theme for the autocomplete/slash SelectList built by
      * createAutocompleteList(). May carry the optional `renderRow` seam (see
@@ -61,6 +73,7 @@ export declare class Editor implements Component, Focusable {
     private renderedVisibleLineCount;
     private renderedAutocompleteHeight;
     private scrollOffset;
+    private keywordRunsCache?;
     borderColor: (str: string) => string;
     private autocompleteProvider?;
     private autocompleteTriggerCharacters;
@@ -153,6 +166,7 @@ export declare class Editor implements Component, Focusable {
     private getWrappedLine;
     protected renderTopBorder(width: number, hiddenLineCount: number): string;
     protected renderBottomBorder(width: number, hiddenLineCount: number): string;
+    private keywordRangesByLine;
     render(width: number): string[];
     handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
     handleInput(data: string): void;

package/dist/components/editor.js

@@ -9,7 +9,7 @@ import { CURSOR_MARKER, } from "../tui.js";
 import { UndoStack } from "../undo-stack.js";
 import { autocompleteBoundaryRegex, autocompleteSeparatorRegex, cjkBreakRegex, getGraphemeSegmenter, getWordSegmenter, isWhitespaceChar, sliceByColumn, visibleWidth, } from "../utils.js";
 import { findWordBackward, findWordForward } from "../word-navigation.js";
-import { renderEditorLine } from "./editor-line-render.js";
+import { keywordRangesByLine, renderEditorLine } from "./editor-line-render.js";
 import { SelectList } from "./select-list.js";
 const graphemeSegmenter = getGraphemeSegmenter();
 const wordSegmenter = getWordSegmenter();
@@ -461,6 +461,13 @@ export class Editor {
         const border = hiddenLineCount > 0 ? createScrollBorder("↓", hiddenLineCount, width) : "─".repeat(width);
         return this.borderColor(border);
     }
+    keywordRangesByLine(highlight) {
+        const text = this.state.lines.join("\n");
+        if (this.keywordRunsCache?.text !== text) {
+            this.keywordRunsCache = { text, byLine: keywordRangesByLine(this.state.lines, highlight.find(text)) };
+        }
+        return this.keywordRunsCache.byLine;
+    }
     render(width) {
         const maxPadding = Math.max(0, Math.floor((width - 1) / 2));
         const paddingX = Math.min(this.paddingX, maxPadding);
@@ -518,6 +525,14 @@ export class Editor {
                 end: range.end - layoutLine.startIndex,
             }));
         };
+        const keywordHighlight = this.theme.keywordHighlight;
+        const keywordRangesByLine = keywordHighlight ? this.keywordRangesByLine(keywordHighlight) : undefined;
+        const keywordRangesFor = (layoutLine) => (keywordRangesByLine?.get(layoutLine.logicalLine) ?? []).map((range) => ({
+            start: range.start - layoutLine.startIndex,
+            end: range.end - layoutLine.startIndex,
+            runStart: range.runStart - layoutLine.startIndex,
+            runLength: range.runLength,
+        }));
         for (const layoutLine of visibleLines) {
             let lineVisibleWidth = visibleWidth(layoutLine.text);
             let cursorInPadding = false;
@@ -529,6 +544,8 @@ export class Editor {
                 text: layoutLine.text,
                 mentions: mentionRangesFor(layoutLine),
                 mentionStyle: mentionStyle ?? ((text) => text),
+                keywords: keywordRangesFor(layoutLine),
+                keywordStyle: keywordHighlight?.style,
                 cursor,
                 firstGrapheme: (text) => [...this.segment(text, "grapheme")][0]?.segment ?? "",
             });

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { type AutocompleteItem, type AutocompleteProvider, type AutocompleteSugg
 export { backgroundAnsi, type Color, type ColorMixSpace, colorToHex, colorToOkhsl, colorToOklch, colorToRgb, foregroundAnsi, type IndexedColor, indexedColor, mixColors, type OkhslChannels, type OklchChannels, type OklchColorValue, okhslColor, oklchColor, parseColor, type RgbColorValue, rgbColor, styleText, styleTextWithAnsi, type TerminalColorMode, type TextAttributes, type TextStyle, } from "./colors.ts";
 export { Box } from "./components/box.ts";
 export { CancellableLoader } from "./components/cancellable-loader.ts";
-export { Editor, type EditorOptions, type EditorTheme, } from "./components/editor.ts";
+export { Editor, type EditorKeywordHighlight, type EditorOptions, type EditorTheme, } from "./components/editor.ts";
 export { HStack } from "./components/h-stack.ts";
 export { Image, type ImageOptions, type ImageTheme } from "./components/image.ts";
 export { Input } from "./components/input.ts";

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);
                     }
@@ -2679,7 +2829,7 @@ export class TuiBase extends Container {
         }
         buffer = this.finishFrame(buffer, cursorPos, newLines.length, finalCursorRow);
         if (process.env.PI_TUI_DEBUG === "1") {
-            const debugDir = "/tmp/tui";
+            const debugDir = path.join(os.tmpdir(), "tui");
             fs.mkdirSync(debugDir, { recursive: true });
             const debugPath = path.join(debugDir, `render-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);
             const debugData = [
@@ -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.12",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "dist/index.js",
@@ -10,7 +10,7 @@
 		"build:native:darwin": "native/darwin/build.sh",
 		"build:native:linux": "native/linux/build.sh",
 		"build:native:win32": "node native/win32/build.mjs",
-		"test": "node --test --import tsx --import ./test/setup-multiplexer-env.mjs --test-reporter=dot --test-reporter-destination=stdout test/*.test.ts",
+		"test": "node ../../scripts/run-tests.mjs node --test --import tsx --import ./test/setup-multiplexer-env.mjs --test-reporter=dot --test-reporter-destination=stdout test/*.test.ts",
 		"prepublishOnly": "npm run clean && npm run build",
 		"bench:frame-cost": "tsx bench/frame-cost.ts"
 	},