@code-yeongyu/senpi-tui 2026.10.2 → 2026.10.4

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { parseTerminalColorSchemeReport, type RgbColor, type TerminalColorScheme
 export declare function calculateImageRows(imageDimensions: ImageDimensions, targetWidthCells: number, cellDimensions?: CellDimensions): number;
 export { allocateImageId, buildKittyPlaceholderRow, type CellDimensions, deleteAllKittyImages, deleteKittyImage, detectCapabilities, encodeITerm2, encodeKitty, getCapabilities, getCellDimensions, getGifDimensions, getImageDimensions, getJpegDimensions, getPngDimensions, getTerminalColorMode, getWebpDimensions, hyperlink, type ImageDimensions, type ImageProtocol, type ImageRenderOptions, imageFallback, KITTY_PLACEHOLDER_MAX, outerKittyGraphicsMode, renderImage, resetCapabilitiesCache, setCapabilities, setCapabilityOverrides, setCellDimensions, type TerminalCapabilities, type TmuxPassthroughState, wrapTmuxPassthrough, } from "./terminal-image.ts";
 export { sanitizeTerminalLabel, shortenImagePath } from "./terminal-text.ts";
-export { type Component, CompositeRevision, Container, CURSOR_MARKER, claimFrameRow, compositeTuiLine, currentRenderRevision, dispatchMouseEvent, type Focusable, frameMode, frameScrollbackRows, isFocusable, isViewportTUI, joinLineArrays, mainScreenHistoryLines, nextRenderRevision, type OverlayAnchor, type OverlayBounds, type OverlayHandle, type OverlayMargin, type OverlayOptions, type OverlayUnfocusOptions, renderAtFrameRow, resetMainScreenHistoryLines, type SizeValue, TUI, type TuiInputListener, type TuiInputListenerResult, type TuiMode, type TuiMouseButton, type TuiMouseDispatchResult, type TuiMouseEvent, type TuiMouseEventResult, type TuiMouseEventType, type TuiStopOptions, type ViewportTUI, } from "./tui.ts";
+export { type Component, CompositeRevision, Container, CURSOR_MARKER, claimFrameRow, compositeTuiLine, currentRenderRevision, dispatchMouseEvent, type Focusable, type FrameLineBytesTotals, frameLineBytesTotals, frameMode, frameScrollbackRows, isFocusable, isViewportTUI, joinLineArrays, mainScreenHistoryLines, nextRenderRevision, type OverlayAnchor, type OverlayBounds, type OverlayHandle, type OverlayMargin, type OverlayOptions, type OverlayUnfocusOptions, renderAtFrameRow, resetMainScreenHistoryLines, type SizeValue, TUI, type TuiInputListener, type TuiInputListenerResult, type TuiMode, type TuiMouseButton, type TuiMouseDispatchResult, type TuiMouseEvent, type TuiMouseEventResult, type TuiMouseEventType, type TuiStopOptions, type ViewportTUI, } from "./tui.ts";
 export { TuiAltScreen, type TuiAltScreenOptions } from "./tui-alt-screen.ts";
 export { TuiMainScreen, type TuiMainScreenRenderState } from "./tui-main-screen.ts";
 export { getGraphemeSegmenter, getOsc8LinkAtColumn, getWordSegmenter, sliceByColumn, stripTerminalSequences, truncateToWidth, visibleWidth, wrapTextWithAnsi, } from "./utils.ts";

package/dist/index.js

@@ -49,7 +49,7 @@ export function calculateImageRows(imageDimensions, targetWidthCells, cellDimens
 }
 export { allocateImageId, buildKittyPlaceholderRow, deleteAllKittyImages, deleteKittyImage, detectCapabilities, encodeITerm2, encodeKitty, getCapabilities, getCellDimensions, getGifDimensions, getImageDimensions, getJpegDimensions, getPngDimensions, getTerminalColorMode, getWebpDimensions, hyperlink, imageFallback, KITTY_PLACEHOLDER_MAX, outerKittyGraphicsMode, renderImage, resetCapabilitiesCache, setCapabilities, setCapabilityOverrides, setCellDimensions, wrapTmuxPassthrough, } from "./terminal-image.js";
 export { sanitizeTerminalLabel, shortenImagePath } from "./terminal-text.js";
-export { CompositeRevision, Container, CURSOR_MARKER, claimFrameRow, compositeTuiLine, currentRenderRevision, dispatchMouseEvent, frameMode, frameScrollbackRows, isFocusable, isViewportTUI, joinLineArrays, mainScreenHistoryLines, nextRenderRevision, renderAtFrameRow, resetMainScreenHistoryLines, TUI, } from "./tui.js";
+export { CompositeRevision, Container, CURSOR_MARKER, claimFrameRow, compositeTuiLine, currentRenderRevision, dispatchMouseEvent, frameLineBytesTotals, frameMode, frameScrollbackRows, isFocusable, isViewportTUI, joinLineArrays, mainScreenHistoryLines, nextRenderRevision, renderAtFrameRow, resetMainScreenHistoryLines, TUI, } from "./tui.js";
 export { TuiAltScreen } from "./tui-alt-screen.js";
 export { TuiMainScreen } from "./tui-main-screen.js";
 // Utilities

package/dist/stdin-buffer.d.ts

@@ -28,6 +28,16 @@ export type StdinBufferOptions = {
      * (default: 10ms). Increase for high-latency Alt+key input (SSH).
      */
     escapeTimeout?: number;
+    /**
+     * Window after the previous input inside which a trailing newline is held
+     * as a possible paste fragment instead of being emitted at once
+     * (default: 20ms). Keystroke-paced input is unaffected.
+     */
+    burstWindowMs?: number;
+    /**
+     * Clock used for burst pacing (default: Date.now). Tests inject a manual clock.
+     */
+    now?: () => number;
 };
 export type StdinBufferEventMap = {
     data: [string];
@@ -48,8 +58,18 @@ export declare class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
     private pasteBuffer;
     private pendingKittyPrintableCodepoint;
     private decoder;
+    private readonly burstWindowMs;
+    private readonly clock;
+    private lastInputAt;
+    private heldNewline;
+    private heldNewlineEndsPaste;
+    private lastBurstPasteAt;
+    private burstTimer;
     constructor(options?: StdinBufferOptions);
     process(data: string | Buffer): void;
+    private consumeUnbracketedBurst;
+    private holdTrailingNewline;
+    private releaseHeldNewline;
     private emitDataSequence;
     flush(): string[];
     clear(): void;

package/dist/stdin-buffer.js

@@ -21,8 +21,16 @@ import { EventEmitter } from "events";
 const ESC = "\x1b";
 const DEFAULT_SEQUENCE_TIMEOUT_MS = 50;
 const DEFAULT_ESCAPE_TIMEOUT_MS = 10;
+const DEFAULT_BURST_WINDOW_MS = 20;
 const BRACKETED_PASTE_START = "\x1b[200~";
 const BRACKETED_PASTE_END = "\x1b[201~";
+const LINE_BREAK = /\r\n|\r|\n/g;
+const TRAILING_LINE_BREAK_RUN = /(\r\n|\r|\n)+$/;
+const LINE_BREAK_BEFORE_TEXT = /[\r\n][^\r\n]/;
+function countLineBreaks(text) {
+    const matches = text.match(LINE_BREAK);
+    return matches === null ? 0 : matches.length;
+}
 /**
  * Check if a string is a complete escape sequence or needs more data
  */
@@ -236,8 +244,13 @@ export class StdinBuffer extends EventEmitter {
         this.pasteMode = false;
         this.pasteBuffer = "";
         this.decoder = new StringDecoder("utf8");
+        this.heldNewline = "";
+        this.heldNewlineEndsPaste = false;
+        this.burstTimer = null;
         this.timeoutMs = options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT_MS;
         this.escapeTimeoutMs = options.escapeTimeout ?? DEFAULT_ESCAPE_TIMEOUT_MS;
+        this.burstWindowMs = options.burstWindowMs ?? DEFAULT_BURST_WINDOW_MS;
+        this.clock = options.now ?? Date.now;
     }
     process(data) {
         // Clear any pending timeout
@@ -280,7 +293,30 @@ export class StdinBuffer extends EventEmitter {
             }
             this.discardingMouseFragment = false;
         }
+        // Only a read that adds input takes over a held line break. A read that leaves above (an empty
+        // decode of half a multibyte character, a dropped mouse fragment) must keep its release timer running.
+        if (this.burstTimer) {
+            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 (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).
+            if (burstGap !== undefined && burstGap >= this.burstWindowMs) {
+                this.releaseHeldNewline();
+            }
+            else {
+                this.buffer = this.heldNewline + this.buffer;
+                this.heldNewline = "";
+                this.heldNewlineEndsPaste = false;
+            }
+        }
         if (this.pasteMode) {
             this.pasteBuffer += this.buffer;
             this.buffer = "";
@@ -326,6 +362,9 @@ export class StdinBuffer extends EventEmitter {
             }
             return;
         }
+        if (this.consumeUnbracketedBurst(burstGap)) {
+            return;
+        }
         const result = extractCompleteSequences(this.buffer);
         this.buffer = result.remainder;
         if (this.buffer.startsWith("\x1b[<")) {
@@ -351,6 +390,71 @@ export class StdinBuffer extends EventEmitter {
             }, timeoutMs);
         }
     }
