@archastro/tui-shot 0.2.1 → 0.2.2

package/README.md

@@ -143,3 +143,12 @@ await closeSharedBrowser();
 ```
 
 Ink fixtures support Ink 7 and React 19 as peer dependencies.
+
+## Graphics-aware PTY captures
+
+Add `graphics: kitty` to a PTY fixture to emulate a terminal that supports the
+Kitty graphics protocol. The harness answers the capability query and cell-size
+reports, records transmitted images and their placements at the cursor, strips
+the escape sequences from the text, and paints the pictures into the PNG in
+cell units. `KittyGraphicsTracker` is exported for harnesses that drive a PTY
+themselves.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { closeSharedBrowser, takeTuiShot } from "./shot.js";
 export { takePtyShot } from "./pty-shot.js";
+export { KittyGraphicsTracker, encodePng, overlaysToHtml } from "./kitty-graphics.js";
+export type { GraphicsOverlay } from "./kitty-graphics.js";
 export type { BatchEntry, BatchManifest, PtyAction, PtyKey, PtyShotFixture, PtyShotRequest, TuiShotFixture, TuiShotRequest, } from "./types.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { closeSharedBrowser, takeTuiShot } from "./shot.js";
 export { takePtyShot } from "./pty-shot.js";
+export { KittyGraphicsTracker, encodePng, overlaysToHtml } from "./kitty-graphics.js";

package/dist/kitty-graphics.d.ts

@@ -0,0 +1,45 @@
+import type { HeadlessTerminal } from "./terminal-html.js";
+export interface GraphicsOverlay {
+    col: number;
+    row: number;
+    cols: number;
+    rows: number;
+    z: number;
+    /** PNG bytes as a data URL. */
+    dataUrl: string;
+}
+export interface KittyTrackerOptions {
+    terminal: HeadlessTerminal;
+    cols: number;
+    rows: number;
+    cellWidth: number;
+    cellHeight: number;
+    /** Where terminal replies (query answers, device attributes) are sent. */
+    reply: (data: string) => void;
+}
+/** Encode raw RGB/RGBA pixels as a PNG (filter type 0 on every scanline). */
+export declare function encodePng(pixels: Buffer, width: number, height: number, channels: 3 | 4): Buffer;
+export declare class KittyGraphicsTracker {
+    private readonly options;
+    private readonly images;
+    private readonly placements;
+    private pending;
+    private carry;
+    private queryLog;
+    constructor(options: KittyTrackerOptions);
+    /** Queries the child sent, for assertions. */
+    get queries(): readonly string[];
+    get imageCount(): number;
+    /** Feed child output: text goes to the terminal, graphics are recorded. */
+    write(data: string): Promise<void>;
+    private writeText;
+    private handleCommand;
+    private storeImage;
+    private place;
+    private delete;
+    private pngFor;
+    /** Pictures currently visible, ordered for painting. */
+    overlays(): GraphicsOverlay[];
+}
+/** HTML for overlays, positioned in cell units so they track the font metrics. */
+export declare function overlaysToHtml(overlays: GraphicsOverlay[], lineHeight: number): string;

package/dist/kitty-graphics.js

@@ -0,0 +1,279 @@
+/**
+ * Kitty graphics protocol support for PTY captures.
+ *
+ * A headless xterm has no picture layer, so this tracker sits between the
+ * child's output and the terminal: it answers the capability queries a
+ * graphics-aware program sends, records every transmitted image and
+ * placement at the cursor position the terminal reports, strips the APC
+ * sequences from the text stream, and finally yields the pictures as
+ * absolutely positioned overlays for the HTML renderer.
+ */
+import fs from "node:fs";
+import zlib from "node:zlib";
+import { writeTerminal } from "./terminal-html.js";
+const APC_START = "\x1b_G";
+const ST = "\x1b\\";
+function parseKeys(text) {
+    const keys = {};
+    for (const pair of text.split(",")) {
+        const equals = pair.indexOf("=");
+        if (equals > 0)
+            keys[pair.slice(0, equals)] = pair.slice(equals + 1);
+    }
+    return keys;
+}
+function crc32(buffer) {
+    let crc = ~0;
+    for (const byte of buffer) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit += 1) {
+            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+        }
+    }
+    return ~crc >>> 0;
+}
+function pngChunk(type, data) {
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    const typed = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(typed));
+    return Buffer.concat([length, typed, crc]);
+}
+/** Encode raw RGB/RGBA pixels as a PNG (filter type 0 on every scanline). */
+export function encodePng(pixels, width, height, channels) {
+    const stride = width * channels;
+    const raw = Buffer.alloc((stride + 1) * height);
+    for (let y = 0; y < height; y += 1) {
+        raw[y * (stride + 1)] = 0;
+        pixels.copy(raw, y * (stride + 1) + 1, y * stride, y * stride + stride);
+    }
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width, 0);
+    header.writeUInt32BE(height, 4);
+    header[8] = 8;
+    header[9] = channels === 4 ? 6 : 2;
+    header[10] = 0;
+    header[11] = 0;
+    header[12] = 0;
+    return Buffer.concat([
+        Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+        pngChunk("IHDR", header),
+        pngChunk("IDAT", zlib.deflateSync(raw)),
+        pngChunk("IEND", Buffer.alloc(0)),
+    ]);
+}
+export class KittyGraphicsTracker {
+    options;
+    images = new Map();
+    placements = new Map();
+    pending = null;
+    carry = "";
+    queryLog = [];
+    constructor(options) {
+        this.options = options;
+    }
+    /** Queries the child sent, for assertions. */
+    get queries() {
+        return this.queryLog;
+    }
+    get imageCount() {
+        return this.images.size;
+    }
+    /** Feed child output: text goes to the terminal, graphics are recorded. */
+    async write(data) {
+        let buffer = this.carry + data;
+        this.carry = "";
+        while (buffer.length > 0) {
+            const start = buffer.indexOf(APC_START);
+            if (start === -1) {
+                await this.writeText(buffer);
+                return;
+            }
+            if (start > 0)
+                await this.writeText(buffer.slice(0, start));
+            const end = buffer.indexOf(ST, start + APC_START.length);
+            if (end === -1) {
+                // Wait for the rest of the sequence.
+                this.carry = buffer.slice(start);
+                return;
+            }
+            this.handleCommand(buffer.slice(start + APC_START.length, end));
+            buffer = buffer.slice(end + ST.length);
+        }
+    }
+    async writeText(text) {
+        // Answer the size reports a graphics-aware program asks for. xterm itself
+        // replies to device attributes.
+        if (text.includes("\x1b[16t")) {
+            this.options.reply(`\x1b[6;${this.options.cellHeight};${this.options.cellWidth}t`);
+        }
+        if (text.includes("\x1b[14t")) {
+            this.options.reply(`\x1b[4;${this.options.cellHeight * this.options.rows};${this.options.cellWidth * this.options.cols}t`);
+        }
+        await writeTerminal(this.options.terminal, text);
+    }
+    handleCommand(body) {
+        const separator = body.indexOf(";");
+        const keys = parseKeys(separator === -1 ? body : body.slice(0, separator));
+        const payload = separator === -1 ? "" : body.slice(separator + 1);
+        const action = keys.a ?? (this.pending ? "t" : "t");
+        if (this.pending) {
+            this.pending.payload += payload;
+            if (keys.m !== "1") {
+                const complete = this.pending;
+                this.pending = null;
+                this.storeImage(complete.keys, complete.payload);
+                if (complete.keys.a === "T")
+                    this.place(complete.keys);
+            }
+            return;
+        }
+        switch (action) {
+            case "q": {
+                this.queryLog.push(body);
+                const id = keys.i ?? "0";
+                const supported = keys.t === "d" || keys.t === "f";
+                this.options.reply(`\x1b_Gi=${id};${supported ? "OK" : "EINVAL:unsupported medium"}\x1b\\`);
+                return;
+            }
+            case "t":
+            case "T": {
+                if (keys.m === "1") {
+                    this.pending = { keys, payload };
+                    return;
+                }
+                this.storeImage(keys, payload);
+                if (action === "T")
+                    this.place(keys);
+                return;
+            }
+            case "p":
+                this.place(keys);
+                return;
+            case "d":
+                this.delete(keys);
+                return;
+            default:
+                return;
+        }
+    }
+    storeImage(keys, payload) {
+        const id = Number(keys.i ?? 0);
+        this.images.set(id, {
+            id,
+            format: Number(keys.f ?? 32),
+            width: keys.s ? Number(keys.s) : undefined,
+            height: keys.v ? Number(keys.v) : undefined,
+            compressed: keys.o === "z",
+            payload,
+            medium: keys.t ?? "d",
+        });
+        if (keys.q !== "1" && keys.q !== "2") {
+            this.options.reply(`\x1b_Gi=${id};OK\x1b\\`);
+        }
+    }
+    place(keys) {
+        const imageId = Number(keys.i ?? 0);
+        if (!this.images.has(imageId))
+            return;
+        const buffer = this.options.terminal.buffer.active;
+        const placementId = Number(keys.p ?? 0);
+        const placement = {
+            imageId,
+            placementId,
+            col: buffer.cursorX,
+            row: buffer.cursorY,
+            cols: Number(keys.c ?? 0),
+            rows: Number(keys.r ?? 0),
+            z: Number(keys.z ?? 0),
+        };
+        this.placements.set(`${imageId}:${placementId}`, placement);
+    }
+    delete(keys) {
+        const mode = keys.d ?? "a";
+        const freeData = mode === mode.toUpperCase();
+        switch (mode.toLowerCase()) {
+            case "a":
+                this.placements.clear();
+                if (freeData)
+                    this.images.clear();
+                return;
+            case "i": {
+                const imageId = Number(keys.i ?? 0);
+                const placementId = keys.p ? Number(keys.p) : null;
+                for (const [key, placement] of this.placements) {
+                    if (placement.imageId !== imageId)
+                        continue;
+                    if (placementId !== null && placement.placementId !== placementId)
+                        continue;
+                    this.placements.delete(key);
+                }
+                if (freeData && placementId === null)
+                    this.images.delete(imageId);
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    pngFor(image) {
+        if (image.png)
+            return image.png;
+        let bytes;
+        if (image.medium === "f") {
+            const filePath = Buffer.from(image.payload, "base64").toString("utf8");
+            try {
+                bytes = fs.readFileSync(filePath);
+            }
+            catch {
+                return null;
+            }
+        }
+        else {
+            bytes = Buffer.from(image.payload, "base64");
+        }
+        if (image.compressed)
+            bytes = zlib.inflateSync(bytes);
+        if (image.format === 100) {
+            image.png = bytes;
+        }
+        else if (image.width && image.height) {
+            image.png = encodePng(bytes, image.width, image.height, image.format === 24 ? 3 : 4);
+        }
+        else {
+            return null;
+        }
+        return image.png;
+    }
+    /** Pictures currently visible, ordered for painting. */
+    overlays() {
+        const result = [];
+        for (const placement of this.placements.values()) {
+            const image = this.images.get(placement.imageId);
+            if (!image)
+                continue;
+            const png = this.pngFor(image);
+            if (!png)
+                continue;
+            if (placement.cols <= 0 || placement.rows <= 0)
+                continue;
+            result.push({
+                col: placement.col,
+                row: placement.row,
+                cols: placement.cols,
+                rows: placement.rows,
+                z: placement.z,
+                dataUrl: `data:image/png;base64,${png.toString("base64")}`,
+            });
+        }
+        return result.sort((a, b) => a.z - b.z);
+    }
+}
+/** HTML for overlays, positioned in cell units so they track the font metrics. */
+export function overlaysToHtml(overlays, lineHeight) {
+    return overlays
+        .map((overlay) => `<img class="tui-graphic" src="${overlay.dataUrl}" style="left:${overlay.col}ch;` +
+        `top:${overlay.row * lineHeight}em;width:${overlay.cols}ch;height:${overlay.rows * lineHeight}em" alt="" />`)
+        .join("");
+}

