@code-yeongyu/senpi-tui 2026.10.18 → 2026.10.19

package/dist/escape-window.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A pending lone ESC whose next input is delivered after the escape window is
+ * released as a standalone Escape press before the new input is processed. The
+ * decision uses the arrival-clock gap observed at delivery time, so an
+ * over-window gap is always treated as a lone Escape regardless of whether the
+ * flush timer callback ran first (#3628). Within the window the pair still
+ * merges into one Alt-key sequence.
+ */
+export declare function isStaleEscape(pending: string, gapMs: number | undefined, escapeWindowMs: number): boolean;
+//# sourceMappingURL=escape-window.d.ts.map

package/dist/escape-window.js

@@ -0,0 +1,12 @@
+/**
+ * A pending lone ESC whose next input is delivered after the escape window is
+ * released as a standalone Escape press before the new input is processed. The
+ * decision uses the arrival-clock gap observed at delivery time, so an
+ * over-window gap is always treated as a lone Escape regardless of whether the
+ * flush timer callback ran first (#3628). Within the window the pair still
+ * merges into one Alt-key sequence.
+ */
+export function isStaleEscape(pending, gapMs, escapeWindowMs) {
+    return pending === "\x1b" && gapMs !== undefined && gapMs >= escapeWindowMs;
+}
+//# sourceMappingURL=escape-window.js.map

package/dist/stdin-buffer.js

@@ -18,9 +18,10 @@
  */
 import { StringDecoder } from "node:string_decoder";
 import { EventEmitter } from "events";
+import { isStaleEscape } from "./escape-window.js";
 const ESC = "\x1b";
 const DEFAULT_SEQUENCE_TIMEOUT_MS = 50;
-const DEFAULT_ESCAPE_TIMEOUT_MS = 10;
+const DEFAULT_ESCAPE_TIMEOUT_MS = 50;
 const DEFAULT_BURST_WINDOW_MS = 20;
 const BRACKETED_PASTE_START = "\x1b[200~";
 const BRACKETED_PASTE_END = "\x1b[201~";
@@ -299,12 +300,16 @@ export class StdinBuffer extends EventEmitter {
             clearTimeout(this.burstTimer);
             this.burstTimer = null;
         }
-        this.buffer += str;
         const chunkAt = str.length > 0 ? this.clock() : undefined;
         const burstGap = chunkAt !== undefined && this.lastInputAt !== undefined ? chunkAt - this.lastInputAt : undefined;
         if (chunkAt !== undefined) {
             this.lastInputAt = chunkAt;
         }
+        if (isStaleEscape(this.buffer, burstGap, this.escapeTimeoutMs)) {
+            this.buffer = "";
+            this.emitDataSequence(ESC);
+        }
+        this.buffer += str;
         if (this.heldNewline.length > 0) {
             // The clock decides, not timer delivery: a read outside the window means the held line
             // break was an Enter, even when its release timer has not fired yet (a stalled loop).

package/dist/terminal-capabilities.d.ts

@@ -6,6 +6,8 @@ export interface TerminalCapabilities {
     hyperlinks: boolean;
     tmuxPassthrough?: boolean;
     kittyUnicodePlaceholders?: boolean;
+    /** Shown next to the image placeholder when the terminal could show images after a user action. */
+    imageHint?: string;
 }
 export interface DetectedTerminalCapabilities extends TerminalCapabilities {
     cellDimensions?: {

package/dist/terminal-capabilities.js

@@ -1,5 +1,6 @@
 import { decideTmuxImageCapability, parseTmuxKittyTerminalOverride, } from "./tmux-image-capability.js";
 import { probeTmuxImageState } from "./tmux-image-probe.js";
+import { isOldWindowsWezTerm, WEZTERM_WINDOWS_IMAGES_HINT } from "./wezterm-windows-images.js";
 export function outerKittyGraphicsMode(clientTermname) {
     const term = clientTermname.trim().toLowerCase();
     return term.includes("kitty") || term.includes("ghostty") || term.includes("warp") ? "placeholder" : null;
@@ -33,7 +34,9 @@ export function detectTerminalCapabilities(env = process.env, platform = process
         return { images: "kitty", trueColor: true, hyperlinks: true };
     }
     if (env.WEZTERM_PANE || termProgram === "wezterm") {
-        return { images: "kitty", trueColor: true, hyperlinks: true };
+        return isOldWindowsWezTerm(env.TERM_PROGRAM_VERSION, platform)
+            ? { images: null, trueColor: true, hyperlinks: true, imageHint: WEZTERM_WINDOWS_IMAGES_HINT }
+            : { images: "kitty", trueColor: true, hyperlinks: true };
     }
     if (termProgram === "iterm.app" || env.ITERM_SESSION_ID) {
         return { images: "iterm2", trueColor: true, hyperlinks: true };

package/dist/terminal-image.js

@@ -3,6 +3,7 @@ import { isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
 import { detectTerminalCapabilities, } from "./terminal-capabilities.js";
 import { sanitizeTerminalLabel, shortenImagePath } from "./terminal-text.js";
+import { isOldWindowsWezTerm, WEZTERM_WINDOWS_IMAGES_HINT } from "./wezterm-windows-images.js";
 export { outerKittyGraphicsMode } from "./terminal-capabilities.js";
 let cachedCapabilities = null;
 let capabilityOverrides = {};
@@ -53,7 +54,9 @@ function detectCapabilitiesFromEnvironment(tmuxForwardsHyperlink) {
         return { images: "kitty", trueColor: true, hyperlinks: true };
     }
     if (process.env.WEZTERM_PANE || termProgram === "wezterm") {
-        return { images: "kitty", trueColor: true, hyperlinks: true };
+        return isOldWindowsWezTerm(process.env.TERM_PROGRAM_VERSION, process.platform)
+            ? { images: null, trueColor: true, hyperlinks: true, imageHint: WEZTERM_WINDOWS_IMAGES_HINT }
+            : { images: "kitty", trueColor: true, hyperlinks: true };
     }
     // Warp supports the Kitty graphics protocol and OSC 8 hyperlinks.
     if (termProgram === "warpterminal" || process.env.WARP_SESSION_ID || process.env.WARP_TERMINAL_SESSION_UUID) {
@@ -86,6 +89,11 @@ function detectCapabilitiesFromEnvironment(tmuxForwardsHyperlink) {
 function parseBooleanCapabilityOverride(value) {
     return value === "1" ? true : value === "0" ? false : undefined;
 }
+// The hint explains why detection turned images off; an explicit image choice makes it wrong.
+function withoutImageHint(caps) {
+    const { imageHint: _imageHint, ...rest } = caps;
+    return rest;
+}
 export function detectCapabilities(tmuxForwardsHyperlink, tmuxPassthroughState) {
     if (!tmuxForwardsHyperlink || !tmuxPassthroughState) {
         const hyperlinks = parseBooleanCapabilityOverride(process.env.PI_HYPERLINKS);
@@ -98,7 +106,7 @@ export function detectCapabilities(tmuxForwardsHyperlink, tmuxPassthroughState)
                 : undefined;
         const trueColor = parseBooleanCapabilityOverride(process.env.PI_TRUE_COLOR);
         return {
-            ...detected,
+            ...(images !== undefined ? withoutImageHint(detected) : detected),
             ...(images !== undefined ? { images } : {}),
             ...(trueColor !== undefined ? { trueColor } : {}),
             ...(hyperlinks !== undefined ? { hyperlinks } : {}),
@@ -125,8 +133,9 @@ export function detectCapabilities(tmuxForwardsHyperlink, tmuxPassthroughState)
 export function getCapabilities() {
     if (!cachedCapabilities) {
         const hyperlinks = capabilityOverrides.hyperlinks;
+        const detected = detectCapabilities(hyperlinks === undefined ? undefined : () => hyperlinks);
         cachedCapabilities = {
-            ...detectCapabilities(hyperlinks === undefined ? undefined : () => hyperlinks),
+            ...(capabilityOverrides.images !== undefined ? withoutImageHint(detected) : detected),
             ...capabilityOverrides,
         };
     }
@@ -142,7 +151,8 @@ export function resetCapabilitiesCache() {
 export function setCapabilityOverrides(overrides) {
     if (capabilityOverrides.images === overrides.images &&
         capabilityOverrides.trueColor === overrides.trueColor &&
-        capabilityOverrides.hyperlinks === overrides.hyperlinks) {
+        capabilityOverrides.hyperlinks === overrides.hyperlinks &&
+        capabilityOverrides.imageHint === overrides.imageHint) {
         return;
     }
     capabilityOverrides = { ...overrides };
@@ -657,6 +667,7 @@ export function imageFallback(mimeType, dimensions, filename) {
     parts.push(`[${sanitizeTerminalLabel(mimeType)}]`);
     if (dimensions)
         parts.push(`${dimensions.widthPx}x${dimensions.heightPx}`);
-    return `[Image: ${parts.join(" ")}]`;
+    const hint = getCapabilities().imageHint;
+    return hint ? `[Image: ${parts.join(" ")}] (${hint})` : `[Image: ${parts.join(" ")}]`;
 }
 //# sourceMappingURL=terminal-image.js.map

package/dist/terminal.d.ts

@@ -74,9 +74,10 @@ export interface ProcessTerminalOptions {
 /**
  * Resolve how long to wait for the rest of an escape sequence before
  * dispatching a lone ESC as the Escape key. Legacy Alt+key input is ESC plus
- * another byte, so high-latency transports need a longer reassembly window.
+ * another byte, so high-latency transports (SSH, the WSL interop pipe) need a
+ * longer reassembly window.
  */
-export declare function resolveEscapeTimeoutMs(env?: NodeJS.ProcessEnv): number;
+export declare function resolveEscapeTimeoutMs(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): number;
 /**
  * Resolve how long a line break that ends a read with text is held as a possible paste fragment
  * when the terminal sends no bracketed-paste markers. Paste chunks over SSH arrive further apart,

package/dist/terminal.js

@@ -7,6 +7,7 @@ import { getNativePlatformHelper } from "./native-platform.js";
 import { observeProcessStderrWrites } from "./stderr-observer.js";
 import { StdinBuffer } from "./stdin-buffer.js";
 import { queryTmuxCursorPosition } from "./tmux-cursor-query.js";
+import { isWslSession } from "./wsl-session.js";
 const TERMINAL_PROGRESS_KEEPALIVE_MS = 1000;
 const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
 const TERMINAL_PROGRESS_CLEAR_SEQUENCE = "\x1b]9;4;0\x07";
@@ -161,22 +162,23 @@ function unsubscribeFromStdinErrors(subscriber) {
     if (stdinErrorSubscribers.size === 0)
         process.stdin.removeListener("error", dispatchStdinError);
 }
-const DEFAULT_ESCAPE_TIMEOUT_MS = 10;
-const DEFAULT_SSH_ESCAPE_TIMEOUT_MS = 100;
+const DEFAULT_ESCAPE_TIMEOUT_MS = 50;
+const DEFAULT_REMOTE_ESCAPE_TIMEOUT_MS = 100;
 const DEFAULT_BURST_WINDOW_MS = 20;
 const DEFAULT_SSH_BURST_WINDOW_MS = 100;
 /**
  * Resolve how long to wait for the rest of an escape sequence before
  * dispatching a lone ESC as the Escape key. Legacy Alt+key input is ESC plus
- * another byte, so high-latency transports need a longer reassembly window.
+ * another byte, so high-latency transports (SSH, the WSL interop pipe) need a
+ * longer reassembly window.
  */
-export function resolveEscapeTimeoutMs(env = process.env) {
+export function resolveEscapeTimeoutMs(env = process.env, platform = process.platform) {
     const configured = Number(env.PI_TUI_ESC_TIMEOUT);
     if (Number.isFinite(configured) && configured > 0) {
         return configured;
     }
-    if (env.SSH_CONNECTION || env.SSH_TTY) {
-        return DEFAULT_SSH_ESCAPE_TIMEOUT_MS;
+    if (env.SSH_CONNECTION || env.SSH_TTY || isWslSession(env, platform)) {
+        return DEFAULT_REMOTE_ESCAPE_TIMEOUT_MS;
     }
     return DEFAULT_ESCAPE_TIMEOUT_MS;
 }

package/dist/tui-main-screen.d.ts

@@ -12,6 +12,11 @@ export interface TuiMainScreenRenderState {
 export declare class TuiMainScreen extends TuiBase {
     readonly mode: "regular";
     private trackingEnabled;
+    /**
+     * The app cannot scroll the terminal's scrollback, so the first wheel report while armed hands the
+     * mouse back to the terminal; the next key press arms it again (senpi#3604).
+     */
+    private yielded;
     private readonly clicks;
     /**
      * A press stays clickable only while the committed frame and component tree it hit are unchanged.
@@ -19,6 +24,7 @@ export declare class TuiMainScreen extends TuiBase {
      */
     private mousePress?;
     constructor(...args: ConstructorParameters<typeof TuiBase>);
+    mouseCaptureState(): "off" | "armed" | "yielded";
     protected applyMouseTracking(enabled: boolean): void;
     protected beforeTerminalStop(): void;
     protected doRender(): void;
@@ -26,6 +32,8 @@ export declare class TuiMainScreen extends TuiBase {
     private pressLayoutUnchanged;
     private applyMouseResult;
     private handleMouseInput;
+    private yieldToTerminal;
+    private rearmAfterYield;
     captureRenderState(): TuiMainScreenRenderState;
     restoreRenderState(state: TuiMainScreenRenderState): void;
 }

package/dist/tui-main-screen.js

@@ -1,16 +1,27 @@
 import { isMouseSequence, MOUSE_TRACKING, MouseClickSynthesizer, parseSgrMouseEvent, toTuiMouseEvent, } from "./mouse-input.js";
 import { isImageLine } from "./terminal-image.js";
-import { Container, dispatchMouseEvent, retargetMouseEvent, TuiBase, } from "./tui.js";
+import { Container, dispatchMouseEvent, isTerminalReport, retargetMouseEvent, TuiBase, } from "./tui.js";
 /** TUI implementation that renders into the terminal's main screen and scrollback. */
 export class TuiMainScreen extends TuiBase {
     constructor(...args) {
         super(...args);
         this.mode = "regular";
         this.trackingEnabled = false;
+        /**
+         * The app cannot scroll the terminal's scrollback, so the first wheel report while armed hands the
+         * mouse back to the terminal; the next key press arms it again (senpi#3604).
+         */
+        this.yielded = false;
         this.clicks = new MouseClickSynthesizer();
         this.addInputListener((data) => this.handleMouseInput(data));
     }
+    mouseCaptureState() {
+        if (this.yielded)
+            return "yielded";
+        return this.trackingEnabled ? "armed" : "off";
+    }
     applyMouseTracking(enabled) {
+        this.yielded = false;
         const supported = Boolean(process.stdout.isTTY) &&
             !process.env.TERMUX_VERSION &&
             (process.platform !== "win32" || Boolean(process.env.WT_SESSION));
@@ -25,6 +36,7 @@ export class TuiMainScreen extends TuiBase {
     beforeTerminalStop() {
         this.terminal.write(MOUSE_TRACKING.disable);
         this.trackingEnabled = false;
+        this.yielded = false;
         this.clicks.cancel();
         this.mousePress = undefined;
     }
@@ -83,9 +95,16 @@ export class TuiMainScreen extends TuiBase {
             this.setFocus(target);
     }
     handleMouseInput(data) {
-        if (!isMouseSequence(data))
+        if (!isMouseSequence(data)) {
+            if (this.yielded && !isTerminalReport(data))
+                this.rearmAfterYield();
             return { consume: false };
+        }
         const raw = parseSgrMouseEvent(data);
+        if (this.trackingEnabled && raw && (raw.button & 64) !== 0) {
+            this.yieldToTerminal();
+            return { consume: true };
+        }
         if (!this.trackingEnabled || !raw || raw.button !== 0) {
             this.clicks.cancel();
             this.mousePress = undefined;
@@ -146,6 +165,22 @@ export class TuiMainScreen extends TuiBase {
         }
         return { consume: true };
     }
+    yieldToTerminal() {
+        this.terminal.write(MOUSE_TRACKING.disable);
+        this.trackingEnabled = false;
+        this.yielded = true;
+        this.clicks.cancel();
+        this.mousePress = undefined;
+        this.requestRender();
+    }
+    rearmAfterYield() {
+        if (!this.mouseCaptureEnabled) {
+            this.yielded = false;
+            return;
+        }
+        this.applyMouseTracking(true);
+        this.requestRender();
+    }
     captureRenderState() {
         return {
             previousLines: [...this.previousLines],

package/dist/tui.d.ts

@@ -391,6 +391,11 @@ export declare abstract class TuiBase extends Container {
     acquireMouseCapture(reason: string): () => void;
     private resetMouseCaptureState;
     protected get mouseCaptureEnabled(): boolean;
+    /**
+     * Whether mouse reports reach the app right now: `"off"` without an enabled lease, `"armed"` while
+     * they do, `"yielded"` while a renderer has handed the mouse back to the terminal (main-screen wheel).
+     */
+    mouseCaptureState(): "off" | "armed" | "yielded";
     protected applyMouseTracking(_enabled: boolean): void;
     protected getMouseLayoutRoots(): readonly Component[];
     protected setMouseBlocker(name: "suspended" | "external-editor" | "shutting-down", on: boolean): void;
@@ -546,15 +551,15 @@ export declare abstract class TuiBase extends Container {
     private deleteChangedKittyImages;
     private getViewportRows;
     private shouldPreserveMuxScrollback;
-    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.
+     * shows them (possibly stale), and the frame is rewritten from the old viewport top down, or from where the
+     * old viewport's rows moved to when rows were inserted above it (senpi#3649), so rows already in the
+     * scrollback are not written into it again. 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;
@@ -594,6 +599,12 @@ export declare abstract class TuiBase extends Container {
         onLateReply?: (colors: TerminalColors) => void;
     }): Promise<TerminalColors>;
 }
+/**
+ * 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.
+ */
+export declare function isTerminalReport(data: string): boolean;
 /** Legacy main-screen renderer export. */
 export declare class TUI extends TuiBase {
     readonly mode: TuiMode;

package/dist/tui.js

@@ -12,6 +12,8 @@ import { parseOscColorResponse, parseTerminalColorSchemeReport, } from "./termin
 import { deleteKittyImage, getCapabilities, isImageLine, resetCapabilitiesCache, setCellDimensions, } from "./terminal-image.js";
 import { consumeTmuxFocusEvent, DISABLE_FOCUS_REPORTING, ENABLE_FOCUS_REPORTING } from "./tmux-focus.js";
 import { extractSegments, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils.js";
+import { planViewportInsertScroll } from "./viewport-insert-scroll.js";
+import { insertedAboveViewport } from "./viewport-shift.js";
 const KITTY_SEQUENCE_PREFIX = "\x1b_G";
 const MAX_RENDER_WRITE_CHARS = 1024 * 1024;
 function writeBounded(terminal, data) {
@@ -148,8 +150,6 @@ function defaultDiagnosticLogDirectory() {
  */
 let renderErrorLogDirectory;
 const VIEWPORT_RENDER_OVERSCAN = 16;
-// Keep scroll-region wins cheap when a few visible rows mutate during append streaming.
-const MAX_SCROLL_DIFF_ROWS = 4;
 const viewportRenderStats = {
     lastNormalizedLines: 0,
     lastKittyImageScannedLines: 0,
@@ -728,6 +728,13 @@ export class TuiBase extends Container {
     get mouseCaptureEnabled() {
         return this.mouseLeases.size > 0 && this.mouseBlockers.size === 0;
     }
+    /**
+     * Whether mouse reports reach the app right now: `"off"` without an enabled lease, `"armed"` while
+     * they do, `"yielded"` while a renderer has handed the mouse back to the terminal (main-screen wheel).
+     */
+    mouseCaptureState() {
+        return this.mouseCaptureEnabled ? "armed" : "off";
+    }
     applyMouseTracking(_enabled) { }
     getMouseLayoutRoots() {
         return [...this.getMountedRoots(), ...this.renderedOverlayLayouts.map((layout) => layout.entry.component)];
@@ -2097,45 +2104,6 @@ export class TuiBase extends Container {
     shouldPreserveMuxScrollback() {
         return this.#muxDetector() && !useLegacyMuxRender();
     }
-    createViewportInsertScrollPlan(newLines, prevViewportTop, height, lineCountDelta) {
-        if (lineCountDelta <= 0 || lineCountDelta >= height || this.overlayStack.length > 0) {
-            return undefined;
-        }
-        const maxViewportTop = Math.max(0, newLines.length - height);
-        const viewportTop = Math.min(maxViewportTop, prevViewportTop + lineCountDelta);
-        if (viewportTop <= prevViewportTop) {
-            return undefined;
-        }
-        const previousVisible = this.getViewportRows(this.previousLines, prevViewportTop, height);
-        const nextVisible = this.getViewportRows(newLines, viewportTop, height);
-        if (previousVisible.some(isImageLine) || nextVisible.some(isImageLine)) {
-            return undefined;
-        }
-        let stableSuffixRows = 0;
-        while (stableSuffixRows < height &&
-            previousVisible[height - stableSuffixRows - 1] === nextVisible[height - stableSuffixRows - 1]) {
-            stableSuffixRows += 1;
-        }
-        const regionHeight = height - stableSuffixRows;
-        if (regionHeight <= 0 || regionHeight < lineCountDelta) {
-            return undefined;
-        }
-        const mutatedRows = [];
-        for (let row = 0; row < regionHeight - lineCountDelta; row++) {
-            if (previousVisible[row + lineCountDelta] !== nextVisible[row]) {
-                mutatedRows.push({ screenRow: row, content: nextVisible[row] });
-                if (mutatedRows.length > MAX_SCROLL_DIFF_ROWS) {
-                    return undefined;
-                }
-            }
-        }
-        return {
-            viewportTop,
-            regionBottom: regionHeight - 1,
-            insertedRows: nextVisible.slice(regionHeight - lineCountDelta, regionHeight),
-            mutatedRows,
-        };
-    }
     renderViewportInsertScroll(plan, newLines, rawLines, cursorPos, width, height) {
         let buffer = TUI.FRAME_BEGIN;
         const regionTop = 0;
@@ -2199,13 +2167,15 @@ export class TuiBase extends Container {
     }
     /**
      * 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.
+     * shows them (possibly stale), and the frame is rewritten from the old viewport top down, or from where the
+     * old viewport's rows moved to when rows were inserted above it (senpi#3649), so rows already in the
+     * scrollback are not written into it again. 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 shift = insertedAboveViewport(this.previousLines, newLines, prevViewportTop, height, newLines.length - this.previousLines.length);
+        const start = Math.min(prevViewportTop + shift, 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);
@@ -2563,7 +2533,9 @@ export class TuiBase extends Container {
             lastChanged = expandedRange.lastChanged;
         }
         const appendStart = appendedLines && firstChanged === this.previousLines.length && firstChanged > 0;
-        const insertScrollPlan = this.createViewportInsertScrollPlan(newLines, prevViewportTop, height, lineCountDelta);
+        const insertScrollPlan = this.overlayStack.length > 0
+            ? undefined
+            : planViewportInsertScroll(this.previousLines, newLines, prevViewportTop, height, lineCountDelta);
         // No changes - but still need to update hardware cursor position if it moved
         if (firstChanged === -1) {
             this.positionHardwareCursor(cursorPos, newLines.length);
@@ -2948,7 +2920,7 @@ export class TuiBase extends Container {
  * 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) {
+export function isTerminalReport(data) {
     return (data.startsWith("\x1b[<") ||
         data.startsWith("\x1b[M") ||
         (data.length > 2 && (data.startsWith("\x1b]") || data.startsWith("\x1bP") || data.startsWith("\x1b_"))) ||

package/dist/viewport-insert-scroll.d.ts

@@ -0,0 +1,22 @@
+export interface ViewportInsertScrollPlan {
+    viewportTop: number;
+    regionBottom: number;
+    insertedRows: string[];
+    mutatedRows: Array<{
+        screenRow: number;
+        content: string;
+    }>;
+}
+/**
+ * Plan a scroll-region update for a frame that grew by `lineCountDelta` rows below a stable bottom suffix.
+ *
+ * Scrolling the region pushes the old top `lineCountDelta` visible rows into the terminal's scrollback as
+ * they are, so the plan only holds when the new frame keeps exactly those rows there. Rows inserted at or
+ * above the viewport top (a live tool card growing above a tall live area such as the /btw panel) break that:
+ * the scroll would lose the inserted rows and send stale copies of the live area into the scrollback on
+ * every frame (senpi#3649), so such a frame takes the general repaint paths instead. Identical rows can make the
+ * departing rows equal the new ones by coincidence, so a frame that reads as rows moved down from above
+ * (`shiftedBlockMoved`) is refused too.
+ */
+export declare function planViewportInsertScroll(previousLines: readonly string[], newLines: readonly string[], prevViewportTop: number, height: number, lineCountDelta: number): ViewportInsertScrollPlan | undefined;
+//# sourceMappingURL=viewport-insert-scroll.d.ts.map

package/dist/viewport-insert-scroll.js

@@ -0,0 +1,60 @@
+import { isImageLine } from "./terminal-image.js";
+import { shiftedBlockMoved } from "./viewport-shift.js";
+// Keep scroll-region wins cheap when a few visible rows mutate during append streaming.
+const MAX_SCROLL_DIFF_ROWS = 4;
+function viewportRows(lines, viewportTop, height) {
+    return Array.from({ length: height }, (_, row) => lines[viewportTop + row] ?? "");
+}
+/**
+ * Plan a scroll-region update for a frame that grew by `lineCountDelta` rows below a stable bottom suffix.
+ *
+ * Scrolling the region pushes the old top `lineCountDelta` visible rows into the terminal's scrollback as
+ * they are, so the plan only holds when the new frame keeps exactly those rows there. Rows inserted at or
+ * above the viewport top (a live tool card growing above a tall live area such as the /btw panel) break that:
+ * the scroll would lose the inserted rows and send stale copies of the live area into the scrollback on
+ * every frame (senpi#3649), so such a frame takes the general repaint paths instead. Identical rows can make the
+ * departing rows equal the new ones by coincidence, so a frame that reads as rows moved down from above
+ * (`shiftedBlockMoved`) is refused too.
+ */
+export function planViewportInsertScroll(previousLines, newLines, prevViewportTop, height, lineCountDelta) {
+    if (lineCountDelta <= 0 || lineCountDelta >= height)
+        return undefined;
+    const maxViewportTop = Math.max(0, newLines.length - height);
+    const viewportTop = Math.min(maxViewportTop, prevViewportTop + lineCountDelta);
+    if (viewportTop <= prevViewportTop)
+        return undefined;
+    const previousVisible = viewportRows(previousLines, prevViewportTop, height);
+    const nextVisible = viewportRows(newLines, viewportTop, height);
+    if (previousVisible.some(isImageLine) || nextVisible.some(isImageLine))
+        return undefined;
+    const scrolledOut = viewportTop - prevViewportTop;
+    for (let row = 0; row < scrolledOut; row++) {
+        if (previousVisible[row] !== newLines[prevViewportTop + row])
+            return undefined;
+    }
+    if (shiftedBlockMoved(previousLines, newLines, prevViewportTop, scrolledOut, height))
+        return undefined;
+    let stableSuffixRows = 0;
+    while (stableSuffixRows < height &&
+        previousVisible[height - stableSuffixRows - 1] === nextVisible[height - stableSuffixRows - 1]) {
+        stableSuffixRows += 1;
+    }
+    const regionHeight = height - stableSuffixRows;
+    if (regionHeight <= 0 || regionHeight < lineCountDelta)
+        return undefined;
+    const mutatedRows = [];
+    for (let row = 0; row < regionHeight - lineCountDelta; row++) {
+        if (previousVisible[row + lineCountDelta] !== nextVisible[row]) {
+            mutatedRows.push({ screenRow: row, content: nextVisible[row] ?? "" });
+            if (mutatedRows.length > MAX_SCROLL_DIFF_ROWS)
+                return undefined;
+        }
+    }
+    return {
+        viewportTop,
+        regionBottom: regionHeight - 1,
+        insertedRows: nextVisible.slice(regionHeight - lineCountDelta, regionHeight),
+        mutatedRows,
+    };
+}
+//# sourceMappingURL=viewport-insert-scroll.js.map

package/dist/viewport-shift.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether the new frame reads as the old one with `shift` rows inserted above `prevViewportTop`: the rows at
+ * `prevViewportTop..+shift` are the old rows right above it, and walking up through the block of rows that keeps
+ * matching that reading finds at least one row that really moved. Identical rows (blank or repeated lines) match
+ * both readings and prove nothing; the walk stops at the first row the shift does not explain.
+ */
+export declare function shiftedBlockMoved(previousLines: readonly string[], newLines: readonly string[], prevViewportTop: number, shift: number, height: number): boolean;
+/**
+ * How far the last frame's visible rows moved down in the new frame because rows were inserted above them.
+ *
+ * A held repaint writes the frame from a start row and lets the rows above the screen scroll into the
+ * terminal's scrollback. Rows that sat above the old viewport are already there, so after an insertion
+ * above the viewport (a live tool card growing over a tall /btw panel, senpi#3649) the repaint must start
+ * where the old viewport's rows went, or every frame pushes another copy of them.
+ *
+ * A shift counts only when the rows it would skip are exactly the rows already in the scrollback right above
+ * the old viewport, the contiguous block of rows above the viewport that matches the shift holds at least one
+ * row that really moved (identical rows, such as blank or repeated lines, match both readings and prove
+ * nothing), and most of the old visible rows reappear at it. A majority alone is not enough: a tall
+ * stable live area matches at any offset after an append, while rows re-laid out in place (a streamed table,
+ * #2836) are new rows that must still scroll into the scrollback, so the start stays at the old viewport top.
+ */
+export declare function insertedAboveViewport(previousLines: readonly string[], newLines: readonly string[], prevViewportTop: number, height: number, lineCountDelta: number): number;
+//# sourceMappingURL=viewport-shift.d.ts.map

package/dist/viewport-shift.js

@@ -0,0 +1,65 @@
+/**
+ * Whether the new frame reads as the old one with `shift` rows inserted above `prevViewportTop`: the rows at
+ * `prevViewportTop..+shift` are the old rows right above it, and walking up through the block of rows that keeps
+ * matching that reading finds at least one row that really moved. Identical rows (blank or repeated lines) match
+ * both readings and prove nothing; the walk stops at the first row the shift does not explain.
+ */
+export function shiftedBlockMoved(previousLines, newLines, prevViewportTop, shift, height) {
+    if (shift <= 0 || shift > prevViewportTop)
+        return false;
+    for (let row = prevViewportTop; row < prevViewportTop + shift; row++) {
+        const scrolled = previousLines[row - shift];
+        if (scrolled === undefined || scrolled !== newLines[row])
+            return false;
+    }
+    const scanFloor = Math.max(shift, prevViewportTop - 2 * height);
+    for (let row = prevViewportTop + shift - 1; row >= scanFloor; row--) {
+        const line = newLines[row];
+        if (line !== previousLines[row - shift])
+            return false;
+        if (line !== previousLines[row])
+            return true;
+    }
+    return false;
+}
+/**
+ * How far the last frame's visible rows moved down in the new frame because rows were inserted above them.
+ *
+ * A held repaint writes the frame from a start row and lets the rows above the screen scroll into the
+ * terminal's scrollback. Rows that sat above the old viewport are already there, so after an insertion
+ * above the viewport (a live tool card growing over a tall /btw panel, senpi#3649) the repaint must start
+ * where the old viewport's rows went, or every frame pushes another copy of them.
+ *
+ * A shift counts only when the rows it would skip are exactly the rows already in the scrollback right above
+ * the old viewport, the contiguous block of rows above the viewport that matches the shift holds at least one
+ * row that really moved (identical rows, such as blank or repeated lines, match both readings and prove
+ * nothing), and most of the old visible rows reappear at it. A majority alone is not enough: a tall
+ * stable live area matches at any offset after an append, while rows re-laid out in place (a streamed table,
+ * #2836) are new rows that must still scroll into the scrollback, so the start stays at the old viewport top.
+ */
+export function insertedAboveViewport(previousLines, newLines, prevViewportTop, height, lineCountDelta) {
+    if (lineCountDelta <= 0)
+        return 0;
+    const visibleMatchesAt = (shift) => {
+        let matches = 0;
+        for (let row = 0; row < height; row++) {
+            const previous = previousLines[prevViewportTop + row];
+            if (previous !== undefined && previous === newLines[prevViewportTop + shift + row])
+                matches += 1;
+        }
+        return matches;
+    };
+    let best = 0;
+    let bestMatches = visibleMatchesAt(0);
+    for (let shift = 1; shift <= Math.min(lineCountDelta, prevViewportTop); shift++) {
+        if (!shiftedBlockMoved(previousLines, newLines, prevViewportTop, shift, height))
+            continue;
+        const matches = visibleMatchesAt(shift);
+        if (matches > bestMatches) {
+            best = shift;
+            bestMatches = matches;
+        }
+    }
+    return bestMatches * 2 > height ? best : 0;
+}
+//# sourceMappingURL=viewport-shift.js.map

package/dist/wezterm-windows-images.d.ts

@@ -0,0 +1,17 @@
+/**
+ * WezTerm on Windows runs its shell through the ConPTY it bundles. Bundled
+ * ConPTY builds before 1.22 drop the Kitty graphics APC (`ESC _G ... ESC \`)
+ * before it reaches WezTerm, so an image placement leaves a blank gap. WezTerm
+ * bundled ConPTY 1.22.250204002 in wezterm/wezterm@4accc376f, whose version
+ * string is below (committer date in its own zone, see wezterm-version/build.rs);
+ * that build and later ones deliver the APC. No stable release has it yet.
+ */
+export declare const MIN_WEZTERM_WINDOWS_IMAGES_VERSION = "20250208-160106";
+export declare const WEZTERM_WINDOWS_IMAGES_HINT = "update WezTerm to a nightly build to show images inline";
+/**
+ * True only when WezTerm on Windows positively reports a build older than the
+ * first one whose bundled ConPTY passes Kitty graphics through. A missing or
+ * unparsable version keeps images on: there is no evidence of an old build.
+ */
+export declare function isOldWindowsWezTerm(version: string | undefined, platform: NodeJS.Platform): boolean;
+//# sourceMappingURL=wezterm-windows-images.d.ts.map

package/dist/wezterm-windows-images.js

@@ -0,0 +1,26 @@
+/**
+ * WezTerm on Windows runs its shell through the ConPTY it bundles. Bundled
+ * ConPTY builds before 1.22 drop the Kitty graphics APC (`ESC _G ... ESC \`)
+ * before it reaches WezTerm, so an image placement leaves a blank gap. WezTerm
+ * bundled ConPTY 1.22.250204002 in wezterm/wezterm@4accc376f, whose version
+ * string is below (committer date in its own zone, see wezterm-version/build.rs);
+ * that build and later ones deliver the APC. No stable release has it yet.
+ */
+export const MIN_WEZTERM_WINDOWS_IMAGES_VERSION = "20250208-160106";
+export const WEZTERM_WINDOWS_IMAGES_HINT = "update WezTerm to a nightly build to show images inline";
+// WezTerm sets TERM_PROGRAM_VERSION to `wezterm_version()`: YYYYMMDD-HHMMSS-<commit>.
+const WEZTERM_VERSION = /^(\d{8})-(\d{6})-[0-9a-f]+/i;
+/**
+ * True only when WezTerm on Windows positively reports a build older than the
+ * first one whose bundled ConPTY passes Kitty graphics through. A missing or
+ * unparsable version keeps images on: there is no evidence of an old build.
+ */
+export function isOldWindowsWezTerm(version, platform) {
+    if (platform !== "win32" || version === undefined)
+        return false;
+    const match = WEZTERM_VERSION.exec(version);
+    if (!match)
+        return false;
+    return `${match[1]}-${match[2]}` < MIN_WEZTERM_WINDOWS_IMAGES_VERSION;
+}
+//# sourceMappingURL=wezterm-windows-images.js.map

package/dist/wsl-session.d.ts

@@ -0,0 +1,3 @@
+/** Windows Subsystem for Linux session detection that survives sanitized environments (#3628). */
+export declare function isWslSession(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, procVersionPath?: string): boolean;
+//# sourceMappingURL=wsl-session.d.ts.map

package/dist/wsl-session.js

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+const WSL_ENV_MARKERS = ["WSL_DISTRO_NAME", "WSL_INTEROP", "WSLENV"];
+/** Windows Subsystem for Linux session detection that survives sanitized environments (#3628). */
+export function isWslSession(env, platform = process.platform, procVersionPath = "/proc/version") {
+    if (platform !== "linux") {
+        return false;
+    }
+    if (WSL_ENV_MARKERS.some((marker) => Boolean(env[marker]))) {
+        return true;
+    }
+    try {
+        return /microsoft|wsl/i.test(readFileSync(procVersionPath, "utf-8"));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=wsl-session.js.map

package/package.json

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