+    consumeUnbracketedBurst(burstGap) {
+        const text = this.buffer;
+        if (text.length === 0 || text.includes(ESC) || text.includes(BRACKETED_PASTE_START)) {
+            return false;
+        }
+        const breaks = countLineBreaks(text);
+        if (breaks === 0) {
+            return false;
+        }
+        // Typing delivers one key per read, so a single read that holds two line breaks, or text after a
+        // line break, is pasted. Both carry text: a run of bare Enters stays keystrokes.
+        if ((breaks >= 2 || LINE_BREAK_BEFORE_TEXT.test(text)) && /[^\r\n]/.test(text)) {
+            this.buffer = "";
+            this.lastBurstPasteAt = this.lastInputAt;
+            this.emit("paste", text);
+            return true;
+        }
+        const trailing = text.match(TRAILING_LINE_BREAK_RUN)?.[0];
+        if (trailing === undefined || burstGap === undefined || burstGap >= this.burstWindowMs) {
+            return false;
+        }
+        const head = text.slice(0, text.length - trailing.length);
+        // A newline that lands inside the window right after a burst paste ends that paste: releasing it
+        // as Enter would submit the block, which the same text in one read never does.
+        const endsPaste = this.lastBurstPasteAt !== undefined &&
+            this.lastInputAt !== undefined &&
+            this.lastInputAt - this.lastBurstPasteAt < this.burstWindowMs;
+        // A read of bare line breaks is a keystroke unless it closes a paste, so it is forwarded at once.
+        if (head.length === 0 && !endsPaste) {
+            return false;
+        }
+        for (const chunk of head) {
+            this.emitDataSequence(chunk);
+        }
+        this.buffer = "";
+        this.holdTrailingNewline(trailing, endsPaste);
+        return true;
+    }
+    holdTrailingNewline(run, endsPaste) {
+        this.heldNewline = run;
+        this.heldNewlineEndsPaste = endsPaste;
+        if (this.burstTimer) {
+            clearTimeout(this.burstTimer);
+        }
+        this.burstTimer = setTimeout(() => {
+            this.burstTimer = null;
+            this.releaseHeldNewline();
+        }, this.burstWindowMs);
+    }
+    releaseHeldNewline() {
+        if (this.heldNewline.length === 0) {
+            return;
+        }
+        const held = this.heldNewline;
+        const endsPaste = this.heldNewlineEndsPaste;
+        this.heldNewline = "";
+        this.heldNewlineEndsPaste = false;
+        if (endsPaste) {
+            this.emit("paste", held);
+            return;
+        }
+        for (const chunk of held) {
+            this.emitDataSequence(chunk);
+        }
+    }
     emitDataSequence(sequence) {
         const rawCodepoint = sequence.length === 1 ? sequence.codePointAt(0) : undefined;
         if (rawCodepoint !== undefined && rawCodepoint === this.pendingKittyPrintableCodepoint) {
@@ -365,6 +469,11 @@ export class StdinBuffer extends EventEmitter {
             clearTimeout(this.timeout);
             this.timeout = null;
         }
+        if (this.burstTimer) {
+            clearTimeout(this.burstTimer);
+            this.burstTimer = null;
+        }
+        this.releaseHeldNewline();
         if (this.buffer.length === 0) {
             return [];
         }
@@ -390,6 +499,13 @@ export class StdinBuffer extends EventEmitter {
             clearTimeout(this.timeout);
             this.timeout = null;
         }
+        if (this.burstTimer) {
+            clearTimeout(this.burstTimer);
+            this.burstTimer = null;
+        }
+        this.heldNewline = "";
+        this.heldNewlineEndsPaste = false;
+        this.lastBurstPasteAt = undefined;
         this.buffer = "";
         this.pasteMode = false;
         this.pasteBuffer = "";

package/dist/terminal.d.ts

@@ -77,6 +77,12 @@ export interface ProcessTerminalOptions {
  * another byte, so high-latency transports need a longer reassembly window.
  */
 export declare function resolveEscapeTimeoutMs(env?: NodeJS.ProcessEnv): 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,
+ * so the default window is longer there. `PI_TUI_BURST_WINDOW_MS=0` never holds a line break.
+ */
+export declare function resolveBurstWindowMs(env?: NodeJS.ProcessEnv): number;
 /**
  * Real terminal using process.stdin/stdout
  */

package/dist/terminal.js

@@ -163,6 +163,8 @@ function unsubscribeFromStdinErrors(subscriber) {
 }
 const DEFAULT_ESCAPE_TIMEOUT_MS = 10;
 const DEFAULT_SSH_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
@@ -178,6 +180,24 @@ export function resolveEscapeTimeoutMs(env = process.env) {
     }
     return DEFAULT_ESCAPE_TIMEOUT_MS;
 }
+/**
+ * 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,
+ * so the default window is longer there. `PI_TUI_BURST_WINDOW_MS=0` never holds a line break.
+ */
+export function resolveBurstWindowMs(env = process.env) {
+    const raw = env.PI_TUI_BURST_WINDOW_MS?.trim();
+    if (raw !== undefined && raw.length > 0) {
+        const configured = Number(raw);
+        if (Number.isFinite(configured) && configured >= 0) {
+            return configured;
+        }
+    }
+    if (env.SSH_CONNECTION || env.SSH_TTY) {
+        return DEFAULT_SSH_BURST_WINDOW_MS;
+    }
+    return DEFAULT_BURST_WINDOW_MS;
+}
 /**
  * Real terminal using process.stdin/stdout
  */
@@ -392,7 +412,10 @@ export class ProcessTerminal {
      * to handle the case where the response arrives split across multiple events.
      */
     setupStdinBuffer() {
-        this.stdinBuffer = new StdinBuffer({ escapeTimeout: resolveEscapeTimeoutMs() });
+        this.stdinBuffer = new StdinBuffer({
+            escapeTimeout: resolveEscapeTimeoutMs(),
+            burstWindowMs: resolveBurstWindowMs(),
+        });
         // Forward individual sequences to the input handler
         this.stdinBuffer.on("data", (sequence) => {
             if (this.discardingPrivateResponse) {

package/dist/tui.d.ts

@@ -257,6 +257,11 @@ export declare function renderAtFrameRow(child: Component, width: number, row: n
 export declare function nextRenderRevision(): number;
 /** Current value of the render revision clock (see {@link nextRenderRevision}). */
 export declare function currentRenderRevision(): number;
+export interface FrameLineBytesTotals {
+    readonly previousLinesBytes: number;
+}
+/** Sum of every live TUI's current frame-line bytes; `0` before any frame renders. */
+export declare function frameLineBytesTotals(): FrameLineBytesTotals;
 /**
  * Render revision of a component whose output is a pure function of its own state and its children's
  * output. `bump()` records an own-state change; `read(children)` returns a revision that also changes
@@ -504,7 +509,10 @@ export declare abstract class TuiBase extends Container {
      */
     private static readonly FRAME_BEGIN;
     private static readonly FRAME_END;
+    private frameLineBytes;
     private setPreviousLines;
+    /** Releases this TUI's frame from the process total (stop/dispose resets the frame). */
+    private dropPreviousLines;
     /** Image presence of the committed frame, measured once per frame array instead of once per check. */
     protected previousLinesHaveImage(): boolean;
     /** Record image presence for a produced array; `undefined` leaves it to a scan when it is committed. */

package/dist/tui.js

@@ -385,6 +385,27 @@ export function nextRenderRevision() {
 export function currentRenderRevision() {
     return renderRevisionClock;
 }
+/**
+ * Byte cost of the frame the TUI last held, summed over every live TUI in the process (senpi#1960):
+ * `previousLines` is the whole frame a terminal keeps for the differential pass, so a long session's
+ * transcript cost lives here. The memory report reads the figure structurally through a process-global
+ * key; a process with no TUI reports no figure. Estimator: 2 bytes per UTF-16 code unit plus an 8-byte
+ * array slot per line - the same estimate the tool-card render cache uses, so the two figures compare.
+ */
+const FRAME_LINE_BYTES_KEY = Symbol.for("senpi.tui.frame-line-bytes");
+function frameLineBytesState() {
+    const existing = Reflect.get(globalThis, FRAME_LINE_BYTES_KEY);
+    if (typeof existing === "object" && existing !== null && typeof Reflect.get(existing, "bytes") === "number") {
+        return existing;
+    }
+    const created = { bytes: 0 };
+    Reflect.set(globalThis, FRAME_LINE_BYTES_KEY, created);
+    return created;
+}
+/** Sum of every live TUI's current frame-line bytes; `0` before any frame renders. */
+export function frameLineBytesTotals() {
+    return { previousLinesBytes: frameLineBytesState().bytes };
+}
 /**
  * Render revision of a component whose output is a pure function of its own state and its children's
  * output. `bump()` records an own-state change; `read(children)` returns a revision that also changes
@@ -654,6 +675,7 @@ export class TuiBase extends Container {
         this.mouseCommittedLineCount = 0;
         this.mouseAnchorPending = false;
         this.mouseExternalWritePending = false;
+        this.frameLineBytes = 0;
         this.terminal = terminal;
         // Preserve existing positional boolean callers while allowing explicit render-policy overrides.
         const normalizedOptions = typeof options === "boolean" ? { showHardwareCursor: options } : (options ?? {});
@@ -1272,8 +1294,7 @@ export class TuiBase extends Container {
         this.afterTerminalStop(options);
         this.resetRenderState();
         this.#lastCursorVisibility = undefined;
-        this.previousLines = [];
-        this.previousRawLines = [];
+        this.dropPreviousLines();
         this.previousKittyImageIds.clear();
         this.previousWidth = 0;
         this.previousHeight = 0;
@@ -1346,8 +1367,7 @@ export class TuiBase extends Container {
     /** Drop every cached frame so the next render repaints from a clean slate. */
     resetForcedRenderState() {
         this.resetRenderState();
-        this.previousLines = [];
-        this.previousRawLines = [];
+        this.dropPreviousLines();
         this.previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
         this.previousHeight = -1; // -1 triggers heightChanged, forcing a full clear
         this.cursorRow = 0;
@@ -1755,9 +1775,22 @@ export class TuiBase extends Container {
     static { this.FRAME_BEGIN = "\x1b[?2026h\x1b[?7l"; }
     static { this.FRAME_END = "\x1b[?7h\x1b[?2026l"; }
     setPreviousLines(lines, rawLines) {
+        const state = frameLineBytesState();
+        state.bytes -= this.frameLineBytes;
+        let bytes = lines.length * 8;
+        for (const line of lines)
+            bytes += line.length * 2;
+        this.frameLineBytes = bytes;
+        state.bytes += bytes;
         this.previousLines = lines;
         this.previousRawLines = rawLines;
     }
+    /** Releases this TUI's frame from the process total (stop/dispose resets the frame). */
+    dropPreviousLines() {
+        if (this.previousLines.length === 0 && this.previousRawLines.length === 0 && this.frameLineBytes === 0)
+            return;
+        this.setPreviousLines([], []);
+    }
     /** Image presence of the committed frame, measured once per frame array instead of once per check. */
     previousLinesHaveImage() {
         const lines = this.previousLines;

package/package.json

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