@nuvin/ink 7.5.0-alpha → 7.7.0-alpha

package/build/ink.js

@@ -16,72 +16,19 @@ 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 { createExplicitWidthEncoder } from './explicit-width.js';
+import { ExplicitWidthDetection, canOverwriteFirstCell, } from './explicit-width-detection.js';
 import { bsu, esu, shouldSynchronize } from './write-synchronized.js';
+import { isOwnedSeekViewport, isSeekViewport, seekViewportReset, selectPaintStrategy, } from './terminal-paint.js';
 import instances from './instances.js';
 import { TextSelectionController } from './text-selection-controller.js';
 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, previousViewportRows, previousOutputHeight, nextOutputHeight, isUnmounting, }) => {
     if (!isTty) {
         return false;
@@ -116,7 +63,15 @@ const getReflowedLineCount = (output, columns) => {
         wordWrap: false,
     }).split('\n').length;
 };
-const isOutputSoftWrapped = (output, columns) => output !== '' && widestLine(output) > columns;
+const isOutputSoftWrapped = (output, columns, maxVisualWidth) => {
+    if (output === '') {
+        return false;
+    }
+    if (maxVisualWidth !== undefined) {
+        return maxVisualWidth > columns;
+    }
+    return widestLine(output) > columns;
+};
 const isErrorInput = (value) => {
     return (value instanceof Error ||
         Object.prototype.toString.call(value) === '[object Error]');
@@ -158,6 +113,7 @@ export default class Ink {
     // Ignore last render after unmounting a tree to prevent empty output before exit
     isUnmounted;
     isUnmounting;
+    outputError;
     lastOutput;
     lastOutputToRender;
     lastOutputHeight;
@@ -181,6 +137,22 @@ export default class Ink {
     cancelKittyDetection;
     nextRenderCommit;
     textSelection;
+    lastLayoutWidth;
+    lastLayoutRows;
+    pendingStaticOutput = '';
+    pendingHistoryAdvance = false;
+    transformOutput;
+    paintEligible = false;
+    paintCapability = 'raw';
+    widthDetection;
+    pendingFrame;
+    reservedFrame;
+    deferredWidthRenders = [];
+    deferredWidthLifecycleActions = [];
+    rawInputReady = false;
+    resumePendingInput;
+    kittyAutoFlags;
+    kittyQuerySent = false;
     constructor(options) {
         autoBind(this);
         this.options = options;
@@ -199,6 +171,41 @@ export default class Ink {
         // 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);
+        const explicitWidth = process.env['INK_EXPLICIT_WIDTH'];
+        const canUseExplicitWidth = options.explicitWidth !== 'disabled' &&
+            this.interactive &&
+            Boolean(options.stdout.isTTY) &&
+            !options.debug &&
+            !this.isScreenReaderEnabled;
+        this.paintEligible = canUseExplicitWidth && explicitWidth !== '0';
+        if (canUseExplicitWidth && explicitWidth === '1') {
+            this.transformOutput = createExplicitWidthEncoder();
+            this.paintCapability = 'osc66';
+        }
+        else if (canUseExplicitWidth &&
+            explicitWidth !== '0' &&
+            options.stdin.isTTY &&
+            options.stdin.readable &&
+            typeof options.stdin.setRawMode === 'function' &&
+            typeof options.stdin.ref === 'function' &&
+            typeof options.stdin.unref === 'function') {
+            this.widthDetection = new ExplicitWidthDetection({
+                getSize: () => getWindowSize(this.options.stdout),
+                write: text => {
+                    if (!getWritableStreamState(this.options.stdout)
+                        .canWriteToStdout) {
+                        throw new Error('Terminal output is unavailable');
+                    }
+                    this.options.stdout.write(text);
+                },
+                reserve: this.reserveExplicitWidthFrame,
+                onResult: this.settleExplicitWidth,
+            });
+            this.widthDetection.onSettled(this.finishExplicitWidthSettlement);
+        }
+        else if (this.paintEligible) {
+            this.paintCapability = 'fallback';
+        }
         this.alternateScreen = false;
         const unthrottled = options.debug || this.isScreenReaderEnabled;
         const maxFps = options.maxFps ?? 30;
@@ -225,27 +232,24 @@ export default class Ink {
         this.rootNode.onImmediateRender = this.onRender;
         this.log = logUpdate.create(options.stdout, {
             incremental: options.incrementalRendering,
+            transformOutput: this.widthDetection
+                ? this.encodeTerminalOutput
+                : this.transformOutput,
         });
         this.cursorPosition = undefined;
+        const writePaintRequest = (request) => {
+            this.writePaintRequest(request);
+        };
         this.throttledLog = unthrottled
-            ? this.log
-            : throttle((output) => {
-                const shouldWrite = this.log.willRender(output);
-                const sync = this.shouldSync();
-                if (sync && shouldWrite) {
-                    this.options.stdout.write(bsu);
-                }
-                this.log(output);
-                if (sync && shouldWrite) {
-                    this.options.stdout.write(esu);
-                }
-            }, undefined, {
+            ? writePaintRequest
+            : throttle(writePaintRequest, undefined, {
                 leading: true,
                 trailing: true,
             });
         // Ignore last render after unmounting a tree to prevent empty output before exit
         this.isUnmounted = false;
         this.isUnmounting = false;
+        this.outputError = undefined;
         // Store concurrent mode setting
         this.isConcurrent = options.concurrent ?? false;
         // Store last output to only rerender when needed
@@ -256,6 +260,7 @@ export default class Ink {
         this.lastPhysicalFrameWasSoftWrapped = false;
         this.lastViewportRows = getWindowSize(this.options.stdout).rows;
         this.lastTerminalWidth = getWindowSize(this.options.stdout).columns;
+        this.lastLayoutRows = this.lastViewportRows;
         // 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 = '';
@@ -279,6 +284,7 @@ export default class Ink {
                 options.stdout.off('resize', this.resized);
             };
         }
+        options.stdout.on('error', this.handleStdoutError);
         this.initKittyKeyboard();
         this.exitPromise = new Promise((resolve, reject) => {
             this.resolveExitPromise = resolve;
@@ -289,6 +295,9 @@ export default class Ink {
         void this.exitPromise.catch(noop);
     }
     resized = () => {
+        if (this.deferUntilExplicitWidthSettlement(this.resized))
+            return;
+        settleThrottle(this.throttledLog, false);
         const currentWidth = getWindowSize(this.options.stdout).columns;
         this.calculateLayout();
         this.onRender();
@@ -308,6 +317,24 @@ export default class Ink {
         this.exitResult = errorOrResult;
         this.unmount();
     };
+    handleStdoutError = (error) => {
+        this.surfaceOutputError(error);
+    };
+    surfaceOutputError(error) {
+        this.log.restoreTerminalModes();
+        this.hasPhysicalFrame = false;
+        this.pendingHistoryAdvance = false;
+        const err = isErrorInput(error)
+            ? error
+            : new Error('Terminal output failed');
+        if (!this.outputError) {
+            this.outputError = err;
+        }
+        if (this.isUnmounted || this.isUnmounting) {
+            return;
+        }
+        this.unmount(err);
+    }
     setCursorPosition = (position) => {
         this.cursorPosition = position;
         this.log.setCursorPosition(position);
@@ -320,16 +347,49 @@ export default class Ink {
         // before restoring output after external stdout/stderr writes.
         this.log.setCursorPosition(this.cursorPosition);
         const outputToRestore = this.lastOutputToRender || this.lastOutput + '\n';
+        const size = getWindowSize(this.options.stdout);
+        const layoutStale = this.lastLayoutWidth !== size.columns ||
+            this.lastLayoutRows !== size.rows;
+        const context = this.getSeekPaintContext({
+            output: this.lastOutput,
+            outputHeight: this.lastOutputHeight,
+            staticOutput: '',
+            layoutColumns: this.lastLayoutWidth ?? size.columns,
+            layoutRows: this.lastLayoutRows ?? size.rows,
+        });
+        if (layoutStale && (context || this.pendingHistoryAdvance)) {
+            this.consumeHistoryAdvance(size.rows);
+            this.scheduleLayoutRender();
+            return;
+        }
+        if (context) {
+            this.consumeHistoryAdvance(context.rows);
+            this.log(outputToRestore, context);
+            const physical = this.log.getPhysicalFrame();
+            this.hasPhysicalFrame = Boolean(physical?.valid);
+            this.lastPhysicalFrameWasSoftWrapped = false;
+            return;
+        }
+        this.pendingHistoryAdvance = false;
         this.log(outputToRestore);
         this.hasPhysicalFrame = true;
         this.lastPhysicalFrameWasSoftWrapped =
             Boolean(this.options.stdout.isTTY) &&
-                isOutputSoftWrapped(outputToRestore, getWindowSize(this.options.stdout).columns);
+                isOutputSoftWrapped(outputToRestore, size.columns);
     };
     calculateLayout = () => {
-        const terminalWidth = getWindowSize(this.options.stdout).columns;
-        this.rootNode.yogaNode.setWidth(terminalWidth);
-        this.rootNode.yogaNode.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
+        const { columns: terminalWidth, rows: terminalRows } = getWindowSize(this.options.stdout);
+        const yoga = this.rootNode.yogaNode;
+        const widthChanged = this.lastLayoutWidth !== terminalWidth;
+        if (widthChanged) {
+            yoga.setWidth(terminalWidth);
+            this.lastLayoutWidth = terminalWidth;
+        }
+        this.lastLayoutRows = terminalRows;
+        if (!widthChanged && !yoga.isDirty())
+            return;
+        yoga.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
+        dom.incrementLayoutEpoch(this.rootNode);
     };
     onRender = () => {
         this.hasPendingThrottledRender = false;
@@ -341,7 +401,7 @@ export default class Ink {
             this.nextRenderCommit = undefined;
         }
         const startTime = performance.now();
-        const { output, outputHeight, staticOutput } = render(this.rootNode, this.isScreenReaderEnabled, 
+        const { output, outputHeight, staticOutput, maxVisualWidth } = render(this.rootNode, this.isScreenReaderEnabled, 
         // Screen-reader rendering bypasses Output, so selection is skipped.
         this.isScreenReaderEnabled ? undefined : this.textSelection);
         this.options.onRender?.({
@@ -414,14 +474,52 @@ export default class Ink {
             }
             return;
         }
-        if (hasStaticOutput) {
-            this.fullStaticOutput += staticOutput;
+        const size = getWindowSize(this.options.stdout);
+        const frame = {
+            output,
+            outputHeight,
+            staticOutput: hasStaticOutput ? staticOutput : '',
+            maxVisualWidth,
+            layoutColumns: this.lastLayoutWidth ?? size.columns,
+            layoutRows: this.lastLayoutRows ?? size.rows,
+        };
+        if (this.widthDetection && !this.widthDetection.settled) {
+            this.pendingFrame = {
+                ...frame,
+                staticOutput: (this.pendingFrame?.staticOutput ?? '') + frame.staticOutput,
+            };
+            if (!this.widthDetection.pending &&
+                !frame.output &&
+                !frame.staticOutput) {
+                // No physical frame exists yet; keep the first nonempty frame eligible.
+                return;
+            }
+            else {
+                this.widthDetection.start();
+            }
+            return;
+        }
+        try {
+            this.commitInteractiveFrame(frame);
+        }
+        catch (error) {
+            this.surfaceOutputError(error);
         }
-        this.renderInteractiveFrame(output, outputHeight, hasStaticOutput ? staticOutput : '');
     };
     render(node) {
+        if (this.widthDetection?.publicationBlocked) {
+            this.deferredWidthRenders.push(node);
+            this.widthDetection.cancel();
+            return;
+        }
         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, interactive: this.interactive, renderThrottleMs: this.renderThrottleMs, writeToStdout: this.writeToStdout, writeToStderr: this.writeToStderr, setCursorPosition: this.setCursorPosition, textSelection: this.textSelection, onExit: this.handleAppExit, onWaitUntilRenderFlush: this.waitUntilRenderFlush }, 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, textSelection: this.textSelection, onExit: this.handleAppExit, onWaitUntilRenderFlush: this.waitUntilRenderFlush, onTerminalResponse: this.widthDetection || this.kittyAutoFlags
+                    ? this.handleTerminalResponse
+                    : undefined, isTerminalResponsePending: this.widthDetection || this.kittyAutoFlags
+                    ? this.isTerminalResponsePending
+                    : undefined, onInputReady: this.widthDetection || this.kittyAutoFlags
+                    ? this.handleInputReady
+                    : undefined }, node)));
         if (this.options.concurrent) {
             // Concurrent mode: use updateContainer (async scheduling)
             reconciler.updateContainer(tree, this.container, null, noop);
@@ -436,6 +534,8 @@ export default class Ink {
         if (this.isUnmounted) {
             return;
         }
+        if (this.deferUntilExplicitWidthSettlement(() => this.writeToStdout(data)))
+            return;
         if (this.options.debug) {
             this.options.stdout.write(data + this.fullStaticOutput + this.lastOutput);
             return;
@@ -444,21 +544,14 @@ export default class Ink {
             this.options.stdout.write(data);
             return;
         }
-        const sync = this.shouldSync();
-        if (sync) {
-            this.options.stdout.write(bsu);
-        }
-        this.log.clear(this.getPhysicalEraseOptions());
-        this.options.stdout.write(data);
-        this.restoreLastOutput();
-        if (sync) {
-            this.options.stdout.write(esu);
-        }
+        this.writeExternalOutput(data, this.options.stdout);
     }
     writeToStderr(data) {
         if (this.isUnmounted) {
             return;
         }
+        if (this.deferUntilExplicitWidthSettlement(() => this.writeToStderr(data)))
+            return;
         if (this.options.debug) {
             this.options.stderr.write(data);
             this.options.stdout.write(this.fullStaticOutput + this.lastOutput);
@@ -468,22 +561,15 @@ export default class Ink {
             this.options.stderr.write(data);
             return;
         }
-        const sync = this.shouldSync();
-        if (sync) {
-            this.options.stdout.write(bsu);
-        }
-        this.log.clear(this.getPhysicalEraseOptions());
-        this.options.stderr.write(data);
-        this.restoreLastOutput();
-        if (sync) {
-            this.options.stdout.write(esu);
-        }
+        this.writeExternalOutput(data, this.options.stderr);
     }
     // eslint-disable-next-line @typescript-eslint/no-restricted-types
     unmount(error) {
         if (this.isUnmounted || this.isUnmounting) {
             return;
         }
+        if (this.deferUntilExplicitWidthSettlement(() => this.unmount(error)))
+            return;
         this.isUnmounting = true;
         if (this.beforeExitHandler) {
             process.off('beforeExit', this.beforeExitHandler);
@@ -504,14 +590,16 @@ export default class Ink {
                 this.calculateLayout();
                 this.onRender();
             }
+            // Accept pending paints from the controlled final render before locking.
+            settleThrottle(this.throttledLog, true);
         }
         // 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);
+        // Cancel leftover throttled log writes so no new frame starts after unmount.
+        settleThrottle(this.throttledLog, false);
+        this.log.restoreTerminalModes();
         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
@@ -527,7 +615,12 @@ export default class Ink {
             if (this.cancelKittyDetection) {
                 this.cancelKittyDetection();
             }
+            this.log.restoreTerminalModes();
+            const seekTeardown = this.log.getPhysicalFrame?.()?.context.strategy === 'seek-viewport';
             if (canWriteToStdout) {
+                if (this.interactive && !this.options.debug && seekTeardown) {
+                    this.log.done();
+                }
                 if (this.kittyProtocolEnabled) {
                     this.writeBestEffort(this.options.stdout, '\u001B[<u');
                 }
@@ -537,6 +630,9 @@ export default class Ink {
                 // 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.
+                // Seek cursor/cache teardown must finish before this screen switch:
+                // after the switch, no seek done() path may reposition or erase the
+                // returned primary screen.
                 if (this.alternateScreen) {
                     this.writeBestEffort(this.options.stdout, ansiEscapes.exitAlternativeScreen);
                     this.writeBestEffort(this.options.stdout, showCursorEscape);
@@ -549,10 +645,16 @@ export default class Ink {
                     // deferred during rendering).
                     this.options.stdout.write(this.options.debug ? '\n' : this.lastOutput + '\n');
                 }
-                else if (!this.options.debug) {
+                else if (!this.options.debug && !seekTeardown) {
                     this.log.done();
                 }
             }
+            else if (this.interactive && !this.options.debug) {
+                try {
+                    this.log.done();
+                }
+                catch { }
+            }
             this.kittyProtocolEnabled = false;
             instances.delete(this.options.stdout);
             // Ensure all queued writes have been processed before resolving the
@@ -565,8 +667,10 @@ export default class Ink {
             // because the event loop is draining and async callbacks won't fire.
             const { exitResult } = this;
             const resolveOrReject = () => {
-                if (isErrorInput(error)) {
-                    this.rejectExitPromise(error);
+                this.options.stdout.off('error', this.handleStdoutError);
+                const exitError = isErrorInput(error) ? error : this.outputError;
+                if (exitError) {
+                    this.rejectExitPromise(exitError);
                 }
                 else {
                     this.resolveExitPromise(exitResult);
@@ -577,7 +681,17 @@ export default class Ink {
                 resolveOrReject();
             }
             else if (canWriteToStdout && hasWritableState) {
-                this.options.stdout.write('', resolveOrReject);
+                try {
+                    this.options.stdout.write('', errorFromBarrier => {
+                        if (errorFromBarrier && !this.outputError) {
+                            this.outputError = errorFromBarrier;
+                        }
+                        resolveOrReject();
+                    });
+                }
+                catch {
+                    resolveOrReject();
+                }
             }
             else {
                 setImmediate(resolveOrReject);
@@ -629,6 +743,14 @@ export default class Ink {
             }
         }
         reconciler.flushSyncWork();
+        settleThrottle(this.throttledOnRender, getWritableStreamState(this.options.stdout)
+            .canWriteToStdout);
+        if (this.widthDetection?.pending)
+            await this.widthDetection.finished;
+        if (this.isUnmounted || this.isUnmounting) {
+            await this.awaitExit();
+            return;
+        }
         const stdout = this.options.stdout;
         const { canWriteToStdout, hasWritableState } = getWritableStreamState(stdout);
         // Flush pending throttled render/log timers so their output is included in this wait.
@@ -636,35 +758,46 @@ export default class Ink {
         settleThrottle(this.throttledLog, canWriteToStdout);
         if (canWriteToStdout && hasWritableState) {
             await new Promise(resolve => {
-                this.options.stdout.write('', () => {
+                let settled = false;
+                const finish = (writeError) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    this.options.stdout.off('error', onError);
+                    if (writeError) {
+                        this.surfaceOutputError(writeError);
+                    }
                     resolve();
-                });
+                };
+                const onError = (writeError) => {
+                    finish(writeError);
+                };
+                this.options.stdout.once('error', onError);
+                try {
+                    this.options.stdout.write('', writeError => {
+                        finish(writeError);
+                    });
+                }
+                catch (writeError) {
+                    finish(isErrorInput(writeError)
+                        ? writeError
+                        : new Error('Terminal output failed'));
+                }
             });
             return;
         }
         await yieldImmediate();
     }
     clear() {
+        if (this.deferUntilExplicitWidthSettlement(this.clear))
+            return;
         if (this.interactive && !this.options.debug) {
-            this.log.clear(this.getPhysicalEraseOptions());
+            this.clearPhysicalFrame();
             this.hasPhysicalFrame = false;
             this.lastPhysicalFrameWasSoftWrapped = false;
         }
     }
-    getPhysicalEraseOptions() {
-        if (!this.options.stdout.isTTY ||
-            !this.hasPhysicalFrame ||
-            this.lastOutputToRender === '') {
-            return undefined;
-        }
-        const terminalWidth = getWindowSize(this.options.stdout).columns;
-        if (!isOutputSoftWrapped(this.lastOutputToRender, terminalWidth)) {
-            return undefined;
-        }
-        return {
-            eraseLineCount: getReflowedLineCount(this.lastOutputToRender, terminalWidth),
-        };
-    }
     patchConsole() {
         if (this.options.debug) {
             return;
@@ -681,6 +814,23 @@ export default class Ink {
             }
         });
     }
+    getPhysicalEraseOptions() {
+        if (isOwnedSeekViewport(this.log.getPhysicalFrame?.())) {
+            return undefined;
+        }
+        if (!this.options.stdout.isTTY ||
+            !this.hasPhysicalFrame ||
+            this.lastOutputToRender === '') {
+            return undefined;
+        }
+        const terminalWidth = getWindowSize(this.options.stdout).columns;
+        if (!isOutputSoftWrapped(this.lastOutputToRender, terminalWidth)) {
+            return undefined;
+        }
+        return {
+            eraseLineCount: getReflowedLineCount(this.lastOutputToRender, terminalWidth),
+        };
+    }
     setAlternateScreen(enabled) {
         this.alternateScreen = this.resolveAlternateScreenOption(enabled, this.interactive);
         if (this.alternateScreen) {
@@ -730,9 +880,127 @@ export default class Ink {
         }
         return this.nextRenderCommit.promise;
     }
-    renderInteractiveFrame(output, outputHeight, staticOutput) {
+    renderInteractiveFrame(output, outputHeight, staticOutput, maxVisualWidth, layoutColumns, layoutRows) {
+        const size = getWindowSize(this.options.stdout);
+        this.renderPendingFrame({
+            output,
+            outputHeight,
+            staticOutput,
+            maxVisualWidth,
+            layoutColumns: layoutColumns ?? this.lastLayoutWidth ?? size.columns,
+            layoutRows: layoutRows ?? this.lastLayoutRows ?? size.rows,
+        });
+    }
+    renderPendingFrame(frame) {
+        const { columns: terminalWidth, rows: terminalRows } = getWindowSize(this.options.stdout);
+        if (frame.layoutColumns !== terminalWidth ||
+            frame.layoutRows !== terminalRows) {
+            this.deferStatic(frame);
+            this.scheduleLayoutRender();
+            return;
+        }
+        const previousPhysical = this.log.getPhysicalFrame?.();
+        const previousSeek = isOwnedSeekViewport(previousPhysical);
+        const seekContext = this.getSeekPaintContext(frame);
+        if (previousSeek &&
+            !seekContext &&
+            frame.outputHeight === previousPhysical.context.rows) {
+            this.deferStatic(frame);
+            return;
+        }
+        if (previousSeek || seekContext) {
+            this.renderSeekFrame(frame, seekContext, previousSeek);
+            return;
+        }
+        this.renderRawInteractiveFrame(frame);
+    }
+    renderSeekFrame(frame, seekContext, previousSeek) {
+        const isTty = this.options.stdout.isTTY;
+        const { rows: terminalRows } = getWindowSize(this.options.stdout);
+        const viewportRows = isTty ? terminalRows : 24;
+        const isFullscreen = isTty && frame.outputHeight >= viewportRows;
+        const outputToRender = isFullscreen ? frame.output : frame.output + '\n';
+        if (!seekContext) {
+            this.leaveSeekViewport();
+            this.renderRawInteractiveFrame(frame);
+            return;
+        }
+        const context = seekContext;
+        const staticOutput = this.takeStaticOutput(frame);
+        const previousPhysical = this.log.getPhysicalFrame?.();
+        const dimensionsChanged = !previousPhysical?.valid ||
+            previousPhysical.context.columns !== context.columns ||
+            previousPhysical.context.rows !== context.rows ||
+            previousPhysical.context.strategy !== context.strategy;
+        const entering = !previousSeek;
+        if (staticOutput !== '') {
+            const sync = this.shouldSync();
+            if (sync) {
+                this.options.stdout.write(bsu);
+            }
+            try {
+                this.clearPhysicalFrame();
+                this.hasPhysicalFrame = false;
+                this.options.stdout.write(this.transformOutput?.(staticOutput) ?? staticOutput);
+                this.pendingHistoryAdvance = true;
+                this.consumeHistoryAdvance(context.rows);
+                this.log(outputToRender, context);
+            }
+            catch (error) {
+                this.failExternalOutput(error);
+            }
+            finally {
+                if (sync) {
+                    try {
+                        this.options.stdout.write(esu);
+                    }
+                    catch { }
+                }
+            }
+            this.publishLogicalFrame(frame, outputToRender, true);
+            return;
+        }
+        if (entering || dimensionsChanged) {
+            const sync = this.shouldSync();
+            if (sync) {
+                this.options.stdout.write(bsu);
+            }
+            try {
+                if (this.pendingHistoryAdvance) {
+                    this.consumeHistoryAdvance(context.rows);
+                }
+                else {
+                    this.options.stdout.write(seekViewportReset);
+                    this.log.reset();
+                }
+                this.log.repaint(outputToRender, undefined, context);
+            }
+            finally {
+                if (sync) {
+                    try {
+                        this.options.stdout.write(esu);
+                    }
+                    catch { }
+                }
+            }
+            this.publishLogicalFrame(frame, outputToRender, true);
+            return;
+        }
+        if (outputToRender !== this.lastOutputToRender ||
+            this.log.isCursorDirty()) {
+            this.throttledLog({
+                frame,
+                outputToRender,
+            });
+            return;
+        }
+        this.publishLogicalFrame(frame, outputToRender, false);
+    }
+    renderRawInteractiveFrame(frame) {
+        const staticOutput = this.takeStaticOutput(frame);
         const hasStaticOutput = staticOutput !== '';
         const isTty = this.options.stdout.isTTY;
+        const { output, outputHeight, maxVisualWidth } = frame;
         const { columns: terminalWidth, rows: terminalRows } = getWindowSize(this.options.stdout);
         // Detect fullscreen: output fills or exceeds terminal height.
         // Only apply when writing to a real TTY — piped output always gets trailing newlines.
@@ -746,7 +1014,7 @@ export default class Ink {
         const outputWillRender = hasStaticOutput || this.log.willRender(outputToRender);
         const shouldClassifyNextFrame = Boolean(isTty) && (columnsDecreased || outputWillRender);
         const nextFrameIsSoftWrapped = shouldClassifyNextFrame &&
-            isOutputSoftWrapped(outputToRender, terminalWidth);
+            isOutputSoftWrapped(outputToRender, terminalWidth, maxVisualWidth);
         const shouldRepairReflow = Boolean(isTty) &&
             hasCachedPhysicalOutput &&
             (columnsDecreased ||
@@ -778,7 +1046,9 @@ export default class Ink {
             if (sync) {
                 this.options.stdout.write(bsu);
             }
-            this.options.stdout.write(ansiEscapes.clearTerminal + this.fullStaticOutput + outputToRender);
+            const content = this.fullStaticOutput + outputToRender;
+            this.options.stdout.write(ansiEscapes.clearTerminal +
+                (this.transformOutput?.(content) ?? content));
             this.lastOutput = output;
             this.lastOutputToRender = outputToRender;
             this.lastOutputHeight = outputHeight;
@@ -788,7 +1058,8 @@ export default class Ink {
             this.hasPhysicalFrame = true;
             this.lastPhysicalFrameWasSoftWrapped = shouldClassifyNextFrame
                 ? nextFrameIsSoftWrapped
-                : Boolean(isTty) && isOutputSoftWrapped(outputToRender, terminalWidth);
+                : Boolean(isTty) &&
+                    isOutputSoftWrapped(outputToRender, terminalWidth, maxVisualWidth);
             if (sync) {
                 this.options.stdout.write(esu);
             }
@@ -802,7 +1073,7 @@ export default class Ink {
                 this.options.stdout.write(bsu);
             }
             this.log.clear(reflowEraseOptions);
-            this.options.stdout.write(staticOutput);
+            this.options.stdout.write(this.transformOutput?.(staticOutput) ?? staticOutput);
             this.log(outputToRender);
             didWriteFrame = true;
             if (sync) {
@@ -823,7 +1094,10 @@ export default class Ink {
         else if (outputToRender !== this.lastOutputToRender ||
             this.log.isCursorDirty()) {
             // ThrottledLog manages its own bsu/esu at actual write time
-            this.throttledLog(outputToRender);
+            this.throttledLog({
+                frame,
+                outputToRender,
+            });
             didWriteFrame = true;
         }
         this.lastOutput = output;
@@ -833,11 +1107,290 @@ export default class Ink {
         if (didWriteFrame) {
             this.lastPhysicalFrameWasSoftWrapped = shouldClassifyNextFrame
                 ? nextFrameIsSoftWrapped
-                : Boolean(isTty) && isOutputSoftWrapped(outputToRender, terminalWidth);
+                : Boolean(isTty) &&
+                    isOutputSoftWrapped(outputToRender, terminalWidth, maxVisualWidth);
         }
         this.lastViewportRows = viewportRows;
         this.lastTerminalWidth = terminalWidth;
     }
+    encodeTerminalOutput(output) {
+        return this.transformOutput?.(output) ?? output;
+    }
+    commitInteractiveFrame(frame) {
+        this.renderInteractiveFrame(frame.output, frame.outputHeight, frame.staticOutput, frame.maxVisualWidth, frame.layoutColumns, frame.layoutRows);
+    }
+    resolvePaintContext(frame) {
+        const { columns, rows } = getWindowSize(this.options.stdout);
+        return {
+            strategy: selectPaintStrategy({
+                eligible: this.paintEligible,
+                capability: this.paintCapability,
+                incremental: Boolean(this.options.incrementalRendering),
+                outputHeight: frame.outputHeight,
+                rows,
+            }),
+            columns,
+            rows,
+        };
+    }
+    getSeekPaintContext(frame) {
+        const context = this.resolvePaintContext(frame);
+        if (!isSeekViewport(context)) {
+            return undefined;
+        }
+        const { rows } = getWindowSize(this.options.stdout);
+        if (frame.outputHeight !== rows || context.rows !== rows) {
+            return undefined;
+        }
+        return context;
+    }
+    clearPhysicalFrame() {
+        const physical = this.log.getPhysicalFrame?.();
+        if (isOwnedSeekViewport(physical)) {
+            this.log.clear();
+            return;
+        }
+        this.log.clear(this.getPhysicalEraseOptions());
+    }
+    leaveSeekViewport() {
+        this.clearPhysicalFrame();
+        this.log.restoreTerminalModes();
+        this.log.reset();
+        this.hasPhysicalFrame = false;
+        this.lastPhysicalFrameWasSoftWrapped = false;
+    }
+    consumeHistoryAdvance(rows) {
+        if (!this.pendingHistoryAdvance) {
+            return;
+        }
+        this.pendingHistoryAdvance = false;
+        if (rows > 0) {
+            this.options.stdout.write('\r\n'.repeat(rows) + '\u001B[H');
+        }
+    }
+    failExternalOutput(error) {
+        this.log.restoreTerminalModes();
+        this.hasPhysicalFrame = false;
+        this.pendingHistoryAdvance = false;
+        throw error;
+    }
+    writeExternalOutput(data, stream) {
+        const sync = this.shouldSync();
+        if (sync) {
+            this.options.stdout.write(bsu);
+        }
+        try {
+            const ownedSeek = isOwnedSeekViewport(this.log.getPhysicalFrame?.());
+            const size = getWindowSize(this.options.stdout);
+            const willSeek = Boolean(this.getSeekPaintContext({
+                output: this.lastOutput,
+                outputHeight: this.lastOutputHeight,
+                staticOutput: '',
+                layoutColumns: this.lastLayoutWidth ?? size.columns,
+                layoutRows: this.lastLayoutRows ?? size.rows,
+            }));
+            this.clearPhysicalFrame();
+            this.hasPhysicalFrame = false;
+            stream.write(data);
+            if (ownedSeek || willSeek) {
+                this.pendingHistoryAdvance = true;
+            }
+            this.restoreLastOutput();
+        }
+        catch (error) {
+            this.failExternalOutput(error);
+        }
+        finally {
+            if (sync) {
+                try {
+                    this.options.stdout.write(esu);
+                }
+                catch { }
+            }
+        }
+    }
+    writePaintRequest(request) {
+        if (this.isUnmounted) {
+            return;
+        }
+        try {
+            const { columns, rows } = getWindowSize(this.options.stdout);
+            if (request.frame.layoutColumns !== columns ||
+                request.frame.layoutRows !== rows) {
+                this.deferStatic(request.frame);
+                this.scheduleLayoutRender();
+                return;
+            }
+            const previousPhysical = this.log.getPhysicalFrame?.();
+            const seekContext = this.getSeekPaintContext(request.frame);
+            if (seekContext === undefined &&
+                isOwnedSeekViewport(previousPhysical) &&
+                request.frame.outputHeight === previousPhysical.context.rows) {
+                this.deferStatic(request.frame);
+                return;
+            }
+            const shouldWrite = this.log.willRender(request.outputToRender, seekContext);
+            const sync = this.shouldSync();
+            if (sync && shouldWrite) {
+                this.options.stdout.write(bsu);
+            }
+            try {
+                this.log(request.outputToRender, seekContext);
+            }
+            finally {
+                if (sync && shouldWrite) {
+                    try {
+                        this.options.stdout.write(esu);
+                    }
+                    catch { }
+                }
+            }
+            this.publishLogicalFrame(request.frame, request.outputToRender, shouldWrite);
+        }
+        catch (error) {
+            this.surfaceOutputError(error);
+        }
+    }
+    publishLogicalFrame(frame, outputToRender, didWrite) {
+        this.lastOutput = frame.output;
+        this.lastOutputToRender = outputToRender;
+        this.lastOutputHeight = frame.outputHeight;
+        const size = getWindowSize(this.options.stdout);
+        this.lastViewportRows = size.rows;
+        this.lastTerminalWidth = size.columns;
+        const physical = this.log.getPhysicalFrame?.();
+        if (isOwnedSeekViewport(physical)) {
+            this.hasPhysicalFrame = true;
+            this.lastPhysicalFrameWasSoftWrapped = false;
+            return;
+        }
+        this.hasPhysicalFrame ||= didWrite;
+    }
+    takeStaticOutput(frame) {
+        const staticOutput = (this.pendingStaticOutput ?? '') + frame.staticOutput;
+        this.pendingStaticOutput = '';
+        this.fullStaticOutput = (this.fullStaticOutput ?? '') + staticOutput;
+        return staticOutput;
+    }
+    deferStatic(frame) {
+        this.pendingStaticOutput =
+            (this.pendingStaticOutput ?? '') + frame.staticOutput;
+    }
+    scheduleLayoutRender() {
+        if (this.isUnmounted) {
+            return;
+        }
+        this.calculateLayout();
+        this.onRender();
+    }
+    reserveExplicitWidthFrame() {
+        const frame = this.pendingFrame;
+        if (!frame || !canOverwriteFirstCell(frame.staticOutput || frame.output))
+            return false;
+        this.reservedFrame = frame;
+        this.pendingFrame = undefined;
+        return true;
+    }
+    settleExplicitWidth(supported) {
+        const reserved = this.reservedFrame;
+        this.reservedFrame = undefined;
+        if (!this.isUnmounted &&
+            this.paintEligible &&
+            this.paintCapability === 'raw') {
+            if (supported) {
+                this.transformOutput = createExplicitWidthEncoder();
+                this.paintCapability = 'osc66';
+            }
+            else {
+                this.paintCapability = 'fallback';
+            }
+        }
+        try {
+            if (this.isUnmounted ||
+                !getWritableStreamState(this.options.stdout)
+                    .canWriteToStdout)
+                return;
+            if (reserved)
+                this.commitInteractiveFrame(reserved);
+            while (true) {
+                settleThrottle(this.throttledOnRender, true);
+                if (!this.pendingFrame)
+                    break;
+                const pending = this.pendingFrame;
+                this.pendingFrame = undefined;
+                this.commitInteractiveFrame(pending);
+            }
+        }
+        finally {
+            this.pendingFrame = undefined;
+        }
+    }
+    deferUntilExplicitWidthSettlement(action) {
+        const detection = this.widthDetection;
+        if (!detection || detection.settled)
+            return false;
+        this.deferredWidthLifecycleActions.push(action);
+        detection.cancel();
+        return true;
+    }
+    finishExplicitWidthSettlement() {
+        this.resumePendingInput?.();
+        for (const node of this.deferredWidthRenders.splice(0))
+            this.render(node);
+        const canWriteToStdout = getWritableStreamState(this.options.stdout).canWriteToStdout;
+        settleThrottle(this.throttledOnRender, canWriteToStdout);
+        settleThrottle(this.throttledLog, canWriteToStdout);
+        for (const action of this.deferredWidthLifecycleActions.splice(0)) {
+            settleThrottle(this.throttledLog, canWriteToStdout);
+            action();
+        }
+    }
+    isTerminalResponsePending() {
+        return Boolean(this.widthDetection?.pending || this.cancelKittyDetection);
+    }
+    handleInputReady(ready, resumePendingInput, afterSettlement) {
+        this.rawInputReady = ready;
+        if (!ready) {
+            const finishInputRelease = () => {
+                this.cancelKittyDetection?.();
+                this.resumePendingInput = undefined;
+                afterSettlement?.();
+            };
+            if (this.deferUntilExplicitWidthSettlement(finishInputRelease))
+                return;
+            finishInputRelease();
+            return;
+        }
+        if (this.isUnmounted || this.isUnmounting)
+            return;
+        this.resumePendingInput = resumePendingInput;
+        this.widthDetection?.setInputReady(true);
+        if (this.kittyAutoFlags &&
+            !this.kittyQuerySent &&
+            this.cancelKittyDetection) {
+            this.kittyQuerySent = true;
+            try {
+                this.options.stdout.write('\u001B[?u');
+            }
+            catch {
+                this.cancelKittyDetection?.();
+            }
+        }
+    }
+    handleTerminalResponse(response) {
+        if (response.type === 'cursor-position') {
+            this.widthDetection?.accept(response);
+            return;
+        }
+        if (this.kittyQuerySent &&
+            this.kittyAutoFlags &&
+            this.cancelKittyDetection) {
+            const flags = this.kittyAutoFlags;
+            this.cancelKittyDetection();
+            if (!this.isUnmounted && !this.isUnmounting)
+                this.enableKittyProtocol(flags);
+        }
+    }
     initKittyKeyboard() {
         // Protocol is opt-in: if kittyKeyboard is not specified, do nothing
         if (!this.options.kittyKeyboard) {
@@ -863,46 +1416,20 @@ export default class Ink {
             !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 = [];
+        if (this.options.debug || this.isScreenReaderEnabled)
+            return;
+        // Replies flow through App's one readable parser, without input replay.
+        this.kittyAutoFlags = flags;
         const cleanup = () => {
-            this.cancelKittyDetection = undefined;
             clearTimeout(timer);
-            stdin.removeListener('data', onData);
-            // 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.
-            const remaining = stripKittyQueryResponsesAndTrailingPartial(responseBuffer);
-            responseBuffer = [];
-            if (remaining.length > 0) {
-                stdin.unshift(Uint8Array.from(remaining));
-            }
-        };
-        const onData = (data) => {
-            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);
-                }
-            }
+            this.cancelKittyDetection = undefined;
+            this.kittyAutoFlags = undefined;
+            this.resumePendingInput?.();
         };
-        // Attach listener before writing the query so that synchronous
-        // or immediate responses are not missed.
-        stdin.on('data', onData);
         const timer = setTimeout(cleanup, 200);
         this.cancelKittyDetection = cleanup;
-        stdout.write('\u001B[?u');
+        if (this.rawInputReady)
+            this.handleInputReady(true, this.resumePendingInput);
     }
     enableKittyProtocol(flags) {
         this.options.stdout.write(`\u001B[>${resolveFlags(flags)}u`);