tinky 1.5.0 → 1.7.0

package/lib/core/cell-output.js

@@ -0,0 +1,231 @@
+/**
+ * Output implementation that writes directly into CellBuffer.
+ */
+import sliceAnsi from "slice-ansi";
+import stringWidth from "string-width";
+import widestLine from "widest-line";
+import { styledCharsFromTokens, tokenize } from "@alcalzone/ansi-tokenize";
+const ESC = "\u001b";
+const isPrintableAsciiText = (value) => {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code === 10) {
+            continue;
+        }
+        if (code < 0x20 || code > 0x7e) {
+            return false;
+        }
+    }
+    return true;
+};
+const getCharWidth = (value, widthCache) => {
+    if (value.length === 1 &&
+        value.charCodeAt(0) >= 0x20 &&
+        value.charCodeAt(0) <= 0x7e) {
+        return 1;
+    }
+    const cached = widthCache.get(value);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const width = Math.max(1, stringWidth(value));
+    widthCache.set(value, width);
+    return width;
+};
+export class CellOutput {
+    clips = [];
+    styleIdByRef = new WeakMap();
+    lastStyleRef;
+    lastStyleId = 0;
+    buffer;
+    constructor(buffer) {
+        this.buffer = buffer;
+    }
+    clip(clip) {
+        this.clips.push(clip);
+    }
+    unclip() {
+        this.clips.pop();
+    }
+    fill(x, y, length, char, charWidth, styles) {
+        if (length <= 0) {
+            return;
+        }
+        const visualLength = length * charWidth;
+        let startX = x;
+        let endX = x + visualLength;
+        const row = y;
+        const clip = this.clips.at(-1);
+        if (clip) {
+            const clipY1 = clip.y1 ?? 0;
+            // Clipping logic: y2 is exclusive boundary
+            if (clip.y2 !== undefined && row >= clip.y2) {
+                return;
+            }
+            if (row < clipY1) {
+                return;
+            }
+            const clipX1 = clip.x1 ?? 0;
+            startX = Math.max(startX, clipX1);
+            if (clip.x2 !== undefined) {
+                endX = Math.min(endX, clip.x2);
+            }
+        }
+        const fillVisualLength = endX - startX;
+        if (fillVisualLength <= 0) {
+            return;
+        }
+        const styleId = this.buffer.styleRegistry.getId(styles);
+        this.buffer.fill(startX, row, fillVisualLength, char, charWidth, styleId);
+    }
+    resolveStyleId(styles) {
+        if (styles.length === 0) {
+            return 0;
+        }
+        if (styles === this.lastStyleRef) {
+            return this.lastStyleId;
+        }
+        const byRef = this.styleIdByRef.get(styles);
+        if (byRef !== undefined) {
+            this.lastStyleRef = styles;
+            this.lastStyleId = byRef;
+            return byRef;
+        }
+        const styleId = this.buffer.styleRegistry.getId(styles);
+        this.styleIdByRef.set(styles, styleId);
+        this.lastStyleRef = styles;
+        this.lastStyleId = styleId;
+        return styleId;
+    }
+    writePlainLine(line, writeX, row, preserveLineTrailingSpaces, widthCache) {
+        let offsetX = writeX;
+        for (const value of line) {
+            const charWidth = getCharWidth(value, widthCache);
+            if (offsetX < 0) {
+                offsetX += charWidth;
+                continue;
+            }
+            if (offsetX >= this.buffer.width) {
+                break;
+            }
+            if (offsetX + charWidth > this.buffer.width) {
+                break;
+            }
+            this.buffer.setCell(offsetX, row, value, charWidth, 0, preserveLineTrailingSpaces);
+            offsetX += charWidth;
+        }
+    }
+    write(x, y, text, options) {
+        const { transformers } = options;
+        if (!text) {
+            return;
+        }
+        let writeX = x;
+        let writeY = y;
+        let lines = text.split("\n");
+        // Match Output.get() semantics: transformed lines may intentionally keep
+        // trailing spaces (for alignment or visual effects), so mark them.
+        const preserveLineTrailingSpaces = transformers.length > 0;
+        const widthCache = new Map();
+        const clip = this.clips.at(-1);
+        if (!clip &&
+            transformers.length === 0 &&
+            !text.includes(ESC) &&
+            isPrintableAsciiText(text)) {
+            let offsetY = 0;
+            for (const line of lines) {
+                const row = writeY + offsetY;
+                if (row < 0) {
+                    offsetY++;
+                    continue;
+                }
+                if (row >= this.buffer.height) {
+                    break;
+                }
+                this.writePlainLine(line, writeX, row, preserveLineTrailingSpaces, widthCache);
+                offsetY++;
+            }
+            return;
+        }
+        if (clip) {
+            const clipHorizontally = typeof clip.x1 === "number" && typeof clip.x2 === "number";
+            const clipVertically = typeof clip.y1 === "number" && typeof clip.y2 === "number";
+            const clipX1 = clip.x1 ?? 0;
+            const clipX2 = clip.x2 ?? 0;
+            const clipY1 = clip.y1 ?? 0;
+            const clipY2 = clip.y2 ?? 0;
+            if (clipHorizontally) {
+                const width = widestLine(text);
+                if (writeX + width < clipX1 || writeX > clipX2) {
+                    return;
+                }
+            }
+            if (clipVertically) {
+                const height = lines.length;
+                if (writeY + height < clipY1 || writeY > clipY2) {
+                    return;
+                }
+            }
+            if (clipHorizontally) {
+                lines = lines.map((line) => {
+                    const from = writeX < clipX1 ? clipX1 - writeX : 0;
+                    const width = stringWidth(line);
+                    const to = writeX + width > clipX2 ? clipX2 - writeX : width;
+                    return sliceAnsi(line, from, to);
+                });
+                if (writeX < clipX1) {
+                    writeX = clipX1;
+                }
+            }
+            if (clipVertically) {
+                const from = writeY < clipY1 ? clipY1 - writeY : 0;
+                const height = lines.length;
+                const to = writeY + height > clipY2 ? clipY2 - writeY : height;
+                lines = lines.slice(from, to);
+                if (writeY < clipY1) {
+                    writeY = clipY1;
+                }
+            }
+        }
+        let offsetY = 0;
+        for (const [lineIndex, line] of lines.entries()) {
+            const row = writeY + offsetY;
+            if (row < 0) {
+                offsetY++;
+                continue;
+            }
+            if (row >= this.buffer.height) {
+                break;
+            }
+            let transformedLine = line;
+            for (const transformer of transformers) {
+                transformedLine = transformer(transformedLine, lineIndex);
+            }
+            if (!transformedLine.includes(ESC) &&
+                isPrintableAsciiText(transformedLine)) {
+                this.writePlainLine(transformedLine, writeX, row, preserveLineTrailingSpaces, widthCache);
+                offsetY++;
+                continue;
+            }
+            const styledChars = styledCharsFromTokens(tokenize(transformedLine));
+            let offsetX = writeX;
+            for (const char of styledChars) {
+                const charWidth = getCharWidth(char.value, widthCache);
+                if (offsetX < 0) {
+                    offsetX += charWidth;
+                    continue;
+                }
+                if (offsetX >= this.buffer.width) {
+                    break;
+                }
+                if (offsetX + charWidth > this.buffer.width) {
+                    break;
+                }
+                const styleId = this.resolveStyleId(char.styles);
+                this.buffer.setCell(offsetX, row, char.value, charWidth, styleId, preserveLineTrailingSpaces);
+                offsetX += charWidth;
+            }
+            offsetY++;
+        }
+    }
+}

