@nuvin/ink 7.6.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;
@@ -166,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;
@@ -190,6 +138,21 @@ export default class Ink {
     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;
@@ -208,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;
@@ -234,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
@@ -265,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 = '';
@@ -288,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;
@@ -298,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();
@@ -317,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);
@@ -329,20 +347,45 @@ 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;
+        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);
@@ -431,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 : '', maxVisualWidth);
     };
     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);
@@ -453,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;
@@ -461,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);
@@ -485,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);
@@ -521,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
@@ -544,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');
                 }
@@ -554,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);
@@ -566,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
@@ -582,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);
@@ -594,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);
@@ -646,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.
@@ -653,17 +758,42 @@ 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;
         }
@@ -685,6 +815,9 @@ export default class Ink {
         });
     }
     getPhysicalEraseOptions() {
+        if (isOwnedSeekViewport(this.log.getPhysicalFrame?.())) {
+            return undefined;
+        }
         if (!this.options.stdout.isTTY ||
             !this.hasPhysicalFrame ||
             this.lastOutputToRender === '') {
@@ -747,9 +880,127 @@ export default class Ink {
         }
         return this.nextRenderCommit.promise;
     }
-    renderInteractiveFrame(output, outputHeight, staticOutput, maxVisualWidth) {
+    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.
@@ -795,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;
@@ -820,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) {
@@ -841,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;
@@ -857,6 +1113,284 @@ export default class Ink {
         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) {
@@ -882,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`);