@monotykamary/localterm-server 2.38.1 → 2.39.0

package/dist/utils/serialize-viewport.d.ts

@@ -0,0 +1,3 @@
+import type { Terminal } from "@xterm/headless";
+export declare const serializeViewport: (terminal: Terminal) => string;
+//# sourceMappingURL=serialize-viewport.d.ts.map

package/dist/utils/serialize-viewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-viewport.d.ts","sourceRoot":"","sources":["../../src/utils/serialize-viewport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAwE7D,eAAO,MAAM,iBAAiB,GAAI,UAAU,QAAQ,KAAG,MAoCtD,CAAC"}

package/dist/utils/serialize-viewport.js

@@ -0,0 +1,119 @@
+// Serialize a headless terminal's visible viewport to an ANSI byte stream
+// that, when written to a viewer's xterm, reproduces the viewport cells
+// (colors, attributes, wide chars) and repositions the cursor — a faithful
+// ~rows×cols "screenshot" the client paints in one write. This is the
+// render-skip payload: when the uplink can't keep up with a megabyte TUI
+// redraw, the server sends this compact viewport snapshot instead of the
+// raw burst, so the viewer sees the latest state in one paint instead of a
+// top-to-bottom crawl.
+//
+// The output is `ESC[2J` (clear the visible screen; the scrollback above is
+// untouched) then one cursor-positioned row of cells at a time, emitting SGR
+// only when a cell's attributes change from the previous one (per-span, not
+// per-cell), then the cursor moved to its viewport position. SGR state is
+// reset before the first differing cell so the snapshot is independent of
+// whatever the viewer's terminal carried from prior output. Cursor visibility
+// and alt-screen entry are intentionally NOT set here — the viewer already
+// tracks those from the live mode-set sequences, so restating them would risk
+// desyncing from the PTY's actual mode state.
+const CSI = "\x1b[";
+const positionCursor = (row, col) => `${CSI}${row};${col}H`;
+// Build the SGR parameter list for a cell's foreground, background, and
+// attributes (bold/dim/italic/underline/blink/inverse/invisible/strikethrough/
+// overline). Palette colors 0-15 use the compact 16-color SGR (30-37 / 90-97
+// for fg, 40-47 / 100-107 for bg); 16-255 use `38;5;n` / `48;5;n`; RGB uses
+// `38;2;r;g;b` / `48;2;r;g;b`. Default fg/bg are 39 / 49.
+const buildSgrParams = (cell) => {
+    const params = [];
+    if (cell.isBold())
+        params.push("1");
+    if (cell.isDim())
+        params.push("2");
+    if (cell.isItalic())
+        params.push("3");
+    if (cell.isUnderline())
+        params.push("4");
+    if (cell.isBlink())
+        params.push("5");
+    if (cell.isInverse())
+        params.push("7");
+    if (cell.isInvisible())
+        params.push("8");
+    if (cell.isStrikethrough())
+        params.push("9");
+    if (cell.isOverline())
+        params.push("53");
+    if (cell.isFgDefault()) {
+        params.push("39");
+    }
+    else if (cell.isFgPalette()) {
+        const color = cell.getFgColor();
+        if (color < 8)
+            params.push(String(30 + color));
+        else if (color < 16)
+            params.push(String(90 + (color - 8)));
+        else
+            params.push(`38;5;${color}`);
+    }
+    else if (cell.isFgRGB()) {
+        const color = cell.getFgColor();
+        params.push(`38;2;${(color >> 16) & 0xff};${(color >> 8) & 0xff};${color & 0xff}`);
+    }
+    if (cell.isBgDefault()) {
+        params.push("49");
+    }
+    else if (cell.isBgPalette()) {
+        const color = cell.getBgColor();
+        if (color < 8)
+            params.push(String(40 + color));
+        else if (color < 16)
+            params.push(String(100 + (color - 8)));
+        else
+            params.push(`48;5;${color}`);
+    }
+    else if (cell.isBgRGB()) {
+        const color = cell.getBgColor();
+        params.push(`48;2;${(color >> 16) & 0xff};${(color >> 8) & 0xff};${color & 0xff}`);
+    }
+    return params;
+};
+// `line.getCell(x)` without a reusable cell allocates per call; for a one-shot
+// snapshot on a backpressure burst (not the hot output path) that's fine, and
+// it keeps the read loop free of cell-lifecycle plumbing.
+export const serializeViewport = (terminal) => {
+    const buffer = terminal.buffer.active;
+    const rows = terminal.rows;
+    const cols = terminal.cols;
+    const top = buffer.baseY;
+    const parts = [`${CSI}2J`, `${CSI}0m`];
+    let prev = null;
+    for (let row = 0; row < rows; row += 1) {
+        const line = buffer.getLine(top + row);
+        parts.push(positionCursor(row + 1, 1));
+        if (!line) {
+            prev = null;
+            continue;
+        }
+        for (let col = 0; col < cols; col += 1) {
+            const cell = line.getCell(col);
+            if (!cell)
+                continue;
+            if (cell.getWidth() === 0)
+                continue; // wide-char spacer — cursor already past it
+            if (prev === null || !cell.attributesEquals(prev)) {
+                const params = buildSgrParams(cell);
+                parts.push(params.length === 0 ? `${CSI}0m` : `${CSI}0;${params.join(";")}m`);
+            }
+            const chars = cell.getChars();
+            parts.push(chars.length === 0 ? " " : chars);
+            prev = cell;
+        }
+    }
+    parts.push(`${CSI}0m`);
+    // cursorY is viewport-relative (0..rows-1); cursorX is 0..cols. ANSI is 1-based.
+    const cursorRow = buffer.cursorY + 1;
+    const cursorCol = Math.min(buffer.cursorX, cols) + 1;
+    parts.push(positionCursor(cursorRow, cursorCol));
+    return parts.join("");
+};
+//# sourceMappingURL=serialize-viewport.js.map

package/dist/utils/serialize-viewport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-viewport.js","sourceRoot":"","sources":["../../src/utils/serialize-viewport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/localterm-server",
-  "version": "2.38.1",
+  "version": "2.39.0",
   "description": "PTY-backed HTTP/WebSocket server that powers localterm, built on Hono + node-pty.",
   "keywords": [
     "hono",