@code-yeongyu/senpi-tui 2026.11.3-2 → 2026.11.4-2

package/dist/index.d.ts

@@ -34,6 +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 { encodeProgramStatus, type ProgramStatus, type ProgramStatusKind, type ProgramStatusState, } from "./program-status.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";

package/dist/index.js

@@ -49,6 +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 { encodeProgramStatus, } from "./program-status.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";

package/dist/program-status.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OSC 7501 Program Status Protocol (rev 0.4): a program tells its terminal whether it is idle, working,
+ * blocked on the user, done or failed. https://control-codes.page/proposals/osc-7501/
+ */
+export type ProgramStatusState = "idle" | "working" | "blocked" | "done" | "error";
+export type ProgramStatusKind = "permission" | "question" | "auth";
+export interface ProgramStatus {
+    state: ProgramStatusState;
+    /** How the user must act; only sent with `blocked`. */
+    kind?: ProgramStatusKind;
+    /** One line on what the program is doing or waiting for. */
+    message?: string;
+}
+/**
+ * Build the OSC 7501 report for `status`, or the `state=clear` report that removes every record when it is
+ * undefined. `app` is repeated in every report because each one replaces its record; an app name outside the
+ * protocol's charset or length is left out rather than sent for the terminal to discard.
+ */
+export declare function encodeProgramStatus(status: ProgramStatus | undefined, app?: string): string;
+//# sourceMappingURL=program-status.d.ts.map

package/dist/program-status.js

@@ -0,0 +1,45 @@
+/**
+ * OSC 7501 Program Status Protocol (rev 0.4): a program tells its terminal whether it is idle, working,
+ * blocked on the user, done or failed. https://control-codes.page/proposals/osc-7501/
+ */
+const MAX_MESSAGE_BYTES = 2048;
+const APP_PATTERN = /^[A-Za-z0-9_.+-]{1,32}$/;
+// C0, DEL and C1 controls: a decoded msg holding any of them makes the terminal drop the whole report.
+const CONTROL_PATTERN = /[\u0000-\u001f\u007f-\u009f]+/g;
+// Bidi overrides/isolates and invisible formatting, which a terminal may show outside the grid.
+const INVISIBLE_FORMATTING_PATTERN = /[\u00ad\u061c\u180e\u200b\u200e\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g;
+function sanitizeMessage(message) {
+    return message.replace(INVISIBLE_FORMATTING_PATTERN, "").replace(CONTROL_PATTERN, " ").replace(/\s+/g, " ").trim();
+}
+function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return text;
+    let bytes = 0;
+    let result = "";
+    for (const char of text) {
+        bytes += Buffer.byteLength(char, "utf8");
+        if (bytes > maxBytes)
+            break;
+        result += char;
+    }
+    return result;
+}
+/**
+ * Build the OSC 7501 report for `status`, or the `state=clear` report that removes every record when it is
+ * undefined. `app` is repeated in every report because each one replaces its record; an app name outside the
+ * protocol's charset or length is left out rather than sent for the terminal to discard.
+ */
+export function encodeProgramStatus(status, app) {
+    if (status === undefined)
+        return "\x1b]7501;state=clear\x1b\\";
+    const pairs = [`state=${status.state}`];
+    if (status.state === "blocked" && status.kind !== undefined)
+        pairs.push(`kind=${status.kind}`);
+    if (app !== undefined && APP_PATTERN.test(app))
+        pairs.push(`app=${app}`);
+    const message = status.message === undefined ? "" : truncateUtf8(sanitizeMessage(status.message), MAX_MESSAGE_BYTES);
+    if (message.length > 0)
+        pairs.push(`msg=${Buffer.from(message, "utf8").toString("base64")}`);
+    return `\x1b]7501;${pairs.join(":")}\x1b\\`;
+}
+//# sourceMappingURL=program-status.js.map

package/dist/terminal.d.ts

@@ -22,6 +22,10 @@ export declare function isAppleTerminalSession(): boolean;
  */
 export declare function refreshTerminalDimensions(): void;
 export declare function normalizeNativeShiftEnterInput(data: string, shouldDetectNativeShiftEnter: boolean, isShiftPressed: boolean): string;
+/**
+ * Terminal.app can deliver Shift+Return as ESC CR, which legacy key parsing reads as Alt+Enter.
+ * The pressed native Shift keeps it apart from an Option-as-Meta Return, which stays Alt+Enter.
+ */
 export declare function normalizeAppleTerminalInput(data: string, isAppleTerminal: boolean, isShiftPressed: boolean): string;
 export declare function isWarpWslSession(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, socketExists?: (socketPath: string) => boolean): boolean;
 export declare function normalizeWarpWslShiftEnterInput(data: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, socketExists?: (socketPath: string) => boolean): string;

