ink 6.5.1 → 6.7.0

package/build/log-update.js

@@ -1,108 +1,234 @@
 import ansiEscapes from 'ansi-escapes';
 import cliCursor from 'cli-cursor';
+import { cursorPositionChanged, buildCursorSuffix, buildCursorOnlySequence, buildReturnToBottomPrefix, hideCursorEscape, } from './cursor-helpers.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;
 const createStandard = (stream, { showCursor = false } = {}) => {
     let previousLineCount = 0;
     let previousOutput = '';
     let hasHiddenCursor = false;
+    let cursorPosition;
+    let cursorDirty = false;
+    let previousCursorPosition;
+    let cursorWasShown = false;
+    const getActiveCursor = () => (cursorDirty ? cursorPosition : undefined);
+    const hasChanges = (str, activeCursor) => {
+        const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+        return str !== previousOutput || cursorChanged;
+    };
     const render = (str) => {
         if (!showCursor && !hasHiddenCursor) {
-            cliCursor.hide();
+            cliCursor.hide(stream);
             hasHiddenCursor = true;
         }
-        const output = str + '\n';
-        if (output === previousOutput) {
-            return;
+        // Only use cursor if setCursorPosition was called since last render.
+        // This ensures stale positions don't persist after component unmount.
+        const activeCursor = getActiveCursor();
+        cursorDirty = false;
+        const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+        if (!hasChanges(str, activeCursor)) {
+            return false;
+        }
+        const lines = str.split('\n');
+        const visibleCount = visibleLineCount(lines, str);
+        const cursorSuffix = buildCursorSuffix(visibleCount, activeCursor);
+        if (str === previousOutput && cursorChanged) {
+            stream.write(buildCursorOnlySequence({
+                cursorWasShown,
+                previousLineCount,
+                previousCursorPosition,
+                visibleLineCount: visibleCount,
+                cursorPosition: activeCursor,
+            }));
+        }
+        else {
+            previousOutput = str;
+            const returnPrefix = buildReturnToBottomPrefix(cursorWasShown, previousLineCount, previousCursorPosition);
+            stream.write(returnPrefix +
+                ansiEscapes.eraseLines(previousLineCount) +
+                str +
+                cursorSuffix);
+            previousLineCount = lines.length;
         }
-        previousOutput = output;
-        stream.write(ansiEscapes.eraseLines(previousLineCount) + output);
-        previousLineCount = output.split('\n').length;
+        previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+        cursorWasShown = activeCursor !== undefined;
+        return true;
     };
     render.clear = () => {
-        stream.write(ansiEscapes.eraseLines(previousLineCount));
+        const prefix = buildReturnToBottomPrefix(cursorWasShown, previousLineCount, previousCursorPosition);
+        stream.write(prefix + ansiEscapes.eraseLines(previousLineCount));
         previousOutput = '';
         previousLineCount = 0;
+        previousCursorPosition = undefined;
+        cursorWasShown = false;
     };
     render.done = () => {
         previousOutput = '';
         previousLineCount = 0;
+        previousCursorPosition = undefined;
+        cursorWasShown = false;
         if (!showCursor) {
-            cliCursor.show();
+            cliCursor.show(stream);
             hasHiddenCursor = false;
         }
     };
     render.sync = (str) => {
-        const output = str + '\n';
-        previousOutput = output;
-        previousLineCount = output.split('\n').length;
+        const activeCursor = cursorDirty ? cursorPosition : undefined;
+        cursorDirty = false;
+        const lines = str.split('\n');
+        previousOutput = str;
+        previousLineCount = lines.length;
+        if (!activeCursor && cursorWasShown) {
+            stream.write(hideCursorEscape);
+        }
+        if (activeCursor) {
+            stream.write(buildCursorSuffix(visibleLineCount(lines, str), activeCursor));
+        }
+        previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+        cursorWasShown = activeCursor !== undefined;
+    };
+    render.setCursorPosition = (position) => {
+        cursorPosition = position;
+        cursorDirty = true;
     };
+    render.isCursorDirty = () => cursorDirty;
+    render.willRender = (str) => hasChanges(str, getActiveCursor());
     return render;
 };
 const createIncremental = (stream, { showCursor = false } = {}) => {
     let previousLines = [];
     let previousOutput = '';
     let hasHiddenCursor = false;
+    let cursorPosition;
+    let cursorDirty = false;
+    let previousCursorPosition;
+    let cursorWasShown = false;
+    const getActiveCursor = () => (cursorDirty ? cursorPosition : undefined);
+    const hasChanges = (str, activeCursor) => {
+        const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+        return str !== previousOutput || cursorChanged;
+    };
     const render = (str) => {
         if (!showCursor && !hasHiddenCursor) {
-            cliCursor.hide();
+            cliCursor.hide(stream);
             hasHiddenCursor = true;
         }
-        const output = str + '\n';
-        if (output === previousOutput) {
-            return;
-        }
-        const previousCount = previousLines.length;
-        const nextLines = output.split('\n');
-        const nextCount = nextLines.length;
-        const visibleCount = nextCount - 1;
-        if (output === '\n' || previousOutput.length === 0) {
-            stream.write(ansiEscapes.eraseLines(previousCount) + output);
-            previousOutput = output;
+        // Only use cursor if setCursorPosition was called since last render.
+        // This ensures stale positions don't persist after component unmount.
+        const activeCursor = getActiveCursor();
+        cursorDirty = false;
+        const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+        if (!hasChanges(str, activeCursor)) {
+            return false;
+        }
+        const nextLines = str.split('\n');
+        const visibleCount = visibleLineCount(nextLines, str);
+        const previousVisible = visibleLineCount(previousLines, previousOutput);
+        if (str === previousOutput && cursorChanged) {
+            stream.write(buildCursorOnlySequence({
+                cursorWasShown,
+                previousLineCount: previousLines.length,
+                previousCursorPosition,
+                visibleLineCount: visibleCount,
+                cursorPosition: activeCursor,
+            }));
+            previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+            cursorWasShown = activeCursor !== undefined;
+            return true;
+        }
+        const returnPrefix = buildReturnToBottomPrefix(cursorWasShown, previousLines.length, previousCursorPosition);
+        if (str === '\n' || previousOutput.length === 0) {
+            const cursorSuffix = buildCursorSuffix(visibleCount, activeCursor);
+            stream.write(returnPrefix +
+                ansiEscapes.eraseLines(previousLines.length) +
+                str +
+                cursorSuffix);
+            cursorWasShown = activeCursor !== undefined;
+            previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+            previousOutput = str;
             previousLines = nextLines;
-            return;
+            return true;
         }
+        const hasTrailingNewline = str.endsWith('\n');
         // 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 (nextCount < previousCount) {
-            buffer.push(
-            // Erases the trailing lines and the final newline slot.
-            ansiEscapes.eraseLines(previousCount - nextCount + 1), 
-            // Positions cursor to the top of the rendered output.
-            ansiEscapes.cursorUp(visibleCount));
+        if (visibleCount < previousVisible) {
+            const previousHadTrailingNewline = previousOutput.endsWith('\n');
+            const extraSlot = previousHadTrailingNewline ? 1 : 0;
+            buffer.push(ansiEscapes.eraseLines(previousVisible - visibleCount + extraSlot), ansiEscapes.cursorUp(visibleCount));
         }
         else {
-            buffer.push(ansiEscapes.cursorUp(previousCount - 1));
+            buffer.push(ansiEscapes.cursorUp(previousVisible - 1));
         }
         for (let i = 0; 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]) {
-                buffer.push(ansiEscapes.cursorNextLine);
+                // Don't move past the last line when there's no trailing newline,
+                // otherwise the cursor overshoots the rendered block.
+                if (!isLastLine || hasTrailingNewline) {
+                    buffer.push(ansiEscapes.cursorNextLine);
+                }
                 continue;
             }
-            buffer.push(ansiEscapes.eraseLine + nextLines[i] + '\n');
+            buffer.push(ansiEscapes.cursorTo(0) +
+                nextLines[i] +
+                ansiEscapes.eraseEndLine +
+                // Don't append newline after the last line when the input
+                // has no trailing newline (fullscreen mode).
+                (isLastLine && !hasTrailingNewline ? '' : '\n'));
         }
+        const cursorSuffix = buildCursorSuffix(visibleCount, activeCursor);
+        buffer.push(cursorSuffix);
         stream.write(buffer.join(''));
-        previousOutput = output;
+        cursorWasShown = activeCursor !== undefined;
+        previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+        previousOutput = str;
         previousLines = nextLines;
+        return true;
     };
     render.clear = () => {
-        stream.write(ansiEscapes.eraseLines(previousLines.length));
+        const prefix = buildReturnToBottomPrefix(cursorWasShown, previousLines.length, previousCursorPosition);
+        stream.write(prefix + ansiEscapes.eraseLines(previousLines.length));
         previousOutput = '';
         previousLines = [];
+        previousCursorPosition = undefined;
+        cursorWasShown = false;
     };
     render.done = () => {
         previousOutput = '';
         previousLines = [];
+        previousCursorPosition = undefined;
+        cursorWasShown = false;
         if (!showCursor) {
-            cliCursor.show();
+            cliCursor.show(stream);
             hasHiddenCursor = false;
         }
     };
     render.sync = (str) => {
-        const output = str + '\n';
-        previousOutput = output;
-        previousLines = output.split('\n');
+        const activeCursor = cursorDirty ? cursorPosition : undefined;
+        cursorDirty = false;
+        const lines = str.split('\n');
+        previousOutput = str;
+        previousLines = lines;
+        if (!activeCursor && cursorWasShown) {
+            stream.write(hideCursorEscape);
+        }
+        if (activeCursor) {
+            stream.write(buildCursorSuffix(visibleLineCount(lines, str), activeCursor));
+        }
+        previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+        cursorWasShown = activeCursor !== undefined;
+    };
+    render.setCursorPosition = (position) => {
+        cursorPosition = position;
+        cursorDirty = true;
     };
+    render.isCursorDirty = () => cursorDirty;
+    render.willRender = (str) => hasChanges(str, getActiveCursor());
     return render;
 };
 const create = (stream, { showCursor = false, incremental = false } = {}) => {

package/build/log-update.js.map

@@ -1 +1 @@
-{"version":3,"file":"log-update.js","sourceRoot":"","sources":["../src/log-update.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"log-update.js","sourceRoot":"","sources":["../src/log-update.ts"],"names":[],"mappings":"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"}

package/build/parse-keypress.d.ts

@@ -9,6 +9,14 @@ type ParsedKey = {
     sequence: string;
     raw: string | undefined;
     code?: string;
+    super?: boolean;
+    hyper?: boolean;
+    capsLock?: boolean;
+    numLock?: boolean;
+    eventType?: 'press' | 'repeat' | 'release';
+    isKittyProtocol?: boolean;
+    text?: string;
+    isPrintable?: boolean;
 };
 declare const parseKeypress: (s?: Buffer | string) => ParsedKey;
 export default parseKeypress;

package/build/parse-keypress.js

@@ -1,5 +1,6 @@
 // Copied from https://github.com/enquirer/enquirer/blob/36785f3399a41cd61e9d28d1eb9c2fcd73d69b4c/lib/keypress.js
 import { Buffer } from 'node:buffer';
+import { kittyModifiers } from './kitty-keyboard.js';
 const metaKeyCodeRe = /^(?:\x1b)([a-zA-Z0-9])$/;
 const fnKeyRe = /^(?:\x1b+)(O|N|\[|\[\[)(?:(\d+)(?:;(\d+))?([~^$])|(?:1;)?(\d+)?([a-zA-Z]))/;
 const keyName = {
@@ -115,6 +116,249 @@ const isCtrlKey = (code) => {
         '[8^',
     ].includes(code);
 };
+// Kitty keyboard protocol: CSI codepoint ; modifiers [: eventType] [; text-as-codepoints] u
+const kittyKeyRe = /^\x1b\[(\d+)(?:;(\d+)(?::(\d+))?(?:;([\d:]+))?)?u$/;
+// Kitty-enhanced special keys: CSI number ; modifiers : eventType {letter|~}
+// These are legacy CSI sequences enhanced with the :eventType field.
+// Examples: \x1b[1;1:1A (up arrow press), \x1b[3;1:3~ (delete release)
+const kittySpecialKeyRe = /^\x1b\[(\d+);(\d+):(\d+)([A-Za-z~])$/;
+// Letter-terminated special key names (CSI 1 ; mods letter)
+const kittySpecialLetterKeys = {
+    A: 'up',
+    B: 'down',
+    C: 'right',
+    D: 'left',
+    E: 'clear',
+    F: 'end',
+    H: 'home',
+    P: 'f1',
+    Q: 'f2',
+    R: 'f3',
+    S: 'f4',
+};
+// Number-terminated special key names (CSI number ; mods ~)
+const kittySpecialNumberKeys = {
+    2: 'insert',
+    3: 'delete',
+    5: 'pageup',
+    6: 'pagedown',
+    7: 'home',
+    8: 'end',
+    11: 'f1',
+    12: 'f2',
+    13: 'f3',
+    14: 'f4',
+    15: 'f5',
+    17: 'f6',
+    18: 'f7',
+    19: 'f8',
+    20: 'f9',
+    21: 'f10',
+    23: 'f11',
+    24: 'f12',
+};
+// Map of special codepoints to key names in kitty protocol
+const kittyCodepointNames = {
+    27: 'escape',
+    // 13 (return) and 32 (space) are handled before this lookup
+    // in parseKittyKeypress so they can be marked as printable.
+    9: 'tab',
+    127: 'delete',
+    8: 'backspace',
+    57358: 'capslock',
+    57359: 'scrolllock',
+    57360: 'numlock',
+    57361: 'printscreen',
+    57362: 'pause',
+    57363: 'menu',
+    57376: 'f13',
+    57377: 'f14',
+    57378: 'f15',
+    57379: 'f16',
+    57380: 'f17',
+    57381: 'f18',
+    57382: 'f19',
+    57383: 'f20',
+    57384: 'f21',
+    57385: 'f22',
+    57386: 'f23',
+    57387: 'f24',
+    57388: 'f25',
+    57389: 'f26',
+    57390: 'f27',
+    57391: 'f28',
+    57392: 'f29',
+    57393: 'f30',
+    57394: 'f31',
+    57395: 'f32',
+    57396: 'f33',
+    57397: 'f34',
+    57398: 'f35',
+    57399: 'kp0',
+    57400: 'kp1',
+    57401: 'kp2',
+    57402: 'kp3',
+    57403: 'kp4',
+    57404: 'kp5',
+    57405: 'kp6',
+    57406: 'kp7',
+    57407: 'kp8',
+    57408: 'kp9',
+    57409: 'kpdecimal',
+    57410: 'kpdivide',
+    57411: 'kpmultiply',
+    57412: 'kpsubtract',
+    57413: 'kpadd',
+    57414: 'kpenter',
+    57415: 'kpequal',
+    57416: 'kpseparator',
+    57417: 'kpleft',
+    57418: 'kpright',
+    57419: 'kpup',
+    57420: 'kpdown',
+    57421: 'kppageup',
+    57422: 'kppagedown',
+    57423: 'kphome',
+    57424: 'kpend',
+    57425: 'kpinsert',
+    57426: 'kpdelete',
+    57427: 'kpbegin',
+    57428: 'mediaplay',
+    57429: 'mediapause',
+    57430: 'mediaplaypause',
+    57431: 'mediareverse',
+    57432: 'mediastop',
+    57433: 'mediafastforward',
+    57434: 'mediarewind',
+    57435: 'mediatracknext',
+    57436: 'mediatrackprevious',
+    57437: 'mediarecord',
+    57438: 'lowervolume',
+    57439: 'raisevolume',
+    57440: 'mutevolume',
+    57441: 'leftshift',
+    57442: 'leftcontrol',
+    57443: 'leftalt',
+    57444: 'leftsuper',
+    57445: 'lefthyper',
+    57446: 'leftmeta',
+    57447: 'rightshift',
+    57448: 'rightcontrol',
+    57449: 'rightalt',
+    57450: 'rightsuper',
+    57451: 'righthyper',
+    57452: 'rightmeta',
+    57453: 'isoLevel3Shift',
+    57454: 'isoLevel5Shift',
+};
+// Valid Unicode codepoint range, excluding surrogates
+const isValidCodepoint = (cp) => cp >= 0 && cp <= 0x10_ffff && !(cp >= 0xd8_00 && cp <= 0xdf_ff);
+const safeFromCodePoint = (cp) => isValidCodepoint(cp) ? String.fromCodePoint(cp) : '?';
+function resolveEventType(value) {
+    if (value === 3)
+        return 'release';
+    if (value === 2)
+        return 'repeat';
+    return 'press';
+}
+function parseKittyModifiers(modifiers) {
+    return {
+        ctrl: !!(modifiers & kittyModifiers.ctrl),
+        shift: !!(modifiers & kittyModifiers.shift),
+        meta: !!(modifiers & kittyModifiers.meta),
+        option: !!(modifiers & kittyModifiers.alt),
+        super: !!(modifiers & kittyModifiers.super),
+        hyper: !!(modifiers & kittyModifiers.hyper),
+        capsLock: !!(modifiers & kittyModifiers.capsLock),
+        numLock: !!(modifiers & kittyModifiers.numLock),
+    };
+}
+const parseKittyKeypress = (s) => {
+    const match = kittyKeyRe.exec(s);
+    if (!match)
+        return null;
+    const codepoint = parseInt(match[1], 10);
+    const modifiers = match[2] ? Math.max(0, parseInt(match[2], 10) - 1) : 0;
+    const eventType = match[3] ? parseInt(match[3], 10) : 1;
+    const textField = match[4];
+    // Bail on invalid primary codepoint
+    if (!isValidCodepoint(codepoint)) {
+        return null;
+    }
+    // Parse text-as-codepoints field (colon-separated Unicode codepoints)
+    let text;
+    if (textField) {
+        text = textField
+            .split(':')
+            .map(cp => safeFromCodePoint(parseInt(cp, 10)))
+            .join('');
+    }
+    // Determine key name from codepoint
+    let name;
+    let isPrintable;
+    if (codepoint === 32) {
+        name = 'space';
+        isPrintable = true;
+    }
+    else if (codepoint === 13) {
+        name = 'return';
+        isPrintable = true;
+    }
+    else if (kittyCodepointNames[codepoint]) {
+        name = kittyCodepointNames[codepoint];
+        isPrintable = false;
+    }
+    else if (codepoint >= 1 && codepoint <= 26) {
+        // Ctrl+letter comes as codepoint 1-26
+        name = String.fromCodePoint(codepoint + 96); // 'a' is 97
+        isPrintable = false;
+    }
+    else {
+        name = safeFromCodePoint(codepoint).toLowerCase();
+        isPrintable = true;
+    }
+    // Default text to the character from the codepoint when not explicitly
+    // provided by the protocol, so keys like space and return produce their
+    // expected text input (' ' and '\r' respectively).
+    if (isPrintable && !text) {
+        text = safeFromCodePoint(codepoint);
+    }
+    return {
+        name,
+        ...parseKittyModifiers(modifiers),
+        eventType: resolveEventType(eventType),
+        sequence: s,
+        raw: s,
+        isKittyProtocol: true,
+        isPrintable,
+        text,
+    };
+};
+// Parse kitty-enhanced special key sequences (arrow keys, function keys, etc.)
+// These use the legacy CSI format but with an added :eventType field.
+const parseKittySpecialKey = (s) => {
+    const match = kittySpecialKeyRe.exec(s);
+    if (!match)
+        return null;
+    const number = parseInt(match[1], 10);
+    const modifiers = Math.max(0, parseInt(match[2], 10) - 1);
+    const eventType = parseInt(match[3], 10);
+    const terminator = match[4];
+    const name = terminator === '~'
+        ? kittySpecialNumberKeys[number]
+        : kittySpecialLetterKeys[terminator];
+    if (!name)
+        return null;
+    return {
+        name,
+        ...parseKittyModifiers(modifiers),
+        eventType: resolveEventType(eventType),
+        sequence: s,
+        raw: s,
+        isKittyProtocol: true,
+        isPrintable: false,
+    };
+};
 const parseKeypress = (s = '') => {
     let parts;
     if (Buffer.isBuffer(s)) {
@@ -132,6 +376,29 @@ const parseKeypress = (s = '') => {
     else if (!s) {
         s = '';
     }
+    // Try kitty keyboard protocol parsers first
+    const kittyResult = parseKittyKeypress(s);
+    if (kittyResult)
+        return kittyResult;
+    const kittySpecialResult = parseKittySpecialKey(s);
+    if (kittySpecialResult)
+        return kittySpecialResult;
+    // If the input matched the kitty CSI-u pattern but was rejected (e.g.,
+    // invalid codepoint), return a safe empty keypress instead of falling
+    // through to legacy parsing which can produce unsafe states (undefined name)
+    if (kittyKeyRe.test(s)) {
+        return {
+            name: '',
+            ctrl: false,
+            meta: false,
+            shift: false,
+            option: false,
+            sequence: s,
+            raw: s,
+            isKittyProtocol: true,
+            isPrintable: false,
+        };
+    }
     const key = {
         name: '',
         ctrl: false,
@@ -142,10 +409,11 @@ const parseKeypress = (s = '') => {
         raw: s,
     };
     key.sequence = key.sequence || s || key.name;
-    if (s === '\r') {
-        // carriage return
+    if (s === '\r' || s === '\x1b\r') {
+        // carriage return (or option+return on macOS)
         key.raw = undefined;
         key.name = 'return';
+        key.option = s.length === 2;
     }
     else if (s === '\n') {
         // enter, should have been called linefeed