terminal-png 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Poe Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -14,14 +14,22 @@ await renderTerminalPng(ansiText, {
 });
 ```
 
-Options:
+## Configuration Options
 
 - `output`: path to the output PNG file
 - `window`: include terminal window chrome
-- `padding`: padding around the rendered terminal content
+- `padding`: non-negative integer padding around the rendered terminal content
+
+The ANSI parser supports common SGR styling, cursor positioning and movement, save/restore cursor,
+erase-in-line/display, tabs, double-width characters, and combining marks. Parsed terminal state is
+bounded to 1000 rows by 1000 columns to avoid unbounded renders from hostile control sequences.
 
 ## CLI
 
 ```sh
 terminal-png <input.ansi> -o <output.png> [--window] [--padding 20]
 ```
+
+## Environment Variables
+
+This package does not read public environment variables. The comparison script inherits `PATH` only to locate the local CLI under test.

package/dist/ansi-parser.js

@@ -1,4 +1,7 @@
 const ESC = "\u001b";
+const TAB_WIDTH = 8;
+const MAX_TERMINAL_ROWS = 1000;
+const MAX_TERMINAL_COLUMNS = 1000;
 function createDefaultStyle() {
     return {
         fg: null,
@@ -295,10 +298,48 @@ function positionParameter(params, index, fallback) {
     const value = toInteger(params.split(";")[index]);
     return value === null || value < 1 ? fallback : value;
 }
+function modeParameter(params, fallback) {
+    const value = toInteger(params.split(";")[0]);
+    return value === null ? fallback : value;
+}
+function displayWidth(text) {
+    if (text === "\t") {
+        return TAB_WIDTH;
+    }
+    const codePoint = text.codePointAt(0);
+    if (codePoint === undefined) {
+        return 0;
+    }
+    if ((codePoint >= 0x1100 && codePoint <= 0x115f) ||
+        codePoint === 0x2329 ||
+        codePoint === 0x232a ||
+        (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+        (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+        (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+        (codePoint >= 0x1f300 && codePoint <= 0x1f64f) ||
+        (codePoint >= 0x1f900 && codePoint <= 0x1f9ff) ||
+        (codePoint >= 0x20000 && codePoint <= 0x3fffd)) {
+        return 2;
+    }
+    return 1;
+}
+function hasRenderableCell(line) {
+    return (line ?? []).some((cell) => cell !== undefined && cell.text.length > 0);
+}
 function buildRuns(lines, lineBreakStyles) {
     const runs = [];
     const defaultStyle = createDefaultStyle();
-    for (let row = 0; row < lines.length; row += 1) {
+    let lastRow = lines.length - 1;
+    while (lastRow > 0 &&
+        !hasRenderableCell(lines[lastRow]) &&
+        lineBreakStyles[lastRow - 1] === undefined) {
+        lastRow -= 1;
+    }
+    for (let row = 0; row <= lastRow; row += 1) {
         const line = lines[row] ?? [];
         let lastCell = line.length - 1;
         while (lastCell >= 0 && line[lastCell] === undefined) {
@@ -308,7 +349,7 @@ function buildRuns(lines, lineBreakStyles) {
             const cell = line[column] ?? { text: " ", style: defaultStyle };
             pushRun(runs, cell.style, cell.text);
         }
-        if (row < lines.length - 1) {
+        if (row < lastRow) {
             pushRun(runs, lineBreakStyles[row] ?? defaultStyle, "\n");
         }
     }
@@ -320,7 +361,21 @@ export function parseAnsi(input) {
     let style = createDefaultStyle();
     let row = 0;
     let column = 0;
+    let savedRow = 0;
+    let savedColumn = 0;
     let index = 0;
+    const clampRow = (nextRow) => {
+        if (nextRow < 0) {
+            return 0;
+        }
+        return Math.min(nextRow, MAX_TERMINAL_ROWS - 1);
+    };
+    const clampColumn = (nextColumn) => {
+        if (nextColumn < 0) {
+            return 0;
+        }
+        return Math.min(nextColumn, MAX_TERMINAL_COLUMNS - 1);
+    };
     const ensureLine = () => {
         while (lines.length <= row) {
             lines.push([]);
@@ -328,12 +383,64 @@ export function parseAnsi(input) {
     };
     const moveDown = (keepColumn) => {
         lineBreakStyles[row] = cloneStyle(style);
-        row += 1;
+        row = clampRow(row + 1);
         if (!keepColumn) {
             column = 0;
         }
         ensureLine();
     };
+    const eraseLine = (mode) => {
+        const line = lines[row] ?? [];
+        if (mode === 1) {
+            for (let cell = 0; cell <= column; cell += 1) {
+                delete line[cell];
+            }
+            return;
+        }
+        if (mode === 2) {
+            lines[row] = [];
+            return;
+        }
+        line.splice(column);
+    };
+    const eraseDisplay = (mode) => {
+        if (mode === 1) {
+            for (let lineRow = 0; lineRow < row; lineRow += 1) {
+                lines[lineRow] = [];
+            }
+            eraseLine(1);
+            return;
+        }
+        if (mode === 2 || mode === 3) {
+            lines.length = 0;
+            lineBreakStyles.length = 0;
+            ensureLine();
+            return;
+        }
+        eraseLine(0);
+        lines.splice(row + 1);
+        lineBreakStyles.splice(row);
+    };
+    const saveCursor = () => {
+        savedRow = row;
+        savedColumn = column;
+    };
+    const restoreCursor = () => {
+        row = clampRow(savedRow);
+        column = clampColumn(savedColumn);
+        ensureLine();
+    };
+    const writeText = (text) => {
+        const width = displayWidth(text);
+        if (width === 0) {
+            return;
+        }
+        lines[row][column] = { text, style: cloneStyle(style) };
+        for (let offset = 1; offset < width && column + offset < MAX_TERMINAL_COLUMNS; offset += 1) {
+            lines[row][column + offset] = { text: "", style: cloneStyle(style) };
+        }
+        column = clampColumn(column + width);
+    };
     while (index < input.length) {
         const char = input[index];
         if (char === "\n") {
@@ -356,10 +463,28 @@ export function parseAnsi(input) {
             index += 1;
             continue;
         }
+        if (char === "\t") {
+            const nextTabStop = Math.min(Math.floor(column / TAB_WIDTH) * TAB_WIDTH + TAB_WIDTH, MAX_TERMINAL_COLUMNS);
+            while (column < nextTabStop) {
+                writeText(" ");
+            }
+            index += 1;
+            continue;
+        }
         if (char === ESC && input[index + 1] === "]") {
             index = parseOscEnd(input, index);
             continue;
         }
+        if (char === ESC && input[index + 1] === "7") {
+            saveCursor();
+            index += 2;
+            continue;
+        }
+        if (char === ESC && input[index + 1] === "8") {
+            restoreCursor();
+            index += 2;
+            continue;
+        }
         const csiPrefixLength = char === "\u009b" ? 1 : char === ESC && input[index + 1] === "[" ? 2 : null;
         if (csiPrefixLength !== null) {
             const sequence = parseCsi(input, index, csiPrefixLength);
@@ -367,33 +492,53 @@ export function parseAnsi(input) {
                 style = applySgr(style, sequence.params);
             }
             else if (sequence.final === "G") {
-                column = positionParameter(sequence.params, 0, 1) - 1;
+                column = clampColumn(positionParameter(sequence.params, 0, 1) - 1);
             }
             else if (sequence.final === "C") {
-                column += positionParameter(sequence.params, 0, 1);
+                column = clampColumn(column + positionParameter(sequence.params, 0, 1));
             }
             else if (sequence.final === "D") {
                 column = Math.max(0, column - positionParameter(sequence.params, 0, 1));
             }
             else if (sequence.final === "A") {
-                row = Math.max(0, row - positionParameter(sequence.params, 0, 1));
+                row = clampRow(row - positionParameter(sequence.params, 0, 1));
             }
             else if (sequence.final === "B") {
-                row += positionParameter(sequence.params, 0, 1);
+                row = clampRow(row + positionParameter(sequence.params, 0, 1));
                 ensureLine();
             }
+            else if (sequence.final === "E") {
+                row = clampRow(row + positionParameter(sequence.params, 0, 1));
+                column = 0;
+                ensureLine();
+            }
+            else if (sequence.final === "F") {
+                row = clampRow(row - positionParameter(sequence.params, 0, 1));
+                column = 0;
+            }
             else if (sequence.final === "H" || sequence.final === "f") {
-                row = positionParameter(sequence.params, 0, 1) - 1;
-                column = positionParameter(sequence.params, 1, 1) - 1;
+                row = clampRow(positionParameter(sequence.params, 0, 1) - 1);
+                column = clampColumn(positionParameter(sequence.params, 1, 1) - 1);
                 ensureLine();
             }
+            else if (sequence.final === "K") {
+                eraseLine(modeParameter(sequence.params, 0));
+            }
+            else if (sequence.final === "J") {
+                eraseDisplay(modeParameter(sequence.params, 0));
+            }
+            else if (sequence.final === "s") {
+                saveCursor();
+            }
+            else if (sequence.final === "u") {
+                restoreCursor();
+            }
             index = sequence.end;
             continue;
         }
         const codePoint = input.codePointAt(index);
         const text = codePoint === undefined ? "" : String.fromCodePoint(codePoint);
-        lines[row][column] = { text, style: cloneStyle(style) };
-        column += 1;
+        writeText(text);
         index += text.length;
     }
     return buildRuns(lines, lineBreakStyles);

package/dist/cli.js

@@ -7,11 +7,30 @@ const defaultOutput = {
     stderr: process.stderr
 };
 function parsePadding(value) {
-    const padding = Number(value);
-    if (!Number.isInteger(padding) || padding < 0) {
-        throw new InvalidArgumentError("padding must be a non-negative integer");
+    if (!isDecimalInteger(value)) {
+        throw new InvalidArgumentError("padding must be a non-negative decimal integer");
     }
-    return padding;
+    return Number.parseInt(value, 10);
+}
+function isDecimalInteger(value) {
+    if (value === "0") {
+        return true;
+    }
+    if (value.length === 0 || value[0] === "0") {
+        return false;
+    }
+    for (const char of value) {
+        if (char < "0" || char > "9") {
+            return false;
+        }
+    }
+    return true;
+}
+function parseOutputPath(value) {
+    if (value.length === 0) {
+        throw new InvalidArgumentError("output path must not be empty");
+    }
+    return value;
 }
 export async function main(args = process.argv.slice(2), output = defaultOutput) {
     const program = new Command();
@@ -19,7 +38,7 @@ export async function main(args = process.argv.slice(2), output = defaultOutput)
         .name("terminal-png")
         .description("Render a PNG image from ANSI terminal output")
         .argument("<input>", "Path to the ANSI input file")
-        .requiredOption("-o, --output <output>", "Path to the output PNG file")
+        .requiredOption("-o, --output <output>", "Path to the output PNG file", parseOutputPath)
         .option("--window", "Include terminal window chrome", true)
         .option("--no-window", "Exclude terminal window chrome")
         .option("--padding <n>", "Padding around terminal content", parsePadding)
@@ -32,7 +51,7 @@ export async function main(args = process.argv.slice(2), output = defaultOutput)
         });
     });
     program.configureOutput({
-        writeErr: value => {
+        writeErr: (value) => {
             output.stderr.write(value);
         }
     });
@@ -50,9 +69,7 @@ export async function main(args = process.argv.slice(2), output = defaultOutput)
         return 1;
     }
 }
-const entryPoint = process.argv[1]
-    ? pathToFileURL(path.resolve(process.argv[1])).href
-    : null;
+const entryPoint = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null;
 if (entryPoint === import.meta.url) {
     const exitCode = await main();
     process.exitCode = exitCode;

package/dist/error-codes.d.ts

@@ -0,0 +1 @@
+export declare function hasOwnErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException;

package/dist/error-codes.js

@@ -0,0 +1,6 @@
+export function hasOwnErrorCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        Object.prototype.hasOwnProperty.call(error, "code") &&
+        error.code === code);
+}

package/dist/index.js

@@ -1,19 +1,24 @@
 import { randomUUID } from "node:crypto";
 import { rename, rm, writeFile } from "node:fs/promises";
 import { parseAnsi } from "./ansi-parser.js";
+import { hasOwnErrorCode } from "./error-codes.js";
 import { renderPng } from "./png-renderer.js";
 import { renderSvg } from "./svg-renderer.js";
 export async function renderTerminalPng(ansiText, options = {}) {
-    if (options.padding !== undefined && (!Number.isInteger(options.padding) || options.padding < 0)) {
+    if (options.padding !== undefined &&
+        (!Number.isInteger(options.padding) || options.padding < 0)) {
         throw new Error("Padding must be a non-negative integer.");
     }
+    if (options.output !== undefined && options.output.length === 0) {
+        throw new Error("Output path must not be empty.");
+    }
     const runs = parseAnsi(ansiText);
     const svg = renderSvg(runs, {
         padding: options.padding,
         window: options.window
     });
     const png = renderPng(svg);
-    if (options.output) {
+    if (options.output !== undefined) {
         const temporaryPath = `${options.output}.${randomUUID()}.tmp`;
         let temporaryCreated = false;
         try {
@@ -36,7 +41,7 @@ export async function renderTerminalPng(ansiText, options = {}) {
     return png;
 }
 function isAlreadyExistsError(error) {
-    return error instanceof Error && "code" in error && error.code === "EEXIST";
+    return error instanceof Error && hasOwnErrorCode(error, "EEXIST");
 }
 export * from "./ansi-parser.js";
 export * from "./font.js";

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "terminal-png",
-  "version": "0.1.4",
+  "version": "0.1.6",
+  "license": "MIT",
   "description": "Render PNG images from ANSI terminal output.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +16,7 @@
     "compare": "tsx scripts/compare.ts"
   },
   "files": [
+    "LICENSE",
     "dist",
     "bin",
     "assets"
@@ -26,7 +28,7 @@
   },
   "dependencies": {
     "@resvg/resvg-js": "^2.6.2",
-    "commander": "^14.0.3",
+    "commander": "^13.1.0",
     "jetbrains-mono": "^1.0.6"
   }
 }