package/lib/core/cell-renderer.d.ts

@@ -0,0 +1,25 @@
+import { type DOMElement } from "./dom.js";
+import { type CellBuffer } from "./cell-buffer.js";
+interface CellRendererResult {
+    /** Interactive frame rendered into `buffer`. */
+    buffer: CellBuffer;
+    /** Height (rows) of the interactive frame. */
+    outputHeight: number;
+    /** Newly appended `<Static>` output, with trailing newline when present. */
+    staticOutput: string;
+    /** Screen-reader text when screen-reader mode is enabled. */
+    screenReaderOutput?: string;
+}
+/**
+ * Renderer that writes interactive output into a CellBuffer.
+ *
+ * Static output is still rendered as string output because it is emitted once
+ * and not updated incrementally.
+ *
+ * @param node - Root DOM node to render.
+ * @param buffer - Reusable destination buffer for the interactive frame.
+ * @param isScreenReaderEnabled - Enables screen-reader rendering path.
+ * @returns The rendered interactive frame and any static output emitted this pass.
+ */
+export declare const cellRenderer: (node: DOMElement, buffer: CellBuffer, isScreenReaderEnabled: boolean) => CellRendererResult;
+export {};

package/lib/core/cell-renderer.js

@@ -0,0 +1,60 @@
+import { renderNodeToOutput, renderNodeToScreenReaderOutput, } from "./render-node-to-output.js";
+import { Output } from "./output.js";
+import { CellOutput } from "./cell-output.js";
+/**
+ * Renderer that writes interactive output into a CellBuffer.
+ *
+ * Static output is still rendered as string output because it is emitted once
+ * and not updated incrementally.
+ *
+ * @param node - Root DOM node to render.
+ * @param buffer - Reusable destination buffer for the interactive frame.
+ * @param isScreenReaderEnabled - Enables screen-reader rendering path.
+ * @returns The rendered interactive frame and any static output emitted this pass.
+ */
+export const cellRenderer = (node, buffer, isScreenReaderEnabled) => {
+    if (!node.taffyNode) {
+        buffer.resize(0, 0);
+        buffer.clear();
+        return { buffer, outputHeight: 0, staticOutput: "" };
+    }
+    if (isScreenReaderEnabled) {
+        const output = renderNodeToScreenReaderOutput(node, {
+            skipStaticElements: true,
+        });
+        const outputHeight = output === "" ? 0 : output.split("\n").length;
+        let staticOutput = "";
+        if (node.staticNode) {
+            staticOutput = renderNodeToScreenReaderOutput(node.staticNode, {
+                skipStaticElements: false,
+            });
+        }
+        return {
+            buffer,
+            outputHeight,
+            staticOutput: staticOutput ? `${staticOutput}\n` : "",
+            screenReaderOutput: output,
+        };
+    }
+    const layout = node.taffyNode.tree.getLayout(node.taffyNode.id);
+    buffer.resize(layout.width, layout.height);
+    buffer.clear();
+    const output = new CellOutput(buffer);
+    renderNodeToOutput(node, output, { skipStaticElements: true });
+    let staticOutput;
+    if (node.staticNode?.taffyNode) {
+        const staticLayout = node.staticNode.taffyNode.tree.getLayout(node.staticNode.taffyNode.id);
+        staticOutput = new Output({
+            width: staticLayout.width,
+            height: staticLayout.height,
+        });
+        renderNodeToOutput(node.staticNode, staticOutput, {
+            skipStaticElements: false,
+        });
+    }
+    return {
+        buffer,
+        outputHeight: buffer.height,
+        staticOutput: staticOutput ? `${staticOutput.get().output}\n` : "",
+    };
+};