package/dist/terminal.js

@@ -12,6 +12,7 @@ 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";
 const NATIVE_SHIFT_ENTER_SEQUENCE = "\x1b[13;2u";
+const APPLE_TERMINAL_ESCAPED_RETURN_SEQUENCE = "\x1b\r";
 const DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS = 7;
 const DEAD_TERMINAL_ERROR_CODES = new Set(["EIO", "EPIPE", "ENOTCONN"]);
 // Bun's macOS tty shim can report synchronous ioctl EIO as raw positive errno 5 without a string code.
@@ -75,7 +76,14 @@ export function normalizeNativeShiftEnterInput(data, shouldDetectNativeShiftEnte
         return NATIVE_SHIFT_ENTER_SEQUENCE;
     return data;
 }
+/**
+ * Terminal.app can deliver Shift+Return as ESC CR, which legacy key parsing reads as Alt+Enter.
+ * The pressed native Shift keeps it apart from an Option-as-Meta Return, which stays Alt+Enter.
+ */
 export function normalizeAppleTerminalInput(data, isAppleTerminal, isShiftPressed) {
+    if (isAppleTerminal && data === APPLE_TERMINAL_ESCAPED_RETURN_SEQUENCE && isShiftPressed) {
+        return NATIVE_SHIFT_ENTER_SEQUENCE;
+    }
     return normalizeNativeShiftEnterInput(data, isAppleTerminal, isShiftPressed);
 }
 export function isWarpWslSession(env = process.env, platform = process.platform, socketExists = (socketPath) => {
@@ -328,6 +336,9 @@ export class ProcessTerminal {
             const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
             const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
             const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString(encoding);
+            if (/^\x1b]52;c;(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?\x07(?![\s\S])/.test(text)) {
+                return rawWrite(text, cb);
+            }
             if (!handler || this.forwardingExternalWrite) {
                 this.noteExternalWrite();
                 rawWrite(text);
@@ -571,8 +582,13 @@ export class ProcessTerminal {
     forwardInputSequence(sequence) {
         if (!this.inputHandler)
             return;
-        const shouldDetectNativeShiftEnter = sequence === "\r" && (isAppleTerminalSession() || process.platform === "win32");
-        const input = normalizeNativeShiftEnterInput(sequence, shouldDetectNativeShiftEnter, shouldDetectNativeShiftEnter && isNativeModifierPressed("shift"));
+        const isReturn = sequence === "\r" || sequence === APPLE_TERMINAL_ESCAPED_RETURN_SEQUENCE;
+        const isAppleTerminal = isReturn && isAppleTerminalSession();
+        const shouldDetectNativeShiftEnter = isAppleTerminal || (sequence === "\r" && process.platform === "win32");
+        const isShiftPressed = shouldDetectNativeShiftEnter && isNativeModifierPressed("shift");
+        const input = isAppleTerminal
+            ? normalizeAppleTerminalInput(sequence, true, isShiftPressed)
+            : normalizeNativeShiftEnterInput(sequence, shouldDetectNativeShiftEnter, isShiftPressed);
         this.inputHandler(input);
     }
     enableModifyOtherKeys() {

package/dist/tui.js

@@ -2774,9 +2774,12 @@ export class TuiBase extends Container {
             const isImage = isImageLine(line);
             const imageReservedRows = isImage ? this.getKittyImageReservedRows(newLines, i, renderEnd) : 1;
             if (imageReservedRows > 1) {
+                // Reserving rows at or past the viewport bottom scrolls the terminal exactly like appended text, and the
+                // relative move back up still lands on the image's first row; only an image that starts above the viewport
+                // or is taller than it cannot be placed in place (senpi#4583).
                 const imageStartScreenRow = i - viewportTop;
-                if (imageStartScreenRow < 0 || imageStartScreenRow + imageReservedRows > height) {
-                    logRedraw(`kitty image pre-clear would scroll (${imageStartScreenRow} + ${imageReservedRows} > ${height})`);
+                if (imageStartScreenRow < 0 || imageReservedRows > height) {
+                    logRedraw(`kitty image cannot be placed in place (start row ${imageStartScreenRow}, ${imageReservedRows} rows, height ${height})`);
                     fullRender(true, !preserveMuxScrollback);
                     return;
                 }

package/package.json

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