ink 6.7.0 → 7.0.0

package/build/ink.js

@@ -9,10 +9,11 @@ import patchConsole from 'patch-console';
 import { LegacyRoot, ConcurrentRoot } from 'react-reconciler/constants.js';
 import Yoga from 'yoga-layout';
 import wrapAnsi from 'wrap-ansi';
-import terminalSize from 'terminal-size';
+import { getWindowSize } from './utils.js';
 import reconciler from './reconciler.js';
 import render from './renderer.js';
 import * as dom from './dom.js';
+import { hideCursorEscape, showCursorEscape } from './cursor-helpers.js';
 import logUpdate from './log-update.js';
 import { bsu, esu, shouldSynchronize } from './write-synchronized.js';
 import instances from './instances.js';
@@ -20,6 +21,110 @@ import App from './components/App.js';
 import { accessibilityContext as AccessibilityContext } from './components/AccessibilityContext.js';
 import { resolveFlags, } from './kitty-keyboard.js';
 const noop = () => { };
+const textEncoder = new TextEncoder();
+const yieldImmediate = async () => new Promise(resolve => {
+    setImmediate(resolve);
+});
+const kittyQueryEscapeByte = 0x1b;
+const kittyQueryOpenBracketByte = 0x5b;
+const kittyQueryQuestionMarkByte = 0x3f;
+const kittyQueryLetterByte = 0x75;
+const zeroByte = 0x30;
+const nineByte = 0x39;
+const isDigitByte = (byte) => byte >= zeroByte && byte <= nineByte;
+const matchKittyQueryResponse = (buffer, startIndex) => {
+    if (buffer[startIndex] !== kittyQueryEscapeByte ||
+        buffer[startIndex + 1] !== kittyQueryOpenBracketByte ||
+        buffer[startIndex + 2] !== kittyQueryQuestionMarkByte) {
+        return undefined;
+    }
+    let index = startIndex + 3;
+    const digitsStartIndex = index;
+    while (index < buffer.length && isDigitByte(buffer[index])) {
+        index++;
+    }
+    if (index === digitsStartIndex) {
+        return undefined;
+    }
+    if (index === buffer.length) {
+        return { state: 'partial' };
+    }
+    if (buffer[index] === kittyQueryLetterByte) {
+        return { state: 'complete', endIndex: index };
+    }
+    return undefined;
+};
+const hasCompleteKittyQueryResponse = (buffer) => {
+    for (let index = 0; index < buffer.length; index++) {
+        const match = matchKittyQueryResponse(buffer, index);
+        if (match?.state === 'complete') {
+            return true;
+        }
+    }
+    return false;
+};
+const stripKittyQueryResponsesAndTrailingPartial = (buffer) => {
+    const keptBytes = [];
+    let index = 0;
+    while (index < buffer.length) {
+        const match = matchKittyQueryResponse(buffer, index);
+        if (match?.state === 'complete') {
+            index = match.endIndex + 1;
+            continue;
+        }
+        if (match?.state === 'partial') {
+            break;
+        }
+        keptBytes.push(buffer[index]);
+        index++;
+    }
+    return keptBytes;
+};
+const shouldClearTerminalForFrame = ({ isTty, viewportRows, previousOutputHeight, nextOutputHeight, isUnmounting, }) => {
+    if (!isTty) {
+        return false;
+    }
+    const hadPreviousFrame = previousOutputHeight > 0;
+    const wasFullscreen = previousOutputHeight >= viewportRows;
+    const wasOverflowing = previousOutputHeight > viewportRows;
+    const isOverflowing = nextOutputHeight > viewportRows;
+    const isLeavingFullscreen = wasFullscreen && nextOutputHeight < viewportRows;
+    const shouldClearOnUnmount = isUnmounting && wasFullscreen;
+    return (
+    // Overflowing frames still need full clear fallback.
+    wasOverflowing ||
+        (isOverflowing && hadPreviousFrame) ||
+        // Clear when shrinking from fullscreen to non-fullscreen output.
+        isLeavingFullscreen ||
+        // Preserve legacy unmount behavior for fullscreen frames: final teardown
+        // render should clear once to avoid leaving a scrolled viewport state.
+        shouldClearOnUnmount);
+};
+const isErrorInput = (value) => {
+    return (value instanceof Error ||
+        Object.prototype.toString.call(value) === '[object Error]');
+};
+const getWritableStreamState = (stdout) => {
+    const canWriteToStdout = !stdout.destroyed && !stdout.writableEnded && (stdout.writable ?? true);
+    const hasWritableState = stdout._writableState !== undefined || stdout.writableLength !== undefined;
+    return {
+        canWriteToStdout,
+        hasWritableState,
+    };
+};
+const settleThrottle = (throttled, canWriteToStdout) => {
+    if (!throttled ||
+        typeof throttled.flush !== 'function') {
+        return;
+    }
+    const throttledValue = throttled;
+    if (canWriteToStdout) {
+        throttledValue.flush();
+    }
+    else if (typeof throttledValue.cancel === 'function') {
+        throttledValue.cancel();
+    }
+};
 export default class Ink {
     /**
     Whether this instance is using concurrent rendering mode.
@@ -30,8 +135,12 @@ export default class Ink {
     cursorPosition;
     throttledLog;
     isScreenReaderEnabled;
+    interactive;
+    renderThrottleMs;
+    alternateScreen;
     // Ignore last render after unmounting a tree to prevent empty output before exit
     isUnmounted;
+    isUnmounting;
     lastOutput;
     lastOutputToRender;
     lastOutputHeight;
@@ -42,12 +151,15 @@ export default class Ink {
     // so that it's rerendered every time, not just new static parts, like in non-debug mode
     fullStaticOutput;
     exitPromise;
+    exitResult;
     beforeExitHandler;
     restoreConsole;
     unsubscribeResize;
     throttledOnRender;
+    hasPendingThrottledRender = false;
     kittyProtocolEnabled = false;
     cancelKittyDetection;
+    nextRenderCommit;
     constructor(options) {
         autoBind(this);
         this.options = options;
@@ -56,9 +168,18 @@ export default class Ink {
         this.isScreenReaderEnabled =
             options.isScreenReaderEnabled ??
                 process.env['INK_SCREEN_READER'] === 'true';
+        // CI detection takes precedence: even a TTY stdout in CI defaults to non-interactive.
+        // Using Boolean(isTTY) (rather than an 'in' guard) correctly handles piped streams
+        // where the property is absent (e.g. `node app.js | cat`).
+        this.interactive = this.resolveInteractiveOption(options.interactive);
+        this.alternateScreen = false;
         const unthrottled = options.debug || this.isScreenReaderEnabled;
         const maxFps = options.maxFps ?? 30;
+        // Treat non-positive maxFps as an internal fallback case, not a supported
+        // "disable throttling" mode. Keep animation scheduling on a normal cadence
+        // so future changes don't accidentally reintroduce zero-delay loops.
         const renderThrottleMs = maxFps > 0 ? Math.max(1, Math.ceil(1000 / maxFps)) : 0;
+        this.renderThrottleMs = unthrottled ? 0 : renderThrottleMs;
         if (unthrottled) {
             this.rootNode.onRender = this.onRender;
             this.throttledOnRender = undefined;
@@ -68,7 +189,10 @@ export default class Ink {
                 leading: true,
                 trailing: true,
             });
-            this.rootNode.onRender = throttled;
+            this.rootNode.onRender = () => {
+                this.hasPendingThrottledRender = true;
+                throttled();
+            };
             this.throttledOnRender = throttled;
         }
         this.rootNode.onImmediateRender = this.onRender;
@@ -80,7 +204,7 @@ export default class Ink {
             ? this.log
             : throttle((output) => {
                 const shouldWrite = this.log.willRender(output);
-                const sync = shouldSynchronize(this.options.stdout);
+                const sync = this.shouldSync();
                 if (sync && shouldWrite) {
                     this.options.stdout.write(bsu);
                 }
@@ -94,13 +218,14 @@ export default class Ink {
             });
         // Ignore last render after unmounting a tree to prevent empty output before exit
         this.isUnmounted = false;
+        this.isUnmounting = false;
         // Store concurrent mode setting
         this.isConcurrent = options.concurrent ?? false;
         // Store last output to only rerender when needed
         this.lastOutput = '';
         this.lastOutputToRender = '';
         this.lastOutputHeight = 0;
-        this.lastTerminalWidth = this.getTerminalWidth();
+        this.lastTerminalWidth = getWindowSize(this.options.stdout).columns;
         // This variable is used only in debug mode to store full static output
         // so that it's rerendered every time, not just new static parts, like in non-debug mode
         this.fullStaticOutput = '';
@@ -110,37 +235,31 @@ export default class Ink {
         this.container = reconciler.createContainer(this.rootNode, rootTag, null, false, null, 'id', () => { }, () => { }, () => { }, () => { });
         // Unmount when process exits
         this.unsubscribeExit = signalExit(this.unmount, { alwaysLast: false });
+        this.setAlternateScreen(Boolean(options.alternateScreen));
         if (process.env['DEV'] === 'true') {
-            reconciler.injectIntoDevTools({
-                bundleType: 0,
-                // Reporting React DOM's version, not Ink's
-                // See https://github.com/facebook/react/issues/16666#issuecomment-532639905
-                version: '16.13.1',
-                rendererPackageName: 'ink',
-            });
+            // @ts-expect-error outdated types
+            reconciler.injectIntoDevTools();
         }
         if (options.patchConsole) {
             this.patchConsole();
         }
-        if (!isInCi) {
+        if (this.interactive) {
             options.stdout.on('resize', this.resized);
             this.unsubscribeResize = () => {
                 options.stdout.off('resize', this.resized);
             };
         }
         this.initKittyKeyboard();
+        this.exitPromise = new Promise((resolve, reject) => {
+            this.resolveExitPromise = resolve;
+            this.rejectExitPromise = reject;
+        });
+        // Prevent global unhandled-rejection crashes when app code exits with an
+        // error but consumers never call waitUntilExit().
+        void this.exitPromise.catch(noop);
     }
-    getTerminalWidth = () => {
-        // The 'columns' property can be undefined or 0 when not using a TTY.
-        // Use terminal-size as a fallback for piped processes, then default to 80.
-        if (this.options.stdout.columns) {
-            return this.options.stdout.columns;
-        }
-        const size = terminalSize();
-        return size?.columns ?? 80;
-    };
     resized = () => {
-        const currentWidth = this.getTerminalWidth();
+        const currentWidth = getWindowSize(this.options.stdout).columns;
         if (currentWidth < this.lastTerminalWidth) {
             // We clear the screen when decreasing terminal width to prevent duplicate overlapping re-renders.
             this.log.clear();
@@ -154,25 +273,44 @@ export default class Ink {
     resolveExitPromise = () => { };
     rejectExitPromise = () => { };
     unsubscribeExit = () => { };
+    handleAppExit = (errorOrResult) => {
+        if (this.isUnmounted || this.isUnmounting) {
+            return;
+        }
+        if (isErrorInput(errorOrResult)) {
+            this.unmount(errorOrResult);
+            return;
+        }
+        this.exitResult = errorOrResult;
+        this.unmount();
+    };
     setCursorPosition = (position) => {
         this.cursorPosition = position;
         this.log.setCursorPosition(position);
     };
     restoreLastOutput = () => {
+        if (!this.interactive) {
+            return;
+        }
         // Clear() resets log-update's cursor state, so replay the latest cursor intent
         // before restoring output after external stdout/stderr writes.
         this.log.setCursorPosition(this.cursorPosition);
         this.log(this.lastOutputToRender || this.lastOutput + '\n');
     };
     calculateLayout = () => {
-        const terminalWidth = this.getTerminalWidth();
+        const terminalWidth = getWindowSize(this.options.stdout).columns;
         this.rootNode.yogaNode.setWidth(terminalWidth);
         this.rootNode.yogaNode.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
     };
     onRender = () => {
+        this.hasPendingThrottledRender = false;
         if (this.isUnmounted) {
             return;
         }
+        if (this.nextRenderCommit) {
+            this.nextRenderCommit.resolve();
+            this.nextRenderCommit = undefined;
+        }
         const startTime = performance.now();
         const { output, outputHeight, staticOutput } = render(this.rootNode, this.isScreenReaderEnabled);
         this.options.onRender?.({ renderTime: performance.now() - startTime });
@@ -182,10 +320,13 @@ export default class Ink {
             if (hasStaticOutput) {
                 this.fullStaticOutput += staticOutput;
             }
+            this.lastOutput = output;
+            this.lastOutputToRender = output;
+            this.lastOutputHeight = outputHeight;
             this.options.stdout.write(this.fullStaticOutput + output);
             return;
         }
-        if (isInCi) {
+        if (!this.interactive) {
             if (hasStaticOutput) {
                 this.options.stdout.write(staticOutput);
             }
@@ -195,7 +336,7 @@ export default class Ink {
             return;
         }
         if (this.isScreenReaderEnabled) {
-            const sync = shouldSynchronize(this.options.stdout);
+            const sync = this.shouldSync();
             if (sync) {
                 this.options.stdout.write(bsu);
             }
@@ -214,7 +355,7 @@ export default class Ink {
                 }
                 return;
             }
-            const terminalWidth = this.getTerminalWidth();
+            const terminalWidth = getWindowSize(this.options.stdout).columns;
             const wrappedOutput = wrapAnsi(output, terminalWidth, {
                 trim: false,
                 hard: true,
@@ -241,49 +382,11 @@ export default class Ink {
         if (hasStaticOutput) {
             this.fullStaticOutput += staticOutput;
         }
-        // Detect fullscreen: output fills or exceeds terminal height.
-        // Only apply when writing to a real TTY — piped output always gets trailing newlines.
-        const isFullscreen = this.options.stdout.isTTY && outputHeight >= this.options.stdout.rows;
-        const outputToRender = isFullscreen ? output : output + '\n';
-        if (this.lastOutputHeight >= this.options.stdout.rows) {
-            const sync = shouldSynchronize(this.options.stdout);
-            if (sync) {
-                this.options.stdout.write(bsu);
-            }
-            this.options.stdout.write(ansiEscapes.clearTerminal + this.fullStaticOutput + output);
-            this.lastOutput = output;
-            this.lastOutputToRender = outputToRender;
-            this.lastOutputHeight = outputHeight;
-            this.log.sync(outputToRender);
-            if (sync) {
-                this.options.stdout.write(esu);
-            }
-            return;
-        }
-        // To ensure static output is cleanly rendered before main output, clear main output first
-        if (hasStaticOutput) {
-            const sync = shouldSynchronize(this.options.stdout);
-            if (sync) {
-                this.options.stdout.write(bsu);
-            }
-            this.log.clear();
-            this.options.stdout.write(staticOutput);
-            this.log(outputToRender);
-            if (sync) {
-                this.options.stdout.write(esu);
-            }
-        }
-        else if (output !== this.lastOutput || this.log.isCursorDirty()) {
-            // ThrottledLog manages its own bsu/esu at actual write time
-            this.throttledLog(outputToRender);
-        }
-        this.lastOutput = output;
-        this.lastOutputToRender = outputToRender;
-        this.lastOutputHeight = outputHeight;
+        this.renderInteractiveFrame(output, outputHeight, hasStaticOutput ? staticOutput : '');
     };
     render(node) {
         const tree = (React.createElement(AccessibilityContext.Provider, { value: { isScreenReaderEnabled: this.isScreenReaderEnabled } },
-            React.createElement(App, { stdin: this.options.stdin, stdout: this.options.stdout, stderr: this.options.stderr, exitOnCtrlC: this.options.exitOnCtrlC, writeToStdout: this.writeToStdout, writeToStderr: this.writeToStderr, setCursorPosition: this.setCursorPosition, onExit: this.unmount }, node)));
+            React.createElement(App, { stdin: this.options.stdin, stdout: this.options.stdout, stderr: this.options.stderr, exitOnCtrlC: this.options.exitOnCtrlC, interactive: this.interactive, renderThrottleMs: this.renderThrottleMs, writeToStdout: this.writeToStdout, writeToStderr: this.writeToStderr, setCursorPosition: this.setCursorPosition, onExit: this.handleAppExit, onWaitUntilRenderFlush: this.waitUntilRenderFlush }, node)));
         if (this.options.concurrent) {
             // Concurrent mode: use updateContainer (async scheduling)
             reconciler.updateContainer(tree, this.container, null, noop);
@@ -302,11 +405,11 @@ export default class Ink {
             this.options.stdout.write(data + this.fullStaticOutput + this.lastOutput);
             return;
         }
-        if (isInCi) {
+        if (!this.interactive) {
             this.options.stdout.write(data);
             return;
         }
-        const sync = shouldSynchronize(this.options.stdout);
+        const sync = this.shouldSync();
         if (sync) {
             this.options.stdout.write(bsu);
         }
@@ -326,11 +429,11 @@ export default class Ink {
             this.options.stdout.write(this.fullStaticOutput + this.lastOutput);
             return;
         }
-        if (isInCi) {
+        if (!this.interactive) {
             this.options.stderr.write(data);
             return;
         }
-        const sync = shouldSynchronize(this.options.stdout);
+        const sync = this.shouldSync();
         if (sync) {
             this.options.stdout.write(bsu);
         }
@@ -341,98 +444,125 @@ export default class Ink {
             this.options.stdout.write(esu);
         }
     }
-    // eslint-disable-next-line @typescript-eslint/ban-types
+    // eslint-disable-next-line @typescript-eslint/no-restricted-types
     unmount(error) {
-        if (this.isUnmounted) {
+        if (this.isUnmounted || this.isUnmounting) {
             return;
         }
+        this.isUnmounting = true;
         if (this.beforeExitHandler) {
             process.off('beforeExit', this.beforeExitHandler);
             this.beforeExitHandler = undefined;
         }
-        // Flush any pending throttled render to ensure the final frame is rendered
-        if (this.throttledOnRender) {
-            this.throttledOnRender.flush();
+        const stdout = this.options.stdout;
+        const { canWriteToStdout, hasWritableState } = getWritableStreamState(stdout);
+        // Clear any pending throttled render timer on unmount. When stdout is writable,
+        // flush so the final frame is emitted; otherwise cancel to avoid delayed callbacks.
+        settleThrottle(this.throttledOnRender, canWriteToStdout);
+        if (canWriteToStdout) {
+            // If throttling is enabled and there is already a pending render, flushing above
+            // is sufficient. Also avoid calling onRender() again when static output already
+            // exists, as that can duplicate <Static> children output on exit (see issue #397).
+            const shouldRenderFinalFrame = !this.throttledOnRender ||
+                (!this.hasPendingThrottledRender && this.fullStaticOutput === '');
+            if (shouldRenderFinalFrame) {
+                this.calculateLayout();
+                this.onRender();
+            }
         }
-        this.calculateLayout();
-        this.onRender();
+        // Mark as unmounted after the final render but before stdout writes
+        // that could re-enter exit() via synchronous write callbacks.
+        this.isUnmounted = true;
         this.unsubscribeExit();
+        // Flush any pending throttled log writes if possible, otherwise cancel to
+        // prevent delayed callbacks from writing to a closed stream.
+        settleThrottle(this.throttledLog, canWriteToStdout);
         if (typeof this.restoreConsole === 'function') {
+            // Once unmount starts, Ink stops trying to manage teardown-time
+            // console output. Restoring the native console before React cleanup keeps
+            // unmount behavior simple and avoids special-case handling for custom
+            // streams, fullscreen frames, and alternate-screen teardown.
             this.restoreConsole();
         }
-        if (typeof this.unsubscribeResize === 'function') {
-            this.unsubscribeResize();
-        }
-        // Flush any pending throttled log writes
-        const throttledLog = this.throttledLog;
-        if (typeof throttledLog.flush === 'function') {
-            throttledLog.flush();
-        }
-        // Cancel any in-progress auto-detection before checking protocol state
-        if (this.cancelKittyDetection) {
-            this.cancelKittyDetection();
-        }
-        if (this.kittyProtocolEnabled) {
-            try {
-                this.options.stdout.write('\u001B[<u');
+        const finishUnmount = () => {
+            if (typeof this.unsubscribeResize === 'function') {
+                this.unsubscribeResize();
             }
-            catch {
-                // Best-effort: stdout may already be destroyed during shutdown
+            // Cancel any in-progress auto-detection before checking protocol state
+            if (this.cancelKittyDetection) {
+                this.cancelKittyDetection();
+            }
+            if (canWriteToStdout) {
+                if (this.kittyProtocolEnabled) {
+                    this.writeBestEffort(this.options.stdout, '\u001B[<u');
+                }
+                // Alternate-screen content is disposable by design. We intentionally
+                // leave it active until React cleanup finishes, then restore the
+                // primary buffer without replaying prior frames, hook writes, or
+                // diagnostics onto it. Trying to preserve teardown output across the
+                // buffer switch adds fragile lifecycle-specific behavior, so Ink keeps
+                // alternate-screen teardown intentionally simple and best-effort.
+                if (this.alternateScreen) {
+                    this.writeBestEffort(this.options.stdout, ansiEscapes.exitAlternativeScreen);
+                    this.writeBestEffort(this.options.stdout, showCursorEscape);
+                    this.alternateScreen = false;
+                }
+                if (!this.interactive) {
+                    // Non-interactive environments don't handle erasing ansi escapes well.
+                    // In debug mode, each render already writes to stdout, so only a trailing
+                    // newline is needed. In non-debug mode, write the last frame now (it was
+                    // deferred during rendering).
+                    this.options.stdout.write(this.options.debug ? '\n' : this.lastOutput + '\n');
+                }
+                else if (!this.options.debug) {
+                    this.log.done();
+                }
             }
             this.kittyProtocolEnabled = false;
-        }
-        // CIs don't handle erasing ansi escapes well, so it's better to
-        // only render last frame of non-static output
-        if (isInCi) {
-            this.options.stdout.write(this.lastOutput + '\n');
-        }
-        else if (!this.options.debug) {
-            this.log.done();
-        }
-        this.isUnmounted = true;
-        if (this.options.concurrent) {
-            // Concurrent mode: use updateContainer (async scheduling)
-            reconciler.updateContainer(null, this.container, null, noop);
-        }
-        else {
-            // Legacy mode: use updateContainerSync + flushSyncWork (sync)
-            reconciler.updateContainerSync(null, this.container, null, noop);
-            reconciler.flushSyncWork();
-        }
-        instances.delete(this.options.stdout);
-        // Ensure all queued writes have been processed before resolving the
-        // exit promise. For real writable streams, queue an empty write as a
-        // barrier — its callback fires only after all prior writes complete.
-        // For non-stream objects (e.g. test spies), resolve on next tick.
-        //
-        // When called from signal-exit during process shutdown (error is a
-        // number or null rather than undefined/Error), resolve synchronously
-        // because the event loop is draining and async callbacks won't fire.
-        const resolveOrReject = () => {
-            if (error instanceof Error) {
-                this.rejectExitPromise(error);
+            instances.delete(this.options.stdout);
+            // Ensure all queued writes have been processed before resolving the
+            // exit promise. For real writable streams, queue an empty write as a
+            // barrier — its callback fires only after all prior writes complete.
+            // For non-stream objects (e.g. test spies), resolve on next tick.
+            //
+            // When called from signal-exit during process shutdown (error is a
+            // number or null rather than undefined/Error), resolve synchronously
+            // because the event loop is draining and async callbacks won't fire.
+            const { exitResult } = this;
+            const resolveOrReject = () => {
+                if (isErrorInput(error)) {
+                    this.rejectExitPromise(error);
+                }
+                else {
+                    this.resolveExitPromise(exitResult);
+                }
+            };
+            const isProcessExiting = error !== undefined && !isErrorInput(error);
+            if (isProcessExiting) {
+                resolveOrReject();
+            }
+            else if (canWriteToStdout && hasWritableState) {
+                this.options.stdout.write('', resolveOrReject);
             }
             else {
-                this.resolveExitPromise();
+                setImmediate(resolveOrReject);
             }
         };
-        const isProcessExiting = error !== undefined && !(error instanceof Error);
-        if (isProcessExiting) {
-            resolveOrReject();
-        }
-        else if (this.options.stdout._writableState !== undefined ||
-            this.options.stdout.writableLength !== undefined) {
-            this.options.stdout.write('', resolveOrReject);
+        const concurrentReconciler = reconciler;
+        if (this.options.concurrent) {
+            reconciler.updateContainerSync(null, this.container, null, noop);
+            reconciler.flushSyncWork();
+            concurrentReconciler.flushPassiveEffects?.();
+            finishUnmount();
         }
         else {
-            setImmediate(resolveOrReject);
+            // Legacy mode: use updateContainerSync + flushSyncWork (sync)
+            reconciler.updateContainerSync(null, this.container, null, noop);
+            reconciler.flushSyncWork();
+            finishUnmount();
         }
     }
     async waitUntilExit() {
-        this.exitPromise ||= new Promise((resolve, reject) => {
-            this.resolveExitPromise = resolve;
-            this.rejectExitPromise = reject;
-        });
         if (!this.beforeExitHandler) {
             this.beforeExitHandler = () => {
                 this.unmount();
@@ -441,8 +571,46 @@ export default class Ink {
         }
         return this.exitPromise;
     }
+    async waitUntilRenderFlush() {
+        if (this.isUnmounted || this.isUnmounting) {
+            await this.awaitExit();
+            return;
+        }
+        // Yield to the macrotask queue so that React's scheduler has a chance to
+        // fire passive effects and process any work they enqueued.
+        await yieldImmediate();
+        if (this.isUnmounted || this.isUnmounting) {
+            await this.awaitExit();
+            return;
+        }
+        // In concurrent mode, React's scheduler may still be mid-render after
+        // the yield. Wait for the next render commit instead of polling.
+        if (this.isConcurrent && this.hasPendingConcurrentWork()) {
+            await Promise.race([this.awaitNextRender(), this.awaitExit()]);
+            if (this.isUnmounted || this.isUnmounting) {
+                this.nextRenderCommit = undefined;
+                await this.awaitExit();
+                return;
+            }
+        }
+        reconciler.flushSyncWork();
+        const stdout = this.options.stdout;
+        const { canWriteToStdout, hasWritableState } = getWritableStreamState(stdout);
+        // Flush pending throttled render/log timers so their output is included in this wait.
+        settleThrottle(this.throttledOnRender, canWriteToStdout);
+        settleThrottle(this.throttledLog, canWriteToStdout);
+        if (canWriteToStdout && hasWritableState) {
+            await new Promise(resolve => {
+                this.options.stdout.write('', () => {
+                    resolve();
+                });
+            });
+            return;
+        }
+        await yieldImmediate();
+    }
     clear() {
-        if (!isInCi && !this.options.debug) {
+        if (this.interactive && !this.options.debug) {
             this.log.clear();
             // Sync lastOutput so that unmount's final onRender
             // sees it as unchanged and log-update skips it
@@ -465,6 +633,106 @@ export default class Ink {
             }
         });
     }
+    setAlternateScreen(enabled) {
+        this.alternateScreen = this.resolveAlternateScreenOption(enabled, this.interactive);
+        if (this.alternateScreen) {
+            this.writeBestEffort(this.options.stdout, ansiEscapes.enterAlternativeScreen);
+            this.writeBestEffort(this.options.stdout, hideCursorEscape);
+        }
+    }
+    resolveInteractiveOption(interactive) {
+        return interactive ?? (!isInCi && Boolean(this.options.stdout.isTTY));
+    }
+    resolveAlternateScreenOption(alternateScreen, interactive) {
+        return (Boolean(alternateScreen) &&
+            interactive &&
+            Boolean(this.options.stdout.isTTY));
+    }
+    shouldSync() {
+        return shouldSynchronize(this.options.stdout, this.interactive);
+    }
+    // Best-effort write: streams may already be destroyed during shutdown.
+    writeBestEffort(stream, data) {
+        try {
+            stream.write(data);
+        }
+        catch { }
+    }
+    // Waits for the exit promise to settle, suppressing any rejection.
+    // Errors are surfaced via waitUntilExit() instead.
+    async awaitExit() {
+        try {
+            await this.exitPromise;
+        }
+        catch { }
+    }
+    hasPendingConcurrentWork() {
+        const concurrentContainer = this.container;
+        return ((concurrentContainer.pendingLanes ?? 0) !== 0 &&
+            concurrentContainer.callbackNode !== undefined &&
+            concurrentContainer.callbackNode !== null);
+    }
+    async awaitNextRender() {
+        if (!this.nextRenderCommit) {
+            let resolveRender;
+            const promise = new Promise(resolve => {
+                resolveRender = resolve;
+            });
+            this.nextRenderCommit = { promise, resolve: resolveRender };
+        }
+        return this.nextRenderCommit.promise;
+    }
+    renderInteractiveFrame(output, outputHeight, staticOutput) {
+        const hasStaticOutput = staticOutput !== '';
+        const isTty = this.options.stdout.isTTY;
+        // Detect fullscreen: output fills or exceeds terminal height.
+        // Only apply when writing to a real TTY — piped output always gets trailing newlines.
+        const viewportRows = isTty ? getWindowSize(this.options.stdout).rows : 24;
+        const isFullscreen = isTty && outputHeight >= viewportRows;
+        const outputToRender = isFullscreen ? output : output + '\n';
+        const shouldClearTerminal = shouldClearTerminalForFrame({
+            isTty,
+            viewportRows,
+            previousOutputHeight: this.lastOutputHeight,
+            nextOutputHeight: outputHeight,
+            isUnmounting: this.isUnmounting,
+        });
+        if (shouldClearTerminal) {
+            const sync = this.shouldSync();
+            if (sync) {
+                this.options.stdout.write(bsu);
+            }
+            this.options.stdout.write(ansiEscapes.clearTerminal + this.fullStaticOutput + output);
+            this.lastOutput = output;
+            this.lastOutputToRender = outputToRender;
+            this.lastOutputHeight = outputHeight;
+            this.log.sync(outputToRender);
+            if (sync) {
+                this.options.stdout.write(esu);
+            }
+            return;
+        }
+        // To ensure static output is cleanly rendered before main output, clear main output first
+        if (hasStaticOutput) {
+            const sync = this.shouldSync();
+            if (sync) {
+                this.options.stdout.write(bsu);
+            }
+            this.log.clear();
+            this.options.stdout.write(staticOutput);
+            this.log(outputToRender);
+            if (sync) {
+                this.options.stdout.write(esu);
+            }
+        }
+        else if (output !== this.lastOutput || this.log.isCursorDirty()) {
+            // ThrottledLog manages its own bsu/esu at actual write time
+            this.throttledLog(outputToRender);
+        }
+        this.lastOutput = output;
+        this.lastOutputToRender = outputToRender;
+        this.lastOutputHeight = outputHeight;
+    }
     initKittyKeyboard() {
         // Protocol is opt-in: if kittyKeyboard is not specified, do nothing
         if (!this.options.kittyKeyboard) {
@@ -472,30 +740,33 @@ export default class Ink {
         }
         const opts = this.options.kittyKeyboard;
         const mode = opts.mode ?? 'auto';
-        if (mode === 'disabled' ||
-            !this.options.stdin.isTTY ||
-            !this.options.stdout.isTTY) {
+        if (mode === 'disabled') {
             return;
         }
         const flags = opts.flags ?? ['disambiguateEscapeCodes'];
+        // 'enabled' force-enables the protocol as long as both streams are TTYs,
+        // regardless of the interactive setting (e.g. even in CI).
         if (mode === 'enabled') {
-            this.enableKittyProtocol(flags);
+            if (this.options.stdin.isTTY && this.options.stdout.isTTY) {
+                this.enableKittyProtocol(flags);
+            }
             return;
         }
-        // Auto mode: use heuristic precheck, then confirm with protocol query
-        const term = process.env['TERM'] ?? '';
-        const termProgram = process.env['TERM_PROGRAM'] ?? '';
-        const isKnownSupportingTerminal = 'KITTY_WINDOW_ID' in process.env ||
-            term === 'xterm-kitty' ||
-            termProgram === 'WezTerm' ||
-            termProgram === 'ghostty';
-        if (!isInCi && isKnownSupportingTerminal) {
-            this.confirmKittySupport(flags);
+        // Auto mode: require interactive + TTY
+        if (!this.interactive ||
+            !this.options.stdin.isTTY ||
+            !this.options.stdout.isTTY) {
+            return;
         }
+        // Auto mode: query the terminal for kitty keyboard protocol support.
+        // The CSI ? u query is safe to send to any terminal — unsupporting
+        // terminals simply won't respond, and the 200ms timeout handles that.
+        // This avoids maintaining a hardcoded whitelist of terminal names.
+        this.confirmKittySupport(flags);
     }
     confirmKittySupport(flags) {
         const { stdin, stdout } = this.options;
-        let responseBuffer = '';
+        let responseBuffer = [];
         const cleanup = () => {
             this.cancelKittyDetection = undefined;
             clearTimeout(timer);
@@ -503,18 +774,18 @@ export default class Ink {
             // Re-emit any buffered data that wasn't the protocol response,
             // so it isn't lost from Ink's normal input pipeline.
             // Clear responseBuffer afterwards to make cleanup idempotent.
-            // eslint-disable-next-line no-control-regex
-            const remaining = responseBuffer.replace(/\u001B\[\?\d+u/, '');
-            responseBuffer = '';
-            if (remaining) {
-                stdin.unshift(Buffer.from(remaining));
+            const remaining = stripKittyQueryResponsesAndTrailingPartial(responseBuffer);
+            responseBuffer = [];
+            if (remaining.length > 0) {
+                stdin.unshift(Uint8Array.from(remaining));
             }
         };
         const onData = (data) => {
-            responseBuffer +=
-                typeof data === 'string' ? data : Buffer.from(data).toString();
-            // eslint-disable-next-line no-control-regex
-            if (/\u001B\[\?\d+u/.test(responseBuffer)) {
+            const chunk = typeof data === 'string' ? textEncoder.encode(data) : data;
+            for (const byte of chunk) {
+                responseBuffer.push(byte);
+            }
+            if (hasCompleteKittyQueryResponse(responseBuffer)) {
                 cleanup();
                 if (!this.isUnmounted) {
                     this.enableKittyProtocol(flags);