package/lib/core/incremental-rendering.d.ts

@@ -0,0 +1,43 @@
+/**
+ * User-facing configuration for incremental rendering.
+ *
+ * You can use this object form when you need to choose a strategy explicitly
+ * or disable incremental rendering without changing existing option shapes.
+ */
+export interface IncrementalRenderingConfig {
+    /**
+     * Master on/off switch for object mode.
+     *
+     * - `false`: disables incremental rendering, regardless of `strategy`.
+     * - `true` or omitted: enables incremental rendering and uses `strategy`.
+     */
+    enabled?: boolean;
+    /**
+     * Diff strategy used for interactive output updates.
+     *
+     * - `"line"`: compares line strings and redraws changed lines.
+     * - `"run"`: compares terminal cells and rewrites minimal changed runs.
+     *
+     * @defaultValue "run"
+     */
+    strategy?: "line" | "run";
+}
+/**
+ * Public option accepted by `render(..., { incrementalRendering })`.
+ */
+export type IncrementalRenderingOption = boolean | IncrementalRenderingConfig;
+/**
+ * Internal normalized strategy used inside the renderer.
+ */
+export type IncrementalRenderStrategy = "none" | "line" | "run";
+/**
+ * Normalizes user-facing incremental rendering options to an internal strategy.
+ *
+ * Resolution order:
+ * - `undefined` or `false` -> `"none"`
+ * - `true` -> `"run"`
+ * - `{ enabled: false }` -> `"none"`
+ * - `{ strategy: "line" }` -> `"line"`
+ * - `{ strategy: "run" }` or omitted strategy -> `"run"`
+ */
+export declare const normalizeIncrementalRendering: (value: IncrementalRenderingOption | undefined) => IncrementalRenderStrategy;

package/lib/core/incremental-rendering.js

