@nuvin/ink 7.5.0-alpha → 7.7.0-alpha

package/build/log-update.js

@@ -1,6 +1,9 @@
+import process from 'node:process';
 import ansiEscapes from 'ansi-escapes';
 import cliCursor from 'cli-cursor';
 import { cursorPositionChanged, getOutputCursorRow, buildCursorSuffix, buildCursorOnlySequence, buildReturnToBottomPrefix, hideCursorEscape, showCursorEscape, } from './cursor-helpers.js';
+import { createSeekPreparer } from './allocated-seek.js';
+import { isSeekViewport, clampSeekCursor, buildSeekCursorSequence, encodeSeekRows, wrapSeekPaint, decawmOn, eraseDisplayHome, } from './terminal-paint.js';
 // Count visible lines in a string, ignoring the trailing empty element
 // that `split('\n')` produces when the string ends with '\n'.
 const visibleLineCount = (lines, str) => str.endsWith('\n') ? lines.length - 1 : lines.length;
@@ -10,7 +13,103 @@ const getEraseLineCount = (cachedLineCount, options) => {
     }
     return options?.eraseLineCount ?? cachedLineCount;
 };
-const createStandard = (stream, { showCursor = false } = {}) => {
+// Maximum shift distance (rows) considered by scroll-region detection. Real
+// wheel/keyboard scrolls move a handful of rows per commit; larger jumps
+// (PageUp/PageDown) rarely share half the frame and fall through to the
+// ordinary diff anyway.
+const maxScrollShift = 32;
+// Minimum fraction of the frame that must be explained by a pure vertical
+// shift for the scroll-region fast path to engage. Updates that merely resemble
+// a shift (streaming appends, selection highlights, spinner ticks) stay below
+// the threshold and use the ordinary diff.
+const minShiftedCoreRatio = 0.5;
+const setScrollRegion = (start, end) => `\u001B[${start + 1};${end}r`;
+const resetScrollRegion = '\u001B[r';
+const cursorToRow = (row) => `\u001B[${row + 1};1H`;
+const blankLines = (count) => Array.from({ length: count }, () => '');
+const prefixUnchanged = (previousLines, nextLines, start) => {
+    for (let index = 0; index < start; index++) {
+        if (nextLines[index] !== previousLines[index]) {
+            return false;
+        }
+    }
+    return true;
+};
+const suffixUnchanged = (previousLines, nextLines, end) => {
+    for (let index = end; index < nextLines.length; index++) {
+        if (nextLines[index] !== previousLines[index])
+            return false;
+    }
+    return true;
+};
+// Detect whether `nextLines` is `previousLines` shifted vertically by k rows
+// with at most a small band of changed edge lines. Only exact whole-line
+// equality counts (same semantics as the existing positional diff).
+const detectScrollShift = (previousLines, nextLines) => {
+    const height = nextLines.length;
+    if (height < 4 || height !== previousLines.length) {
+        return undefined;
+    }
+    const required = Math.ceil(height * minShiftedCoreRatio);
+    for (let rows = 1; rows <= Math.min(maxScrollShift, height - 1); rows++) {
+        // Content moved up: nextLines[i] === previousLines[i + rows] over the
+        // overlap [0, height - rows); the bottom `rows` lines are new.
+        let up = 0;
+        let upFirst = -1;
+        let upLast = -1;
+        for (let i = 0; i < height - rows; i++) {
+            if (nextLines[i] !== previousLines[i + rows]) {
+                continue;
+            }
+            up++;
+            if (nextLines[i] === previousLines[i]) {
+                continue;
+            }
+            upFirst = upFirst < 0 ? i : upFirst;
+            upLast = i;
+        }
+        const upEnd = upLast + rows + 1;
+        if (up >= required &&
+            upFirst >= 0 &&
+            upLast - upFirst + 1 >= required &&
+            upEnd <= height &&
+            upEnd - upFirst > rows &&
+            prefixUnchanged(previousLines, nextLines, upFirst) &&
+            suffixUnchanged(previousLines, nextLines, upEnd)) {
+            return { rows, start: upFirst, end: upEnd };
+        }
+        // Content moved down: nextLines[i] === previousLines[i - rows]; the top
+        // `rows` lines of the shifted band are new.
+        let down = 0;
+        let downFirst = -1;
+        let downLast = -1;
+        for (let i = rows; i < height; i++) {
+            if (nextLines[i] !== previousLines[i - rows]) {
+                continue;
+            }
+            down++;
+            if (nextLines[i] === previousLines[i]) {
+                continue;
+            }
+            downFirst = downFirst < 0 ? i : downFirst;
+            downLast = i;
+        }
+        const downStart = downFirst - rows;
+        const downEnd = downLast + 1;
+        if (down >= required &&
+            downFirst >= 0 &&
+            downLast - downFirst + 1 >= required &&
+            downStart >= 0 &&
+            downEnd <= height &&
+            downEnd - downStart > rows &&
+            prefixUnchanged(previousLines, nextLines, downStart) &&
+            suffixUnchanged(previousLines, nextLines, downEnd)) {
+            return { rows: -rows, start: downStart, end: downEnd };
+        }
+    }
+    return undefined;
+};
+const createStandard = (stream, { showCursor = false, transformOutput } = {}) => {
     let previousLineCount = 0;
     let previousOutput = '';
     let hasHiddenCursor = false;
@@ -54,7 +153,7 @@ const createStandard = (stream, { showCursor = false } = {}) => {
             const returnPrefix = buildReturnToBottomPrefix(cursorWasShown, previousLineCount, previousCursorPosition);
             stream.write(returnPrefix +
                 ansiEscapes.eraseLines(getEraseLineCount(previousLineCount, options)) +
-                str +
+                (transformOutput ? transformOutput(str) : str) +
                 cursorSuffix);
             previousLineCount = lines.length;
         }
@@ -62,8 +161,8 @@ const createStandard = (stream, { showCursor = false } = {}) => {
         cursorWasShown = activeCursor !== undefined;
         return true;
     };
-    const render = (str) => writeFrame(str, false);
-    render.repaint = (str, options) => writeFrame(str, true, options);
+    const render = (str, _context) => writeFrame(str, false);
+    render.repaint = (str, options, _context) => writeFrame(str, true, options);
     render.clear = (options) => {
         const prefix = buildReturnToBottomPrefix(cursorWasShown, previousLineCount, previousCursorPosition);
         stream.write(prefix +
@@ -98,7 +197,7 @@ const createStandard = (stream, { showCursor = false } = {}) => {
         cursorWasShown = false;
         cursorDirty = false;
     };
-    render.sync = (str) => {
+    render.sync = (str, _physical) => {
         const activeCursor = cursorPosition;
         cursorDirty = false;
         const lines = str.split('\n');
@@ -118,10 +217,14 @@ const createStandard = (stream, { showCursor = false } = {}) => {
         cursorDirty = true;
     };
     render.isCursorDirty = () => cursorDirty;
-    render.willRender = (str) => hasChanges(str, getActiveCursor());
+    render.willRender = (str, _context) => hasChanges(str, getActiveCursor());
+    render.getPhysicalFrame = () => undefined;
+    render.restoreTerminalModes = () => {
+        // Standard rendering never acquires seek terminal modes.
+    };
     return render;
 };
-const createIncremental = (stream, { showCursor = false } = {}) => {
+const createIncremental = (stream, { showCursor = false, transformOutput } = {}) => {
     let previousLines = [];
     let previousOutput = '';
     let hasHiddenCursor = false;
@@ -129,12 +232,221 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
     let cursorDirty = false;
     let previousCursorPosition;
     let cursorWasShown = false;
+    let physicalFrame;
+    let previousIdentities = [];
+    let ownsDecawm = false;
+    let writeGeneration = 0;
+    let paintedSeekViewport = false;
+    const seekPreparer = createSeekPreparer();
+    let streamErrorHandler;
+    let handlingAsyncWriteError = false;
     const getActiveCursor = () => cursorPosition;
     const hasChanges = (str, activeCursor) => {
         const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
         return str !== previousOutput || cursorChanged;
     };
-    const render = (str) => {
+    const bumpGeneration = () => {
+        writeGeneration++;
+    };
+    const invalidatePhysical = () => {
+        if (physicalFrame === undefined) {
+            return;
+        }
+        physicalFrame = {
+            ...physicalFrame,
+            valid: false,
+            ownsViewport: false,
+        };
+    };
+    const canWriteStream = () => {
+        const candidate = stream;
+        return (!candidate.destroyed &&
+            !candidate.writableEnded &&
+            (candidate.writable ?? true));
+    };
+    const restoreTerminalModes = () => {
+        if (!ownsDecawm) {
+            return;
+        }
+        if (canWriteStream()) {
+            try {
+                stream.write(decawmOn);
+            }
+            catch {
+                // Best-effort autowrap restore.
+            }
+        }
+        ownsDecawm = false;
+    };
+    const handleAsyncWriteError = () => {
+        if (handlingAsyncWriteError) {
+            return;
+        }
+        handlingAsyncWriteError = true;
+        bumpGeneration();
+        invalidatePhysical();
+        previousIdentities = [];
+        previousOutput = '';
+        previousLines = [];
+        // A queued successful write can establish the next ordered diff base,
+        // but an async error invalidates it; it is not proof that a terminal
+        // displayed the frame.
+        if (paintedSeekViewport) {
+            ownsDecawm = true;
+        }
+        restoreTerminalModes();
+    };
+    const detachStreamErrorListener = () => {
+        if (!streamErrorHandler) {
+            return;
+        }
+        stream.off('error', streamErrorHandler);
+        streamErrorHandler = undefined;
+    };
+    const attachStreamErrorListener = () => {
+        if (streamErrorHandler) {
+            return;
+        }
+        streamErrorHandler = () => {
+            handleAsyncWriteError();
+        };
+        stream.on('error', streamErrorHandler);
+    };
+    const copyContext = (context) => ({
+        strategy: context.strategy,
+        columns: context.columns,
+        rows: context.rows,
+    });
+    const seekHasChanges = (str, context, activeCursor) => {
+        if (physicalFrame === undefined ||
+            !physicalFrame.valid ||
+            physicalFrame.context.strategy !== context.strategy ||
+            physicalFrame.context.columns !== context.columns ||
+            physicalFrame.context.rows !== context.rows ||
+            str !== previousOutput) {
+            return true;
+        }
+        return cursorPositionChanged(activeCursor, previousCursorPosition);
+    };
+    const submitSeekWrite = (payload, { decawm, onAccept, }) => {
+        const generation = ++writeGeneration;
+        handlingAsyncWriteError = false;
+        if (decawm) {
+            ownsDecawm = true;
+            // Seek cells may already be on the stream; keep teardown ownership
+            // through throw/reentry. Physical/diff still publish only on accept.
+            paintedSeekViewport = true;
+        }
+        attachStreamErrorListener();
+        try {
+            stream.write(payload, error => {
+                if (error) {
+                    handleAsyncWriteError();
+                }
+            });
+            if (decawm) {
+                ownsDecawm = false;
+            }
+            // A queued successful write can establish the next ordered diff base,
+            // but an async error invalidates it; it is not proof that a terminal
+            // displayed the frame.
+            if (generation === writeGeneration) {
+                onAccept();
+            }
+            return true;
+        }
+        catch (error) {
+            invalidatePhysical();
+            previousIdentities = [];
+            previousOutput = '';
+            previousLines = [];
+            if (decawm) {
+                ownsDecawm = true;
+            }
+            restoreTerminalModes();
+            throw error;
+        }
+    };
+    const writeSeekFrame = (str, context, force) => {
+        const activeCursor = getActiveCursor();
+        cursorDirty = false;
+        if (!force && !seekHasChanges(str, context, activeCursor)) {
+            return false;
+        }
+        const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+        const dimensionsChanged = physicalFrame === undefined ||
+            !physicalFrame.valid ||
+            physicalFrame.context.columns !== context.columns ||
+            physicalFrame.context.rows !== context.rows ||
+            physicalFrame.context.strategy !== context.strategy;
+        if (!force &&
+            !dimensionsChanged &&
+            str === previousOutput &&
+            cursorChanged) {
+            const payload = buildSeekCursorSequence(activeCursor, context.columns, context.rows, cursorWasShown);
+            return submitSeekWrite(payload, {
+                decawm: false,
+                onAccept() {
+                    previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+                    cursorWasShown = activeCursor !== undefined;
+                    if (physicalFrame?.valid) {
+                        physicalFrame = {
+                            ...physicalFrame,
+                            cursor: clampSeekCursor(activeCursor, context.columns, context.rows),
+                        };
+                    }
+                },
+            });
+        }
+        const prepared = seekPreparer.prepareFrame(str, context.columns);
+        const viewportCount = Math.min(prepared.length, context.rows);
+        const viewportPrepared = prepared.slice(0, viewportCount);
+        const paintAll = force || dimensionsChanged;
+        const indexes = [];
+        if (paintAll) {
+            for (let index = 0; index < viewportCount; index++) {
+                indexes.push(index);
+            }
+        }
+        else {
+            for (let index = 0; index < viewportCount; index++) {
+                if (viewportPrepared[index].identity !== previousIdentities[index]) {
+                    indexes.push(index);
+                }
+            }
+        }
+        const encodedRows = encodeSeekRows(viewportPrepared, indexes, context.columns);
+        const cursorSuffix = buildSeekCursorSequence(activeCursor, context.columns, context.rows, cursorWasShown);
+        const payload = encodedRows.length > 0
+            ? wrapSeekPaint(encodedRows + cursorSuffix)
+            : cursorSuffix;
+        if (payload.length === 0) {
+            return false;
+        }
+        return submitSeekWrite(payload, {
+            decawm: encodedRows.length > 0,
+            onAccept() {
+                previousOutput = str;
+                previousLines = str.split('\n');
+                previousIdentities = viewportPrepared.map(row => row.identity);
+                previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+                cursorWasShown = activeCursor !== undefined;
+                paintedSeekViewport = true;
+                physicalFrame = {
+                    context: copyContext(context),
+                    ownsViewport: true,
+                    valid: true,
+                    logicalRows: viewportPrepared.map(row => row.logical),
+                    allocatedWidths: viewportPrepared.map(row => row.allocatedWidth),
+                    cursor: clampSeekCursor(activeCursor, context.columns, context.rows),
+                };
+            },
+        });
+    };
+    const render = (str, context) => {
+        if (isSeekViewport(context)) {
+            return writeSeekFrame(str, context, false);
+        }
         if (!showCursor && !hasHiddenCursor) {
             cliCursor.hide(stream);
             hasHiddenCursor = true;
@@ -169,7 +481,7 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
             const cursorSuffix = buildCursorSuffix(outputCursorRow, activeCursor);
             stream.write(returnPrefix +
                 ansiEscapes.eraseLines(previousLines.length) +
-                str +
+                (transformOutput ? transformOutput(str) : str) +
                 cursorSuffix);
             cursorWasShown = activeCursor !== undefined;
             previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
@@ -181,8 +493,33 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
         // We aggregate all chunks for incremental rendering into a buffer, and then write them to stdout at the end.
         const buffer = [];
         buffer.push(returnPrefix);
-        // Clear extra lines if the current content's line count is lower than the previous.
-        if (visibleCount < previousVisible) {
+        const prevVisible = previousLines.slice(0, previousVisible);
+        const nextVisible = nextLines.slice(0, visibleCount);
+        const shift = process.env['NUVIN_INK_NO_SCROLL_OPT'] === '1' ||
+            activeCursor !== undefined ||
+            hasTrailingNewline ||
+            previousOutput.endsWith('\n') ||
+            visibleCount !== previousVisible
+            ? undefined
+            : detectScrollShift(prevVisible, nextVisible);
+        let diffPrevious = previousLines;
+        let loopStart = 0;
+        if (shift) {
+            const k = Math.abs(shift.rows);
+            const { start, end } = shift;
+            const prefix = prevVisible.slice(0, start);
+            const band = prevVisible.slice(start, end);
+            const suffix = prevVisible.slice(end);
+            const shiftedBand = shift.rows > 0
+                ? [...band.slice(k), ...blankLines(k)]
+                : [...blankLines(k), ...band.slice(0, band.length - k)];
+            const shiftedPrevious = [...prefix, ...shiftedBand, ...suffix];
+            buffer.push(setScrollRegion(start, end), cursorToRow(start), shift.rows > 0 ? `\u001B[${k}M` : `\u001B[${k}L`, resetScrollRegion, cursorToRow(start));
+            diffPrevious = shiftedPrevious;
+            loopStart = start;
+        }
+        else if (visibleCount < previousVisible) {
+            // Clear extra lines if the current content's line count is lower than the previous.
             const previousHadTrailingNewline = previousOutput.endsWith('\n');
             const extraSlot = previousHadTrailingNewline ? 1 : 0;
             buffer.push(ansiEscapes.eraseLines(previousVisible - visibleCount + extraSlot), ansiEscapes.cursorUp(visibleCount));
@@ -190,10 +527,10 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
         else {
             buffer.push(ansiEscapes.cursorUp(previousLines.length - 1));
         }
-        for (let i = 0; i < visibleCount; i++) {
+        for (let i = loopStart; i < visibleCount; i++) {
             const isLastLine = i === visibleCount - 1;
             // We do not write lines if the contents are the same. This prevents flickering during renders.
-            if (nextLines[i] === previousLines[i]) {
+            if (nextLines[i] === diffPrevious[i]) {
                 // Don't move past the last line when there's no trailing newline,
                 // otherwise the cursor overshoots the rendered block.
                 if (!isLastLine || hasTrailingNewline) {
@@ -202,7 +539,7 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
                 continue;
             }
             buffer.push(ansiEscapes.cursorTo(0) +
-                nextLines[i] +
+                (transformOutput ? transformOutput(nextLines[i]) : nextLines[i]) +
                 ansiEscapes.eraseEndLine +
                 // Don't append newline after the last line when the input
                 // has no trailing newline (fullscreen mode).
@@ -217,7 +554,10 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
         previousLines = nextLines;
         return true;
     };
-    render.repaint = (str, options) => {
+    render.repaint = (str, options, context) => {
+        if (isSeekViewport(context)) {
+            return writeSeekFrame(str, context, true);
+        }
         if (!showCursor && !hasHiddenCursor) {
             cliCursor.hide(stream);
             hasHiddenCursor = true;
@@ -230,7 +570,7 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
         const cursorSuffix = buildCursorSuffix(outputCursorRow, activeCursor);
         stream.write(returnPrefix +
             ansiEscapes.eraseLines(getEraseLineCount(previousLines.length, options)) +
-            str +
+            (transformOutput ? transformOutput(str) : str) +
             cursorSuffix);
         previousOutput = str;
         previousLines = nextLines;
@@ -238,46 +578,101 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
         cursorWasShown = activeCursor !== undefined;
         return true;
     };
-    render.clear = (options) => {
-        const prefix = buildReturnToBottomPrefix(cursorWasShown, previousLines.length, previousCursorPosition);
-        stream.write(prefix +
-            ansiEscapes.eraseLines(getEraseLineCount(previousLines.length, options)));
+    const clearSeekState = () => {
         previousOutput = '';
         previousLines = [];
+        previousIdentities = [];
         previousCursorPosition = undefined;
         cursorWasShown = false;
         cursorDirty = false;
+        paintedSeekViewport = false;
+        invalidatePhysical();
+    };
+    render.clear = (options) => {
+        bumpGeneration();
+        restoreTerminalModes();
+        if (paintedSeekViewport) {
+            stream.write(eraseDisplayHome);
+            clearSeekState();
+            return;
+        }
+        const prefix = buildReturnToBottomPrefix(cursorWasShown, previousLines.length, previousCursorPosition);
+        stream.write(prefix +
+            ansiEscapes.eraseLines(getEraseLineCount(previousLines.length, options)));
+        clearSeekState();
     };
     render.done = () => {
-        const returnPrefix = buildReturnToBottomPrefix(cursorWasShown, previousLines.length, previousCursorPosition);
-        if (returnPrefix || showCursor) {
-            stream.write(returnPrefix + (showCursor ? showCursorEscape : ''));
+        bumpGeneration();
+        restoreTerminalModes();
+        detachStreamErrorListener();
+        try {
+            if (paintedSeekViewport) {
+                if (showCursor) {
+                    stream.write(showCursorEscape);
+                }
+                clearSeekState();
+                cursorPosition = undefined;
+                if (!showCursor) {
+                    cliCursor.show(stream);
+                    hasHiddenCursor = false;
+                }
+                return;
+            }
+            const returnPrefix = buildReturnToBottomPrefix(cursorWasShown, previousLines.length, previousCursorPosition);
+            if (returnPrefix || showCursor) {
+                stream.write(returnPrefix + (showCursor ? showCursorEscape : ''));
+            }
+            clearSeekState();
+            cursorPosition = undefined;
+            if (!showCursor) {
+                cliCursor.show(stream);
+                hasHiddenCursor = false;
+            }
         }
-        previousOutput = '';
-        previousLines = [];
-        previousCursorPosition = undefined;
-        cursorWasShown = false;
-        cursorPosition = undefined;
-        cursorDirty = false;
-        if (!showCursor) {
-            cliCursor.show(stream);
-            hasHiddenCursor = false;
+        catch {
+            clearSeekState();
+            cursorPosition = undefined;
         }
     };
     render.reset = () => {
         // Cache-only: the caller must have externally reset or replaced terminal contents.
+        bumpGeneration();
         previousOutput = '';
         previousLines = [];
+        previousIdentities = [];
         previousCursorPosition = undefined;
         cursorWasShown = false;
         cursorDirty = false;
+        invalidatePhysical();
     };
-    render.sync = (str) => {
+    render.sync = (str, physical) => {
         const activeCursor = cursorPosition;
         cursorDirty = false;
         const lines = str.split('\n');
         previousOutput = str;
         previousLines = lines;
+        const matching = physical?.valid === true &&
+            physical.ownsViewport &&
+            physical.context.strategy === 'seek-viewport' &&
+            physical.logicalRows.join('\n') === str;
+        if (matching && physical) {
+            physicalFrame = {
+                context: copyContext(physical.context),
+                ownsViewport: true,
+                valid: true,
+                logicalRows: physical.logicalRows,
+                allocatedWidths: physical.allocatedWidths,
+                cursor: physical.cursor,
+            };
+            previousIdentities = [];
+            paintedSeekViewport = true;
+            previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+            cursorWasShown = activeCursor !== undefined;
+            return;
+        }
+        previousIdentities = [];
+        paintedSeekViewport = false;
+        invalidatePhysical();
         if (!activeCursor && cursorWasShown) {
             stream.write(hideCursorEscape);
         }
@@ -292,14 +687,21 @@ const createIncremental = (stream, { showCursor = false } = {}) => {
         cursorDirty = true;
     };
     render.isCursorDirty = () => cursorDirty;
-    render.willRender = (str) => hasChanges(str, getActiveCursor());
+    render.willRender = (str, context) => {
+        if (isSeekViewport(context)) {
+            return seekHasChanges(str, context, getActiveCursor());
+        }
+        return hasChanges(str, getActiveCursor());
+    };
+    render.getPhysicalFrame = () => physicalFrame;
+    render.restoreTerminalModes = restoreTerminalModes;
     return render;
 };
-const create = (stream, { showCursor = false, incremental = false } = {}) => {
+const create = (stream, { showCursor = false, incremental = false, transformOutput, } = {}) => {
     if (incremental) {
-        return createIncremental(stream, { showCursor });
+        return createIncremental(stream, { showCursor, transformOutput });
     }
-    return createStandard(stream, { showCursor });
+    return createStandard(stream, { showCursor, transformOutput });
 };
 const logUpdate = { create };
 export default logUpdate;