tinky 1.5.0 → 1.7.0

package/README.ja-JP.md

@@ -308,6 +308,34 @@ unmount();
 clear();
 ```
 
+### incrementalRendering
+
+`incrementalRendering` を使うと、Tinky がインタラクティブフレームを更新する
+方法を選べます。run モードはターミナルセル単位で diff し、変更区間だけを書
+き込みます。line モードは行単位で diff し、変更行を再描画します。
+
+```tsx
+import { render } from "tinky";
+
+render(<App />, {
+  // 次と同じ: { strategy: "run" }
+  incrementalRendering: true,
+});
+
+render(<App />, {
+  incrementalRendering: { strategy: "line" },
+});
+
+render(<App />, {
+  incrementalRendering: { enabled: false },
+});
+```
+
+`debug`、スクリーンリーダー、CI 環境では、Tinky は自動的に非 run パスへ
+フォールバックします。戦略の比較と挙動の詳細は
+[増分レンダリングガイド](./docs/incremental-rendering.ja-JP.md) を参照して
+ください。
+
 ### measureElement(ref)
 
 レンダリングされた要素のサイズを測定します。
@@ -337,6 +365,18 @@ Tinky は Bun を使用してテストを行います。テストスイートを
 bun test
 ```
 
+増分レンダリングのローカルベンチマークを実行するには、次を実行します。
+
+```bash
+bun run perf:render
+```
+
+CI と同じ性能ゲートを実行するには、次を実行します。
+
+```bash
+bun run perf:gate
+```
+
 ## 📄 ライセンス
 
 MIT © [ByteLandTechnology](https://github.com/ByteLandTechnology)

package/README.md

@@ -308,6 +308,33 @@ unmount();
 clear();
 ```
 
+### incrementalRendering
+
+Use `incrementalRendering` to control how Tinky updates interactive frames.
+Run mode diffs terminal cells and writes minimal changed runs. Line mode diffs
+whole lines and rewrites changed lines.
+
+```tsx
+import { render } from "tinky";
+
+render(<App />, {
+  // Equivalent to: { strategy: "run" }
+  incrementalRendering: true,
+});
+
+render(<App />, {
+  incrementalRendering: { strategy: "line" },
+});
+
+render(<App />, {
+  incrementalRendering: { enabled: false },
+});
+```
+
+Tinky automatically falls back to non-run paths in `debug`, screen-reader, and
+CI environments. For strategy trade-offs and behavior details, read
+[Incremental rendering guide](./docs/incremental-rendering.md).
+
 ### measureElement(ref)
 
 Measure the dimensions of a rendered element.
@@ -337,6 +364,18 @@ Tinky uses Bun for testing. Run the test suite:
 bun test
 ```
 
+To benchmark incremental rendering locally, run:
+
+```bash
+bun run perf:render
+```
+
+To enforce the performance threshold used by CI, run:
+
+```bash
+bun run perf:gate
+```
+
 ## 📄 License
 
 MIT © [ByteLandTechnology](https://github.com/ByteLandTechnology)

package/README.zh-CN.md

@@ -308,6 +308,32 @@ unmount();
 clear();
 ```
 
+### incrementalRendering
+
+你可以通过 `incrementalRendering` 控制 Tinky 更新交互帧的方式。run 模式会按
+终端单元格做 diff，只写入变化片段；line 模式按整行做 diff，并重写变化行。
+
+```tsx
+import { render } from "tinky";
+
+render(<App />, {
+  // 等价于: { strategy: "run" }
+  incrementalRendering: true,
+});
+
+render(<App />, {
+  incrementalRendering: { strategy: "line" },
+});
+
+render(<App />, {
+  incrementalRendering: { enabled: false },
+});
+```
+
+在 `debug`、屏幕阅读器和 CI 环境中，Tinky 会自动回退到非 run 路径。关于
+策略取舍和行为细节，请参阅
+[增量渲染指南](./docs/incremental-rendering.zh-CN.md)。
+
 ### measureElement(ref)
 
 测量已渲染元素的尺寸。
@@ -337,6 +363,18 @@ Tinky 使用 Bun 进行测试。运行测试套件：
 bun test
 ```
 
+如需在本地做增量渲染性能基准测试，请运行：
+
+```bash
+bun run perf:render
+```
+
+如需执行与 CI 一致的性能门禁，请运行：
+
+```bash
+bun run perf:gate
+```
+
 ## 📄 许可证
 
 MIT © [ByteLandTechnology](https://github.com/ByteLandTechnology)

package/lib/components/Text.js

@@ -29,12 +29,19 @@ export function Text({ color, backgroundColor, dimColor = false, bold = false, i
     const { isScreenReaderEnabled } = useContext(AccessibilityContext);
     const inheritedBackgroundColor = useContext(backgroundContext);
     const childrenOrAriaLabel = isScreenReaderEnabled && ariaLabel ? ariaLabel : children;
+    const effectiveBackgroundColor = backgroundColor ?? inheritedBackgroundColor;
+    const hasTextStyle = color !== undefined ||
+        effectiveBackgroundColor !== undefined ||
+        dimColor ||
+        bold ||
+        italic ||
+        underline ||
+        strikethrough ||
+        inverse;
     if (childrenOrAriaLabel === undefined || childrenOrAriaLabel === null) {
         return null;
     }
     const transform = (children) => {
-        // Use explicit backgroundColor if provided, otherwise use inherited from parent Box
-        const effectiveBackgroundColor = backgroundColor ?? inheritedBackgroundColor;
         return applyTextStyles(children, {
             color,
             backgroundColor: effectiveBackgroundColor,
@@ -54,5 +61,5 @@ export function Text({ color, backgroundColor, dimColor = false, bold = false, i
             flexShrink: 1,
             flexDirection: "row",
             textWrap: wrap,
-        }, internal_transform: transform, children: isScreenReaderEnabled && ariaLabel ? ariaLabel : children }));
+        }, internal_transform: hasTextStyle ? transform : undefined, children: isScreenReaderEnabled && ariaLabel ? ariaLabel : children }));
 }

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

@@ -0,0 +1,91 @@
+/**
+ * Cell-buffer rendering primitives.
+ *
+ * This stores terminal cells in compact parallel arrays and keeps ANSI styles
+ * as small numeric IDs via StyleRegistry.
+ */
+import { type AnsiCode } from "../types/ansi.js";
+export interface CellBufferSize {
+    width: number;
+    height: number;
+}
+export declare class StyleRegistry {
+    private readonly keyToId;
+    private readonly idToStyles;
+    constructor();
+    static keyFor(styles: readonly AnsiCode[] | null | undefined): string;
+    getId(styles: readonly AnsiCode[] | null | undefined): number;
+    getStyles(id: number): readonly AnsiCode[];
+}
+export declare class CellBuffer {
+    width: number;
+    height: number;
+    readonly styleRegistry: StyleRegistry;
+    /**
+     * Per-cell visible glyph. Continuation cells store empty string.
+     */
+    chars: string[];
+    /**
+     * Per-cell display width: 1 or 2 on leading cells, 0 on continuation cells.
+     */
+    widths: Uint8Array;
+    /**
+     * Per-cell style id. Continuation cells keep the leading style id.
+     */
+    styleIds: Uint32Array;
+    /**
+     * Marks whether a cell was explicitly written in the current frame.
+     */
+    touched: Uint8Array;
+    /**
+     * Marks whether trailing spaces on a touched cell should be preserved.
+     */
+    preserveTrailingSpace: Uint8Array;
+    /**
+     * Marks whether a row has been touched by any write operation.
+     * Used to optimize isRowEqual/diffing.
+     */
+    rowTouched: Uint8Array;
+    constructor(size?: CellBufferSize, styleRegistry?: StyleRegistry);
+    resize(width: number, height: number): void;
+    clear(styleId?: number): void;
+    /**
+     * Converts `(x, y)` coordinates to a linear index in parallel arrays.
+     */
+    index(x: number, y: number): number;
+    setCell(x: number, y: number, ch: string, charWidth: number, styleId: number, preserveTrailing?: boolean): void;
+    fill(x: number, y: number, length: number, char: string, charWidth: number, styleId: number): void;
+    isRowEqual(other: CellBuffer, row: number): boolean;
+    isEqual(other: CellBuffer): boolean;
+    /**
+     * Computes the visible right edge for a row.
+     *
+     * This keeps transformer-produced trailing spaces when `preserveTrailingSpace`
+     * is set, while trimming untouched or default trailing cells.
+     */
+    getRowRightEdge(row: number): number;
+    /**
+     * Closes active styles and opens next styles when style id changes.
+     */
+    appendStyleTransition(out: string[], activeStyleId: number, nextStyleId: number): number;
+    /**
+     * Closes any currently active style sequence.
+     */
+    appendCloseActiveStyle(out: string[], activeStyleId: number): number;
+    /**
+     * Serializes a contiguous range of cells from one row, preserving ANSI style
+     * transitions and wide-character boundaries.
+     */
+    appendStyledRange(row: number, start: number, end: number, out: string[], activeStyleId: number, cursorX: number): {
+        cursorX: number;
+        activeStyleId: number;
+    };
+    /**
+     * Serializes one row into ANSI text, trimming only non-visible tail cells.
+     */
+    serializeRow(row: number): string;
+    /**
+     * Serializes the entire buffer into a multi-line ANSI string.
+     */
+    toString(): string;
+}

package/lib/core/cell-buffer.js

@@ -0,0 +1,346 @@
+/**
+ * Cell-buffer rendering primitives.
+ *
+ * This stores terminal cells in compact parallel arrays and keeps ANSI styles
+ * as small numeric IDs via StyleRegistry.
+ */
+export class StyleRegistry {
+    keyToId = new Map();
+    idToStyles = [];
+    constructor() {
+        // id=0 is "no style"
+        this.keyToId.set("", 0);
+        this.idToStyles[0] = [];
+    }
+    static keyFor(styles) {
+        if (!styles || styles.length === 0) {
+            return "";
+        }
+        let key = "";
+        for (const style of styles) {
+            key += style.code;
+            key += "\u0000";
+            key += style.endCode;
+            key += "\u0001";
+        }
+        return key;
+    }
+    getId(styles) {
+        const key = StyleRegistry.keyFor(styles);
+        const cached = this.keyToId.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const id = this.idToStyles.length;
+        const cloned = (styles ?? []).map((style) => ({
+            type: "ansi",
+            code: style.code,
+            endCode: style.endCode,
+        }));
+        this.keyToId.set(key, id);
+        this.idToStyles[id] = cloned;
+        return id;
+    }
+    getStyles(id) {
+        return this.idToStyles[id] ?? [];
+    }
+}
+export class CellBuffer {
+    width = 0;
+    height = 0;
+    styleRegistry;
+    /**
+     * Per-cell visible glyph. Continuation cells store empty string.
+     */
+    chars = [];
+    /**
+     * Per-cell display width: 1 or 2 on leading cells, 0 on continuation cells.
+     */
+    widths = new Uint8Array(0);
+    /**
+     * Per-cell style id. Continuation cells keep the leading style id.
+     */
+    styleIds = new Uint32Array(0);
+    /**
+     * Marks whether a cell was explicitly written in the current frame.
+     */
+    touched = new Uint8Array(0);
+    /**
+     * Marks whether trailing spaces on a touched cell should be preserved.
+     */
+    preserveTrailingSpace = new Uint8Array(0);
+    /**
+     * Marks whether a row has been touched by any write operation.
+     * Used to optimize isRowEqual/diffing.
+     */
+    rowTouched = new Uint8Array(0);
+    constructor(size = { width: 0, height: 0 }, styleRegistry) {
+        this.styleRegistry = styleRegistry ?? new StyleRegistry();
+        this.resize(size.width, size.height);
+        this.clear();
+    }
+    resize(width, height) {
+        const nextWidth = Math.max(0, Math.floor(width));
+        const nextHeight = Math.max(0, Math.floor(height));
+        if (this.width === nextWidth && this.height === nextHeight) {
+            return;
+        }
+        this.width = nextWidth;
+        this.height = nextHeight;
+        const size = nextWidth * nextHeight;
+        this.chars = new Array(size);
+        this.widths = new Uint8Array(size);
+        this.styleIds = new Uint32Array(size);
+        this.touched = new Uint8Array(size);
+        this.preserveTrailingSpace = new Uint8Array(size);
+        this.rowTouched = new Uint8Array(nextHeight);
+    }
+    clear(styleId = 0) {
+        const size = this.width * this.height;
+        this.chars.fill(" ", 0, size);
+        this.widths.fill(1, 0, size);
+        this.styleIds.fill(styleId, 0, size);
+        this.touched.fill(0, 0, size);
+        this.preserveTrailingSpace.fill(0, 0, size);
+        // Only rows with default style (0) are considered "untouched" for optimization
+        if (styleId === 0) {
+            this.rowTouched.fill(0);
+        }
+        else {
+            this.rowTouched.fill(1);
+        }
+    }
+    /**
+     * Converts `(x, y)` coordinates to a linear index in parallel arrays.
+     */
+    index(x, y) {
+        return y * this.width + x;
+    }
+    setCell(x, y, ch, charWidth, styleId, preserveTrailing = false) {
+        if (x < 0 || y < 0 || x >= this.width || y >= this.height) {
+            return;
+        }
+        const width = Math.max(1, Math.floor(charWidth));
+        if (x + width > this.width) {
+            return;
+        }
+        const cellIndex = this.index(x, y);
+        this.chars[cellIndex] = ch;
+        this.widths[cellIndex] = width;
+        this.styleIds[cellIndex] = styleId;
+        this.touched[cellIndex] = 1;
+        this.preserveTrailingSpace[cellIndex] = preserveTrailing ? 1 : 0;
+        this.rowTouched[y] = 1;
+        if (width > 1) {
+            for (let i = 1; i < width; i++) {
+                const continuationIndex = cellIndex + i;
+                this.chars[continuationIndex] = "";
+                this.widths[continuationIndex] = 0;
+                this.styleIds[continuationIndex] = styleId;
+                this.touched[continuationIndex] = 1;
+                this.preserveTrailingSpace[continuationIndex] = preserveTrailing
+                    ? 1
+                    : 0;
+            }
+        }
+    }
+    fill(x, y, length, char, charWidth, styleId) {
+        if (y < 0 || y >= this.height || length <= 0) {
+            return;
+        }
+        const startX = Math.max(0, x);
+        const endX = Math.min(this.width, x + length);
+        const fillLength = endX - startX;
+        if (fillLength <= 0) {
+            return;
+        }
+        const start = this.index(startX, y);
+        // Optimized path for single-width characters (common for background/borders)
+        if (charWidth === 1) {
+            const end = start + fillLength;
+            this.chars.fill(char, start, end);
+            this.widths.fill(1, start, end);
+            this.styleIds.fill(styleId, start, end);
+            this.touched.fill(1, start, end);
+            this.preserveTrailingSpace.fill(0, start, end);
+            this.rowTouched[y] = 1;
+            return;
+        }
+        // Fallback for multi-width characters
+        for (let i = 0; i < fillLength; i += charWidth) {
+            this.setCell(startX + i, y, char, charWidth, styleId, false);
+        }
+    }
+    isRowEqual(other, row) {
+        if (this.width !== other.width || this.height !== other.height) {
+            return false;
+        }
+        if (row < 0 || row >= this.height) {
+            return false;
+        }
+        // Optimization: if both rows are untouched (empty/default), they are equal
+        if (!this.rowTouched[row] && !other.rowTouched[row]) {
+            return true;
+        }
+        const thisRightEdge = this.getRowRightEdge(row);
+        const otherRightEdge = other.getRowRightEdge(row);
+        if (thisRightEdge !== otherRightEdge) {
+            return false;
+        }
+        if (thisRightEdge === 0) {
+            return true;
+        }
+        const start = row * this.width;
+        const end = start + thisRightEdge;
+        for (let index = start; index < end; index++) {
+            if (this.styleIds[index] !== other.styleIds[index]) {
+                return false;
+            }
+            if (this.widths[index] !== other.widths[index]) {
+                return false;
+            }
+            if (this.chars[index] !== other.chars[index]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    isEqual(other) {
+        if (this.width !== other.width || this.height !== other.height) {
+            return false;
+        }
+        for (let row = 0; row < this.height; row++) {
+            if (!this.isRowEqual(other, row)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Computes the visible right edge for a row.
+     *
+     * This keeps transformer-produced trailing spaces when `preserveTrailingSpace`
+     * is set, while trimming untouched or default trailing cells.
+     */
+    getRowRightEdge(row) {
+        const width = this.width;
+        if (row < 0 || row >= this.height) {
+            return 0;
+        }
+        if (!this.rowTouched[row]) {
+            return 0;
+        }
+        const offset = row * width;
+        for (let x = width - 1; x >= 0; x--) {
+            const index = offset + x;
+            if (this.widths[index] === 0) {
+                continue;
+            }
+            if (this.touched[index] === 0) {
+                continue;
+            }
+            const canTrimUnstyledSpace = this.chars[index] === " " &&
+                this.styleIds[index] === 0 &&
+                this.preserveTrailingSpace[index] === 0;
+            if (canTrimUnstyledSpace) {
+                continue;
+            }
+            const cellWidth = this.widths[index] || 1;
+            return Math.min(width, x + cellWidth);
+        }
+        return 0;
+    }
+    /**
+     * Closes active styles and opens next styles when style id changes.
+     */
+    appendStyleTransition(out, activeStyleId, nextStyleId) {
+        if (activeStyleId === nextStyleId) {
+            return activeStyleId;
+        }
+        const activeStyles = this.styleRegistry.getStyles(activeStyleId);
+        for (let i = activeStyles.length - 1; i >= 0; i--) {
+            out.push(activeStyles[i]?.endCode);
+        }
+        const nextStyles = this.styleRegistry.getStyles(nextStyleId);
+        for (const style of nextStyles) {
+            out.push(style.code);
+        }
+        return nextStyleId;
+    }
+    /**
+     * Closes any currently active style sequence.
+     */
+    appendCloseActiveStyle(out, activeStyleId) {
+        if (activeStyleId === 0) {
+            return 0;
+        }
+        const activeStyles = this.styleRegistry.getStyles(activeStyleId);
+        for (let i = activeStyles.length - 1; i >= 0; i--) {
+            out.push(activeStyles[i]?.endCode);
+        }
+        return 0;
+    }
+    /**
+     * Serializes a contiguous range of cells from one row, preserving ANSI style
+     * transitions and wide-character boundaries.
+     */
+    appendStyledRange(row, start, end, out, activeStyleId, cursorX) {
+        const width = this.width;
+        if (row < 0 || row >= this.height) {
+            return { cursorX, activeStyleId };
+        }
+        const safeStart = Math.max(0, Math.min(width, start));
+        const safeEnd = Math.max(0, Math.min(width, end));
+        if (safeEnd <= safeStart) {
+            return { cursorX, activeStyleId };
+        }
+        const rowOffset = row * width;
+        let x = safeStart;
+        while (x < safeEnd) {
+            const index = rowOffset + x;
+            const cellWidth = this.widths[index];
+            if (cellWidth === 0) {
+                x++;
+                continue;
+            }
+            const styleId = this.styleIds[index];
+            activeStyleId = this.appendStyleTransition(out, activeStyleId, styleId);
+            out.push(this.chars[index] ?? " ");
+            const advance = cellWidth || 1;
+            cursorX += advance;
+            x += advance;
+        }
+        return { cursorX, activeStyleId };
+    }
+    /**
+     * Serializes one row into ANSI text, trimming only non-visible tail cells.
+     */
+    serializeRow(row) {
+        const rightEdge = this.getRowRightEdge(row);
+        if (rightEdge === 0) {
+            return "";
+        }
+        const out = [];
+        const { activeStyleId } = this.appendStyledRange(row, 0, rightEdge, out, 0, 0);
+        this.appendCloseActiveStyle(out, activeStyleId);
+        return out.join("");
+    }
+    /**
+     * Serializes the entire buffer into a multi-line ANSI string.
+     */
+    toString() {
+        const out = [];
+        for (let row = 0; row < this.height; row++) {
+            if (row > 0) {
+                out.push("\n");
+            }
+            const rightEdge = this.getRowRightEdge(row);
+            if (rightEdge === 0) {
+                continue;
+            }
+            const { activeStyleId } = this.appendStyledRange(row, 0, rightEdge, out, 0, 0);
+            this.appendCloseActiveStyle(out, activeStyleId);
+        }
+        return out.join("");
+    }
+}

package/lib/core/cell-log-update-run.d.ts

@@ -0,0 +1,40 @@
+import { type WriteStream } from "../types/io.js";
+import { type CellBuffer } from "./cell-buffer.js";
+/**
+ * Run-diff renderer for interactive terminal output.
+ *
+ * Compared with line-diff mode, this renderer diffs cell buffers and emits
+ * minimal cursor movement + text writes for changed runs. It entirely skips
+ * terminal writes when consecutive frames are identical.
+ */
+export interface CellLogUpdateRunOptions {
+    /** Enables diff updates. Set `false` to force full-frame redraws. */
+    incremental?: boolean;
+    /** Keeps the terminal cursor visible during updates. */
+    showCursor?: boolean;
+    /** Gap merge threshold used by `mergeStrategy: "threshold"`. */
+    mergeThreshold?: number;
+    /** Segment merge policy. `cost` chooses cheapest bytes, `threshold` uses gap. */
+    mergeStrategy?: "cost" | "threshold";
+    /** Fallback to full-row writes when too many segments are present. */
+    maxSegmentsBeforeFullRow?: number;
+    /** Penalty when overwriting unchanged gaps in `cost` mode. */
+    overwriteGapPenaltyBytes?: number;
+}
+export interface RenderOptions {
+    /** Forces full redraw for the current frame. */
+    forceFull?: boolean;
+}
+export type CellLogUpdateRender = ((prevBuffer: CellBuffer, nextBuffer: CellBuffer, options?: RenderOptions) => void) & {
+    /** Erases currently rendered interactive frame. */
+    clear: () => void;
+    /** Resets internal frame state without writing to stream. */
+    reset: () => void;
+    /** Synchronizes internal state after an external full redraw. */
+    sync: (buffer: CellBuffer) => void;
+    /** Finalizes renderer and restores cursor visibility. */
+    done: () => void;
+};
+export declare const cellLogUpdateRun: {
+    create: (stream: WriteStream, options?: CellLogUpdateRunOptions) => CellLogUpdateRender;
+};