@@ -0,0 +1,22 @@
+/**
+ * Normalizes user-facing incremental rendering options to an internal strategy.
+ *
+ * Resolution order:
+ * - `undefined` or `false` -> `"none"`
+ * - `true` -> `"run"`
+ * - `{ enabled: false }` -> `"none"`
+ * - `{ strategy: "line" }` -> `"line"`
+ * - `{ strategy: "run" }` or omitted strategy -> `"run"`
+ */
+export const normalizeIncrementalRendering = (value) => {
+    if (value === undefined || value === false) {
+        return "none";
+    }
+    if (value === true) {
+        return "run";
+    }
+    if (value.enabled === false) {
+        return "none";
+    }
+    return value.strategy ?? "run";
+};

package/lib/core/output.d.ts

@@ -1,9 +1,17 @@
 import { type OutputTransformer } from "./render-node-to-output.js";
 import { type Dimension } from "../utils/dimension.js";
+import { type AnsiCode } from "../types/ansi.js";
+/**
+ * Options for writing text to an output target.
+ */
+export interface OutputWriteOptions {
+    /** Array of transformers to apply to each rendered line. */
+    transformers: OutputTransformer[];
+}
 /**
  * Represents a clipping rectangle.
  */
-interface Clip {
+export interface Clip {
     /** Left boundary (undefined for no limit). */
     x1: number | undefined;
     /** Right boundary (undefined for no limit). */
@@ -13,6 +21,15 @@ interface Clip {
     /** Bottom boundary (undefined for no limit). */
     y2: number | undefined;
 }
+/**
+ * Shared write/clip/unclip surface used by render traversal.
+ */
+export interface OutputLike {
+    write(x: number, y: number, text: string, options: OutputWriteOptions): void;
+    clip(clip: Clip): void;
+    unclip(): void;
+    fill(x: number, y: number, length: number, char: string, charWidth: number, styles: AnsiCode[]): void;
+}
 /**
  * "Virtual" output class
  *
@@ -21,7 +38,7 @@ interface Clip {
  *
  * Used to generate the final output of all nodes before writing to stdout.
  */
-export declare class Output {
+export declare class Output implements OutputLike {
     width: number;
     height: number;
     private readonly operations;
@@ -39,9 +56,7 @@ export declare class Output {
      * @param text - The text to write.
      * @param options - Options containing transformers.
      */
-    write(x: number, y: number, text: string, options: {
-        transformers: OutputTransformer[];
-    }): void;
+    write(x: number, y: number, text: string, options: OutputWriteOptions): void;
     /**
      * Sets a clipping area for subsequent operations.
      *
@@ -52,6 +67,7 @@ export declare class Output {
      * Removes the last clipping area, restoring the previous one.
      */
     unclip(): void;
+    fill(x: number, y: number, length: number, char: string, _charWidth: number, styles: AnsiCode[]): void;
     /**
      * Generates the final output string and its height.
      *
@@ -62,4 +78,3 @@ export declare class Output {
         height: number;
     };
 }
-export {};

package/lib/core/output.js

@@ -33,7 +33,6 @@ export class Output {
      * @param options - Options containing transformers.
      */
     write(x, y, text, options) {
-        const { transformers } = options;
         if (!text) {
             return;
         }
@@ -42,7 +41,7 @@ export class Output {
             x,
             y,
             text,
-            transformers,
+            options,
         });
     }
     /**
@@ -64,6 +63,18 @@ export class Output {
             type: "unclip",
         });
     }
+    fill(x, y, length, char, _charWidth, styles) {
+        if (length <= 0) {
+            return;
+        }
+        const prefix = styles.map((style) => style.code).join("");
+        const suffix = [...styles]
+            .reverse()
+            .map((style) => style.endCode)
+            .join("");
+        const text = prefix + char.repeat(length) + suffix;
+        this.write(x, y, text, { transformers: [] });
+    }
     /**
      * Generates the final output string and its height.
      *
@@ -73,6 +84,10 @@ export class Output {
         // Initialize output array with a specific set of rows, so that
         // margin/padding at the bottom is preserved
         const output = [];
+        // Tracks whether a cell was explicitly written this frame.
+        const touched = [];
+        // Preserves intentional trailing spaces produced by transformers.
+        const preserveTrailingSpace = [];
         for (let y = 0; y < this.height; y++) {
             const row = [];
             for (let x = 0; x < this.width; x++) {
@@ -83,7 +98,11 @@ export class Output {
                     styles: [],
                 });
             }
+            const rowTouched = new Array(this.width).fill(false);
+            const rowPreserve = new Array(this.width).fill(false);
             output.push(row);
+            touched.push(rowTouched);
+            preserveTrailingSpace.push(rowPreserve);
         }
         const clips = [];
         for (const operation of this.operations) {
@@ -94,9 +113,11 @@ export class Output {
                 clips.pop();
             }
             if (operation.type === "write") {
-                const { text, transformers } = operation;
+                const { text } = operation;
+                const { transformers } = operation.options;
                 let { x, y } = operation;
                 let lines = text.split("\n");
+                const preserveLineTrailingSpaces = transformers.length > 0;
                 const clip = clips.at(-1);
                 if (clip) {
                     const clipHorizontally = typeof clip.x1 === "number" && typeof clip.x2 === "number";
@@ -142,10 +163,13 @@ export class Output {
                 }
                 let offsetY = 0;
                 for (const [index, line] of lines.entries()) {
-                    const currentLine = output[y + offsetY];
+                    const rowIndex = y + offsetY;
+                    const currentLine = output[rowIndex];
+                    const touchedRow = touched[rowIndex];
+                    const preserveRow = preserveTrailingSpace[rowIndex];
                     // Line can be missing if `text` is taller than height of
                     // pre-initialized `this.output`
-                    if (!currentLine) {
+                    if (!currentLine || !touchedRow || !preserveRow) {
                         continue;
                     }
                     let transformedLine = line;
@@ -156,6 +180,8 @@ export class Output {
                     let offsetX = x;
                     for (const character of characters) {
                         currentLine[offsetX] = character;
+                        touchedRow[offsetX] = true;
+                        preserveRow[offsetX] = preserveLineTrailingSpaces;
                         // Determine printed width using string-width to align with measurement
                         const characterWidth = Math.max(1, stringWidth(character.value));
                         // For multi-column characters, clear following cells to avoid stray
@@ -168,6 +194,8 @@ export class Output {
                                     fullWidth: false,
                                     styles: character.styles,
                                 };
+                                touchedRow[offsetX + index] = true;
+                                preserveRow[offsetX + index] = preserveLineTrailingSpaces;
                             }
                         }
                         offsetX += characterWidth;
@@ -177,9 +205,46 @@ export class Output {
             }
         }
         const generatedOutput = output
-            .map((line) => {
-            const lineWithoutEmptyItems = line.filter((item) => item !== undefined);
-            return styledCharsToString(lineWithoutEmptyItems).trimEnd();
+            .map((line, rowIndex) => {
+            const rowTouched = touched[rowIndex] ?? [];
+            const rowPreserve = preserveTrailingSpace[rowIndex] ?? [];
+            const compactLine = [];
+            const compactTouched = [];
+            const compactPreserve = [];
+            for (let index = 0; index < line.length; index++) {
+                const item = line[index];
+                if (item === undefined) {
+                    continue;
+                }
+                compactLine.push(item);
+                compactTouched.push(rowTouched[index] === true);
+                compactPreserve.push(rowPreserve[index] === true);
+            }
+            let end = compactLine.length - 1;
+            while (end >= 0) {
+                const item = compactLine[end];
+                if (!item) {
+                    end--;
+                    continue;
+                }
+                if (!compactTouched[end]) {
+                    end--;
+                    continue;
+                }
+                const canTrimUnstyledSpace = item.type === "char" &&
+                    item.value === " " &&
+                    item.styles.length === 0 &&
+                    !compactPreserve[end];
+                if (canTrimUnstyledSpace) {
+                    end--;
+                    continue;
+                }
+                break;
+            }
+            if (end < 0) {
+                return "";
+            }
+            return styledCharsToString(compactLine.slice(0, end + 1));
         })
             .join("\n");
         return {

package/lib/core/render-border.d.ts

@@ -1,13 +1,3 @@
 import { type DOMNode } from "./dom.js";
-import { type Output } from "./output.js";
-/**
- * Renders the border for a DOM node.
- * Calculates border dimensions and draws border characters with specified
- * styles.
- *
- * @param x - The x-coordinate (column) where the border starts.
- * @param y - The y-coordinate (row) where the border starts.
- * @param node - The DOM node for which to render the border.
- * @param output - The output instance to write the border to.
- */
-export declare const renderBorder: (x: number, y: number, node: DOMNode, output: Output) => void;
+import { type OutputLike } from "./output.js";
+export declare const renderBorder: (x: number, y: number, node: DOMNode, output: OutputLike) => void;