package/dist/pty-shot.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
+import { KittyGraphicsTracker, overlaysToHtml } from "./kitty-graphics.js";
 import { captureTerminalHtml, queueTerminalShot, validPositive, } from "./shot.js";
 import { createHeadlessTerminal, terminalPlainText, terminalToHtml, writeTerminal, } from "./terminal-html.js";
 const KEYSTROKES = {
@@ -122,6 +123,9 @@ function loadPtyFixture(fixturePath) {
         typeof value.allowNonZeroExit !== "boolean") {
         throw fixtureError(absolute, "allowNonZeroExit must be a boolean");
     }
+    if (value.graphics !== undefined && value.graphics !== "kitty") {
+        throw fixtureError(absolute, 'graphics must be "kitty" when set');
+    }
     for (const field of ["background", "foreground", "fontFamily"]) {
         if (value[field] !== undefined && typeof value[field] !== "string") {
             throw fixtureError(absolute, `${field} must be a string`);
@@ -238,12 +242,18 @@ async function takeIsolatedPtyShot(request) {
         throw new Error(`PTY fixture cwd is not a directory: ${cwd}`);
     }
     const terminal = createHeadlessTerminal(cols, rows);
+    const graphics = fixture.graphics === "kitty";
     const childEnvironment = {
         ...process.env,
-        TERM: "xterm-256color",
+        TERM: graphics ? "xterm-kitty" : "xterm-256color",
         COLORTERM: "truecolor",
         ...fixture.env,
     };
+    // Cell metrics the emulated terminal reports; the HTML renderer positions
+    // overlays in ch/em units so the same ratios hold in the PNG.
+    const cellWidth = Math.max(1, Math.round(fontSize * 0.62));
+    const cellHeight = Math.max(1, Math.round(fontSize * lineHeight));
+    let tracker = null;
     const command = resolvePtyCommand(fixture.command, cwd, childEnvironment);
     const useExitWrapper = process.platform === "win32" ||
         process.env.ASTROSHOT_TEST_FORCE_PTY_EXIT_WRAPPER === "1";
@@ -339,12 +349,23 @@ async function takeIsolatedPtyShot(request) {
             throw new Error("PTY capture is unavailable because the optional node-pty native addon could not load on this platform. Reinstall @archastro/astroshot in a supported Node.js environment.", { cause: error });
         }
         child = spawnPty(spawnedCommand, spawnedArgs, {
-            name: "xterm-256color",
+            name: graphics ? "xterm-kitty" : "xterm-256color",
             cols,
             rows,
             cwd,
             env: childEnvironment,
         });
+        if (graphics) {
+            const spawned = child;
+            const reply = (data) => {
+                if (!exited)
+                    spawned.write(data);
+            };
+            tracker = new KittyGraphicsTracker({ terminal, cols, rows, cellWidth, cellHeight, reply });
+            // A real terminal answers device attributes and similar queries; forward
+            // xterm's replies so the program can finish its capability probe.
+            terminal.onData(reply);
+        }
         child.onData((data) => {
             if (useExitWrapper && wrappedExitCode === null) {
                 markerBuffer = (markerBuffer + data).slice(-4_096);
@@ -359,7 +380,7 @@ async function takeIsolatedPtyShot(request) {
                     }
                 }
             }
-            writes = writes.then(() => writeTerminal(terminal, data));
+            writes = writes.then(() => tracker ? tracker.write(data) : writeTerminal(terminal, data));
         });
         child.onExit((event) => {
             exited = event;
@@ -434,6 +455,7 @@ async function takeIsolatedPtyShot(request) {
         });
         return await captureTerminalHtml({
             terminalRows,
+            overlays: tracker ? overlaysToHtml(tracker.overlays(), lineHeight) : "",
             outPath: request.outPath,
             headed: request.headed,
             cols,

package/dist/shot.d.ts

@@ -6,6 +6,8 @@ export declare function validPositive(value: number, name: string, options: {
 }): number;
 export interface TerminalCaptureRequest {
     terminalRows: string;
+    /** Absolutely positioned pictures painted over the rows (kitty graphics). */
+    overlays?: string;
     outPath: string;
     headed?: boolean;
     cols: number;

package/dist/shot.js

@@ -133,15 +133,17 @@ export async function captureTerminalHtml(request) {
               line-height: ${lineHeight};
               text-rendering: geometricPrecision;
             }
+            .tui-screen { position: relative; }
             .tui-row {
               height: ${lineHeight}em;
               overflow: hidden;
               white-space: pre;
             }
+            .tui-graphic { position: absolute; display: block; object-fit: fill; }
           </style>
         </head>
         <body>
-          <div data-tui-shot role="img" aria-label="Terminal screenshot">${terminalRows}</div>
+          <div data-tui-shot role="img" aria-label="Terminal screenshot"><div class="tui-screen">${terminalRows}${request.overlays ?? ""}</div></div>
         </body>
       </html>`, { waitUntil: "load" });
         await page.locator("[data-tui-shot]").screenshot({

package/dist/types.d.ts

@@ -53,6 +53,12 @@ export interface PtyShotFixture {
     settleMs?: number;
     /** Permit a child that exits nonzero before capture. Defaults to false. */
     allowNonZeroExit?: boolean;
+    /**
+     * Emulate a graphics-capable terminal: answer the kitty graphics query and
+     * cell-size reports, record transmitted images, and paint them into the
+     * PNG at their placements.
+     */
+    graphics?: "kitty";
     actions?: PtyAction[];
     expectText?: string[];
     background?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archastro/tui-shot",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Deterministic PNG screenshots of Ink fixtures and arbitrary PTY programs",
   "keywords": [
     "ink",