@deepseek-harness-tui/dsh-tui 0.8.7 → 0.9.0

package/lib/types/ink/ink.js

@@ -12,12 +12,14 @@ import { logError } from '../utils/log.js';
 import { format } from 'util';
 import { colorize } from './colorize.js';
 import App from './components/App.js';
-import { FRAME_INTERVAL_MS } from './constants.js';
+import { FRAME_INTERVAL_MS, PTY_BACKLOG_BYTES } from './constants.js';
 import * as dom from './dom.js';
+import { beginGeometryFrame, endGeometryFrame, GEOMETRY_TRACE_ENABLED, noteFrameCause } from './geometry-trace.js';
 import { KeyboardEvent } from './events/keyboard-event.js';
 import { FocusManager } from './focus.js';
 import { emptyFrame } from './frame.js';
-import { dispatchClick, dispatchHover } from './hit-test.js';
+import { dispatchClick, dispatchHover, dispatchWheel, clearHovered } from './hit-test.js';
+import { logMouseDebug } from '../utils/debug.js';
 import instances from './instances.js';
 import { suppressInputFor } from './input-suppression.js';
 import { LogUpdate } from './log-update.js';
@@ -30,11 +32,12 @@ import { applyPositionedHighlight, scanPositions } from './render-to-screen.js';
 import createRenderer from './renderer.js';
 import { CharPool, cellAt, createScreen, HyperlinkPool, isEmptyCellAt, migrateScreenPools, StylePool } from './screen.js';
 import { applySearchHighlight } from './searchHighlight.js';
-import { applySelectionOverlay, captureScrolledRows, clearSelection, createSelectionState, extendSelection, findPlainTextUrlAt, getSelectedText, hasSelection, moveFocus, selectLineAt, selectWordAt, shiftAnchor, shiftSelection, shiftSelectionForFollow, startSelection, updateSelection } from './selection.js';
+import { applySelectionOverlay, captureScrolledRows, clearSelection, createSelectionState, extendSelection, findPlainTextUrlAt, getSelectedText, hasSelection, moveFocus, pickFollowForSelection, selectLineAt, selectWordAt, shiftAnchor, shiftSelection, shiftSelectionForFollow, startSelection, updateSelection } from './selection.js';
 import { isDecstbmSafe, SYNC_OUTPUT_SUPPORTED, supportsExtendedKeys, supportsWin32InputMode, writeDiffToTerminal } from './terminal.js';
 import { CURSOR_HOME, cursorMove, cursorPosition, DISABLE_KITTY_KEYBOARD, DISABLE_MODIFY_OTHER_KEYS, DISABLE_WIN32_INPUT_MODE, ENABLE_KITTY_KEYBOARD, ENABLE_MODIFY_OTHER_KEYS, ENABLE_WIN32_INPUT_MODE, ERASE_SCREEN, ERASE_SCROLLBACK, SGR_RESET } from './termio/csi.js';
 import { DBP, DFE, DISABLE_MOUSE_TRACKING, ENABLE_MOUSE_TRACKING, ENTER_ALT_SCREEN, EXIT_ALT_SCREEN, SHOW_CURSOR } from './termio/dec.js';
 import { CLEAR_ITERM2_PROGRESS, CLEAR_TAB_STATUS, setClipboard, supportsTabStatus, wrapForMultiplexer } from './termio/osc.js';
+import { decrqm } from './terminal-querier.js';
 import { TerminalWriteProvider } from './useTerminalNotification.js';
 // Alt-screen: renderer.ts sets cursor.visible = !isTTY || screen.height===0,
 // which is always false in alt-screen (TTY + content fills screen).
@@ -310,9 +313,31 @@ export default class Ink {
         // frame resets and renders.
         if (cols === this.terminalColumns && rows === this.terminalRows)
             return;
+        noteFrameCause('resize');
         this.terminalColumns = cols;
         this.terminalRows = rows;
         this.altScreenParkPatch = makeAltScreenParkPatch(this.terminalRows);
+        // Reflow moved every rect the pointer state was tracking: hover sets
+        // and the multi-click chain reference pre-resize geometry. Fire the
+        // leave handlers FIRST — a bare clear() strands the crossed rows'
+        // hovered=true React state forever (stuck highlights) — then drop the
+        // set so a post-resize click is a fresh single click and hover re-fires
+        // from scratch. (Coordinates in in-flight events are clamped at the
+        // App boundary against the new dimensions.)
+        clearHovered(this.hoveredNodes);
+        this.app?.resetPointerState();
+        // Invalidate every render that was scheduled against the OLD size: a
+        // queued microtask generation or a scroll-drain timer would otherwise
+        // fire after this resize completes and paint a frame computed for the
+        // pre-resize layout (mixed-width rows, off-by-reflow writes). The
+        // re-render below schedules fresh work at the new dimensions.
+        this.renderGeneration++;
+        this.pendingRenderGeneration = null;
+        this.scheduleRender.cancel?.();
+        if (this.drainTimer !== null) {
+            clearTimeout(this.drainTimer);
+            this.drainTimer = null;
+        }
         // Every cached measurement in the tree was taken against a width that no
         // longer exists. Nothing here is "dirty" in the reconciler's sense — no
         // props changed — so without an explicit sweep the text nodes keep
@@ -333,9 +358,12 @@ export default class Ink {
         // doesn't exit alt-screen. Do NOT write ERASE_SCREEN: render() below
         // can take ~80ms; erasing first leaves the screen blank that whole time.
         if (this.altScreenActive && !this.isPaused && this.options.stdout.isTTY) {
-            if (this.altScreenMouseTracking) {
-                this.options.stdout.write(ENABLE_MOUSE_TRACKING);
-            }
+            // Blind mouse re-assert + 1049 probe: conpty resets modes on resize
+            // too, and a dropped 1049 means every subsequent frame paints onto
+            // the MAIN screen (looks like the app spontaneously exited
+            // fullscreen). The probe's re-entry is gated on a positive DECRPM
+            // "reset" answer, so this stays inert on healthy terminals.
+            this.probeAltScreenHealth();
             this.resetFramesForAltScreen();
             this.needsEraseBeforePaint = true;
         }
@@ -465,10 +493,12 @@ export default class Ink {
     reanchorViewport() {
         if (this.altScreenActive)
             return;
+        noteFrameCause('reanchor');
         this.log.requestViewportReanchor();
     }
     /** Render synchronously and invalidate older trailing/drain callbacks. */
     renderNow() {
+        noteFrameCause('immediate');
         this.renderGeneration++;
         this.pendingRenderGeneration = null;
         this.scheduleRender.cancel?.();
@@ -478,10 +508,49 @@ export default class Ink {
         }
         this.onRender();
     }
+    /**
+     * Schedule the next scroll-drain frame — Grok Build's Presenter, ported.
+     * Grok keeps TWO cadence knobs (min_draw_ms for renders, scroll_ms for
+     * scroll); collapsing both to FRAME_INTERVAL_MS made big flicks steppy
+     * (the proportional step, 75%-of-remaining, × 4× the interval = chunky
+     * ramp and ~4× longer settle), so the drain keeps its own fast cadence:
+     *
+     *  - CADENCE: quarter interval (~250fps). Drain frames are cheap
+     *    (DECSTBM + ~10 patches); scroll throughput is unchanged.
+     *  - IN-FLIGHT GATE: while stdout still holds unflushed bytes above
+     *    PTY_BACKLOG_BYTES (slow ConPTY round trip, ssh link), queue nothing
+     *    further — re-probe at quarter interval instead. Grok's equivalent
+     *    (in_flight_target + writer ack) exists to keep latency bounded
+     *    under exactly this backpressure; without it each stacked frame adds
+     *    its full render+write to the input→paint latency, which reads as
+     *    sticky, laggy scrolling on Windows terminals.
+     *
+     * The gate holds only DRAIN frames; React-driven renders (keystrokes,
+     * streaming) still render via the normal throttle — user-visible updates
+     * must never wait behind scroll output.
+     */
+    scheduleDrain() {
+        if (this.drainTimer !== null)
+            return;
+        const stdout = this.options.stdout;
+        const backlog = typeof stdout.writableLength === 'number'
+            ? stdout.writableLength
+            : 0;
+        if (backlog > PTY_BACKLOG_BYTES) {
+            this.drainTimer = setTimeout(() => {
+                this.drainTimer = null;
+                this.scheduleDrain();
+            }, FRAME_INTERVAL_MS >> 2);
+            return;
+        }
+        this.drainTimer = setTimeout(this.renderNow, FRAME_INTERVAL_MS >> 2);
+    }
     onRender() {
         if (this.isUnmounted || this.isPaused) {
             return;
         }
+        if (GEOMETRY_TRACE_ENABLED)
+            beginGeometryFrame(this.renderGeneration);
         // Entering a render cancels any pending drain tick — this render will
         // handle the drain (and re-schedule below if needed). Prevents a
         // wheel-event-triggered render AND a drain-timer render both firing.
@@ -494,9 +563,25 @@ export default class Ink {
         // Done before the render to avoid dirtying state that would trigger
         // an extra React re-render cycle.
         flushInteractionTime();
+        // Dimension consistency: onComputeLayout laid the tree out against
+        // this.terminalColumns/Rows (the cached values handleResize owns), so
+        // the renderer and the diff engine MUST paint that same size. Reading
+        // the live stdout size here mixed the two when a resize event had not
+        // fired yet (Windows Terminal emits 'resize' after columns already
+        // changed): Yoga laid out for the old width while log-update wrapped
+        // and diffed at the new one — rows painted off by the reflow delta.
+        // On drift, route through the resize path (cache sync + markTreeDirty
+        // + re-render) and bail: the render handleResize schedules paints the
+        // correctly-laid-out frame.
+        const liveColumns = this.options.stdout.columns || 80;
+        const liveRows = this.options.stdout.rows || 24;
+        if (this.options.stdout.isTTY && (liveColumns !== this.terminalColumns || liveRows !== this.terminalRows)) {
+            this.handleResize();
+            return;
+        }
         const renderStart = performance.now();
-        const terminalWidth = this.options.stdout.columns || 80;
-        const terminalRows = this.options.stdout.rows || 24;
+        const terminalWidth = this.terminalColumns;
+        const terminalRows = this.terminalRows;
         const frame = this.renderer({
             frontFrame: this.frontFrame,
             backFrame: this.backFrame,
@@ -507,10 +592,11 @@ export default class Ink {
             prevFrameContaminated: this.prevFrameContaminated
         });
         const rendererMs = performance.now() - renderStart;
-        // Sticky/auto-follow scrolled the ScrollBox this frame. Translate the
-        // selection by the same delta so the highlight stays anchored to the
-        // TEXT (native terminal behavior — the selection walks up the screen
-        // as content scrolls, eventually clipping at the top). frontFrame
+        // Sticky/auto-follow or wheel-drain scrolled one or more ScrollBoxes
+        // this frame. Translate the selection by the same delta so the highlight
+        // stays anchored to the TEXT (native terminal behavior — the
+        // selection walks up the screen as content scrolls, eventually
+        // clipping at the top). frontFrame
         // still holds the PREVIOUS frame's screen (swap is at ~500 below), so
         // captureScrolledRows reads the rows that are about to scroll out
         // before they're overwritten — the text stays copyable until the
@@ -518,16 +604,28 @@ export default class Ink {
         // (screen-local) so only anchor shifts — selection grows toward the
         // mouse as the anchor walks up. After release, both ends are text-
         // anchored and move as a block.
-        const follow = consumeFollowScroll();
-        if (follow && this.selection.anchor &&
-            // Only translate if the selection is ON scrollbox content. Selections
-            // in the footer/prompt/StickyPromptHeader are on static text — the
-            // scroll doesn't move what's under them. Without this guard, a
-            // footer selection would be shifted by -delta then clamped to
-            // viewportBottom, teleporting it into the scrollbox. Mirror the
-            // bounds check the deleted check() in ScrollKeybindingHandler had.
-            this.selection.anchor.row >= follow.viewportTop && this.selection.anchor.row <= follow.viewportBottom) {
+        const follow = pickFollowForSelection(consumeFollowScroll(), this.selection.anchor?.row ?? null);
+        // pickFollowForSelection already checked anchor-in-viewport (that IS
+        // the "selection is on scrollbox content" guard — footer/prompt
+        // selections on static text match no viewport and follow nothing).
+        // Innermost-viewport wins attributes correctly when several boxes
+        // scrolled this frame (transcript draining while an overlay panel's
+        // box scrolls): panels render on top, so overlap-row selections
+        // belong to the panel, not the covered transcript.
+        if (follow && this.selection.anchor) {
             const { delta, viewportTop, viewportBottom } = follow;
+            // Signed delta: >0 = content moved up (at-bottom follow or
+            // wheel-down drain); <0 = content moved down (wheel-up drain, #438).
+            // The capture window is the viewport-edge rows about to scroll out
+            // (top edge when content moves up, bottom edge when it moves down),
+            // and the shift re-anchors the endpoints by the same amount in the
+            // OPPOSITE direction so they track the text, not the screen.
+            const rows = Math.abs(delta);
+            const up = delta > 0;
+            const firstRow = up ? viewportTop : viewportBottom - rows + 1;
+            const lastRow = up ? viewportTop + rows - 1 : viewportBottom;
+            const side = up ? 'above' : 'below';
+            const shift = up ? -rows : rows;
             // captureScrolledRows and shift* are a pair: capture grabs rows about
             // to scroll off, shift moves the selection endpoint so the same rows
             // won't intersect again next frame. Capturing without shifting leaves
@@ -537,9 +635,9 @@ export default class Ink {
             // each shift branch so the pairing can't be broken by a new guard.
             if (this.selection.isDragging) {
                 if (hasSelection(this.selection)) {
-                    captureScrolledRows(this.selection, this.frontFrame.screen, viewportTop, viewportTop + delta - 1, 'above');
+                    captureScrolledRows(this.selection, this.frontFrame.screen, firstRow, lastRow, side);
                 }
-                shiftAnchor(this.selection, -delta, viewportTop, viewportBottom);
+                shiftAnchor(this.selection, shift, viewportTop, viewportBottom);
             }
             else if (
             // Flag-3 guard: the anchor check above only proves ONE endpoint is
@@ -556,14 +654,16 @@ export default class Ink {
             // is correct there even when focus is in the footer).
             !this.selection.focus || this.selection.focus.row >= viewportTop && this.selection.focus.row <= viewportBottom) {
                 if (hasSelection(this.selection)) {
-                    captureScrolledRows(this.selection, this.frontFrame.screen, viewportTop, viewportTop + delta - 1, 'above');
+                    captureScrolledRows(this.selection, this.frontFrame.screen, firstRow, lastRow, side);
                 }
-                const cleared = shiftSelectionForFollow(this.selection, -delta, viewportTop, viewportBottom);
-                // Auto-clear (both ends overshot minRow) must notify React-land
-                // so useHasSelection re-renders and the footer copy/escape hint
-                // disappears. notifySelectionChange() would recurse into onRender;
-                // fire the listeners directly — they schedule a React update for
-                // LATER, they don't re-enter this frame.
+                const cleared = shiftSelectionForFollow(this.selection, shift, viewportTop, viewportBottom);
+                // Auto-clear (both ends overshot an edge — off the top via
+                // follow/wheel-down, off the bottom via wheel-up) must notify
+                // React-land so useHasSelection re-renders and the footer
+                // copy/escape hint disappears. notifySelectionChange() would
+                // recurse into onRender; fire the listeners directly — they
+                // schedule a React update for LATER, they don't re-enter this
+                // frame.
                 if (cleared)
                     for (const cb of this.selectionListeners)
                         cb();
@@ -809,18 +909,16 @@ export default class Ink {
         // are only ever true in alt-screen; in main-screen this is false→false.
         this.prevFrameContaminated = selActive || hlActive;
         // A ScrollBox has pendingScrollDelta left to drain — schedule the next
-        // frame. MUST NOT call this.scheduleRender() here: we're inside a
-        // trailing-edge throttle invocation, timerId is undefined, and lodash's
-        // debounce sees timeSinceLastCall >= wait (last call was at the start
-        // of this window) → leadingEdge fires IMMEDIATELY → double render ~0.1ms
-        // apart → jank. Use a plain timeout. If a wheel event or immediate
-        // render arrives first, renderNow cancels this timer — no double.
-        //
-        // Drain frames are cheap (DECSTBM + ~10 patches, ~200 bytes) so run at
-        // quarter interval (~250fps, setTimeout practical floor) for max scroll
-        // speed. Regular renders stay at FRAME_INTERVAL_MS via the throttle.
+        // frame via scheduleDrain (cadence + pty backpressure gate, see there).
+        // MUST NOT call this.scheduleRender() here: we're inside a trailing-edge
+        // throttle invocation, timerId is undefined, and lodash's debounce sees
+        // timeSinceLastCall >= wait (last call was at the start of this window)
+        // → leadingEdge fires IMMEDIATELY → double render ~0.1ms apart → jank.
+        // If a wheel event or immediate render arrives first, renderNow cancels
+        // this timer — no double.
         if (frame.scrollDrainPending) {
-            this.drainTimer = setTimeout(this.renderNow, FRAME_INTERVAL_MS >> 2);
+            noteFrameCause('scroll-drain');
+            this.scheduleDrain();
         }
         const yogaMs = getLastYogaMs();
         const commitMs = getLastCommitMs();
@@ -834,6 +932,7 @@ export default class Ink {
             cacheHits: 0,
             live: 0
         };
+        endGeometryFrame(performance.now() - renderStart);
         this.options.onFrame?.({
             durationMs: performance.now() - renderStart,
             phases: {
@@ -953,6 +1052,14 @@ export default class Ink {
             return;
         this.altScreenActive = active;
         this.altScreenMouseTracking = active && mouseTracking;
+        // Screen geometry/context just changed wholesale: hover sets, the
+        // multi-click chain, and any pending hyperlink open belong to the old
+        // screen. Fire leave handlers before dropping the set — a bare clear()
+        // strands the old screen's rows with hovered=true forever (stuck
+        // highlights). Stale clickCount would turn the first click into a
+        // double-click; stale hovered nodes would suppress real onMouseEnter.
+        clearHovered(this.hoveredNodes);
+        this.app?.resetPointerState();
         if (active) {
             this.mainScreenFrameState = {
                 frontFrame: this.frontFrame,
@@ -1038,10 +1145,10 @@ export default class Ink {
             this.renderNow();
             return;
         }
-        // Mouse tracking — idempotent, safe to re-assert on every stdin gap.
-        if (this.altScreenMouseTracking) {
-            this.options.stdout.write(ENABLE_MOUSE_TRACKING);
-        }
+        // Mouse tracking + alt-screen health — the probe re-asserts mouse
+        // blindly (idempotent) and re-enters alt only if the terminal answers
+        // DECRPM with "1049 reset".
+        this.probeAltScreenHealth();
         // Alt-screen re-entry — destructive (ERASE_SCREEN). Only for callers that
         // have a strong signal the terminal actually dropped mode 1049.
         if (includeAltScreen) {
@@ -1064,6 +1171,10 @@ export default class Ink {
         // Cancel any pending throttled render so it doesn't fire between
         // cleanupTerminalModes() and process.exit() and write to main screen.
         this.scheduleRender.cancel?.();
+        if (this.drainTimer !== null) {
+            clearTimeout(this.drainTimer);
+            this.drainTimer = null;
+        }
         this.app?.detachForShutdown();
         // Shutdown bypasses the normal unmount path, so release the process and
         // stdout listeners here as well. Otherwise a SIGCONT or resize arriving
@@ -1071,6 +1182,11 @@ export default class Ink {
         // through this detached instance after terminal cleanup has completed.
         this.unsubscribeTTYHandlers?.();
         this.unsubscribeExit();
+        // unmount() early-returns on isUnmounted above, so its instances.delete
+        // never runs — a detached instance would stay in the map and a later
+        // instances.get(stdout) lookup (Chat's reanchorViewport plumbing) could
+        // hand out a dead renderer. Remove the mapping here too.
+        instances.delete(this.options.stdout);
         // `detachForShutdown()` deliberately makes later `unmount()` calls a
         // no-op, so release process-level output patches here rather than relying
         // on unmount() to do it. The shutdown continuation may run an updater
@@ -1136,6 +1252,57 @@ export default class Ink {
     drainStdin() {
         drainStdin(this.options.stdin);
     }
+    /**
+     * Self-heal after a terminal-side mode reset. Windows conpty drops DEC
+     * private modes on DPI changes, window moves between monitors and renderer
+     * restarts — the user sees the app "exit fullscreen" with a dead mouse
+     * while altScreenActive still claims we are in alt. Two layers:
+     *
+     * 1. Blind, idempotent mouse-tracking re-assert (covers the mode reset
+     *    without a round trip; ~30 bytes).
+     * 2. DECRQM probe of mode 1049. Re-entry (destructive: ERASE) happens
+     *    ONLY on a positive "reset" answer, so iTerm2's
+     *    enter-clears-when-already-in-alt quirk can never fire on a healthy
+     *    screen, and terminals that ignore DECRQM stay inert.
+     *
+     * Called from every interaction dispatch (click/hover/wheel/key) plus the
+     * focus/resize/stdin-gap triggers. The 250ms throttle keeps the round
+     * trip bounded while active use is going on — a dropped 1049 heals on
+     * the FIRST interaction after the drop instead of waiting for a focus
+     * event or a >5s idle gap (mouse motion keeps lastStdinTime fresh, so
+     * the gap path never fires during active use — the exact pattern that
+     * left the app broken until the user gave up).
+     */
+    lastHealthProbeAt = 0;
+    probeAltScreenHealth = () => {
+        const now = Date.now();
+        if (now - this.lastHealthProbeAt < 250)
+            return;
+        this.lastHealthProbeAt = now;
+        if (!this.options.stdout.isTTY || this.isPaused || !this.altScreenActive)
+            return;
+        if (this.altScreenMouseTracking) {
+            this.options.stdout.write(ENABLE_MOUSE_TRACKING);
+        }
+        const querier = this.app?.querier;
+        if (querier === undefined)
+            return;
+        void Promise.all([querier.send(decrqm(1049)), querier.flush()]).then(([reply]) => {
+            // DECRPM status: 1/3 = set, 2/4 = reset, 0/undefined = unknown.
+            // Heal only on a POSITIVE reset — an unanswered probe must not
+            // trigger the destructive re-entry.
+            if (reply !== undefined && (reply.status === 2 || reply.status === 4)) {
+                this.reenterAltScreen();
+            }
+        }).catch(() => {
+            /* probe is best-effort; the next trigger retries */
+        });
+    };
+    /** Refocus = first observable moment after a conpty-side mode reset. */
+    handleTerminalFocusProbe = (focused) => {
+        if (focused)
+            this.probeAltScreenHealth();
+    };
     /**
      * Re-enter alt-screen, clear, home, re-enable mouse tracking, and reset
      * frame buffers so the next render repaints from scratch. Self-heal for
@@ -1429,19 +1596,49 @@ export default class Ink {
      * Returns true if a DOM handler consumed the click. Gated on
      * altScreenActive — clicks only make sense with a fixed viewport where
      * nodeCache rects map 1:1 to terminal cells (no scrollback offset).
+     * The button byte is the raw SGR release code; its modifier bits land
+     * on ClickEvent.shift/alt/ctrl.
      */
-    dispatchClick(col, row) {
-        if (!this.altScreenActive)
+    dispatchClick(col, row, button = 0) {
+        // Interaction-level health probe: the first click after a conpty-side
+        // mode drop triggers the heal (probe is throttled + no-op on healthy
+        // screens). Runs before the gate so a dropped 1049 is re-entered
+        // within a round trip instead of the click silently missing.
+        this.probeAltScreenHealth();
+        if (!this.altScreenActive) {
+            logMouseDebug('dispatchClick skipped — alt screen inactive', { col, row });
             return false;
+        }
         const blank = isEmptyCellAt(this.frontFrame.screen, col, row);
-        return dispatchClick(this.rootNode, col, row, blank);
+        const handled = dispatchClick(this.rootNode, col, row, blank, button);
+        logMouseDebug('dispatchClick', { col, row, handled });
+        return handled;
+    }
+    /**
+     * Route a wheel event to the ScrollBox (any onWheel handler) under the
+     * pointer. Returns true when a handler consumed it, so App can skip the
+     * legacy global wheel-key path and exactly one layer scrolls. Gated on
+     * altScreenActive like dispatchClick — without mouse tracking there are
+     * no wheel coordinates to route by.
+     */
+    dispatchWheelAt(col, row, deltaY, deltaX = 0, button = 0) {
+        this.probeAltScreenHealth();
+        if (!this.altScreenActive)
+            return false;
+        const handled = dispatchWheel(this.rootNode, col, row, deltaY, deltaX, button);
+        if (handled) {
+            logMouseDebug('dispatchWheelAt consumed', { col, row, deltaY, deltaX });
+        }
+        return handled;
     }
     dispatchHover(col, row) {
+        this.probeAltScreenHealth();
         if (!this.altScreenActive)
             return;
         dispatchHover(this.rootNode, col, row, this.hoveredNodes);
     }
     dispatchKeyboardEvent(parsedKey) {
+        this.probeAltScreenHealth();
         const target = this.focusManager.activeElement ?? this.rootNode;
         const event = new KeyboardEvent(parsedKey);
         dispatcher.dispatchDiscrete(target, event);
@@ -1604,6 +1801,9 @@ export default class Ink {
     // cascades through useContext → <AlternateScreen>'s useLayoutEffect dep
     // array → spurious exit+re-enter of the alt screen on every SIGWINCH.
     writeRaw(data) {
+        if (data.includes('\x1b[?1049')) {
+            logMouseDebug('stdout:1049', { len: data.length, head: data.slice(0, 60) });
+        }
         this.options.stdout.write(data);
     }
     setCursorDeclaration = (decl, clearIfNode) => {
@@ -1617,7 +1817,7 @@ export default class Ink {
     }
     render(node) {
         this.currentNode = node;
-        const tree = _jsx(App, { ref: this.setAppRef, stdin: this.options.stdin, stdout: this.options.stdout, stderr: this.options.stderr, exitOnCtrlC: this.options.exitOnCtrlC, onExit: this.unmount, terminalColumns: this.terminalColumns, terminalRows: this.terminalRows, selection: this.selection, onSelectionChange: this.notifySelectionChange, onClickAt: this.dispatchClick, onHoverAt: this.dispatchHover, getHyperlinkAt: this.getHyperlinkAt, onOpenHyperlink: this.openHyperlink, onMultiClick: this.handleMultiClick, onSelectionDrag: this.handleSelectionDrag, onStdinResume: this.reassertTerminalModes, onCursorDeclaration: this.setCursorDeclaration, dispatchKeyboardEvent: this.dispatchKeyboardEvent, children: _jsx(TerminalWriteProvider, { value: this.writeRaw, children: node }) });
+        const tree = _jsx(App, { ref: this.setAppRef, stdin: this.options.stdin, stdout: this.options.stdout, stderr: this.options.stderr, exitOnCtrlC: this.options.exitOnCtrlC, onExit: this.unmount, terminalColumns: this.terminalColumns, terminalRows: this.terminalRows, selection: this.selection, onSelectionChange: this.notifySelectionChange, onClickAt: this.dispatchClick, onHoverAt: this.dispatchHover, onWheelAt: this.dispatchWheelAt, getHyperlinkAt: this.getHyperlinkAt, onOpenHyperlink: this.openHyperlink, onMultiClick: this.handleMultiClick, onSelectionDrag: this.handleSelectionDrag, onStdinResume: this.reassertTerminalModes, onTerminalFocus: this.handleTerminalFocusProbe, onCursorDeclaration: this.setCursorDeclaration, dispatchKeyboardEvent: this.dispatchKeyboardEvent, children: _jsx(TerminalWriteProvider, { value: this.writeRaw, children: node }) });
         // @ts-ignore -- ported CC build; type drift tolerated updateContainerSync exists in react-reconciler but not in @types/react-reconciler
         reconciler.updateContainerSync(tree, this.container, null, noop);
         // @ts-ignore -- ported CC build; type drift tolerated flushSyncWork exists in react-reconciler but not in @types/react-reconciler
@@ -1791,9 +1991,25 @@ export default class Ink {
                 logForDebugging(`[stderr] ${text}`, {
                     level: 'warn'
                 });
-                if (this.altScreenActive && !this.isUnmounted && !this.isPaused) {
-                    this.prevFrameContaminated = true;
-                    this.scheduleRender();
+                if (!this.isUnmounted && !this.isPaused) {
+                    if (this.altScreenActive) {
+                        this.prevFrameContaminated = true;
+                        this.scheduleRender();
+                    }
+                    else {
+                        // Main-screen (inline): the diff engine's moves are purely
+                        // relative to the physical cursor, so ANY unobserved tty write
+                        // (one that slipped through before this patch existed, or via
+                        // a path it can't intercept — a snapshotted ESM writer) shifts
+                        // every later write by N rows with nothing to detect it after
+                        // the fact. The stdin-gap reassert covers slow leaks; this
+                        // per-write defensive net closes the fast ones: blind
+                        // idempotent viewport repaint from the physical cursor. When
+                        // nothing drifted (the usual case — the write was swallowed)
+                        // it paints the same pixels again at O(viewport) bytes.
+                        this.log.requestViewportReanchor();
+                        this.scheduleRender();
+                    }
                 }
             }
             finally {

package/lib/types/ink/node-cache.d.ts

@@ -12,6 +12,11 @@ export type CachedLayout = {
     width: number;
     height: number;
     top?: number;
+    /** Effective background color (own ?? inherited) at the last render.
+     *  Renderer compares it per frame so a background change refuses the
+     *  prevScreen blit — children would otherwise resurrect the stale color
+     *  (stuck hover highlight). */
+    bg?: string;
 };
 /** Layout bounds cached per rendered node, used for blitting and clearing. */
 export declare const nodeCache: WeakMap<DOMElement, CachedLayout>;

package/lib/types/ink/node-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-cache.d.ts","sourceRoot":"","sources":["../../../src/ink/node-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAErD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,8EAA8E;AAC9E,eAAO,MAAM,SAAS,mCAA0C,CAAA;AAEhE,kEAAkE;AAClE,eAAO,MAAM,aAAa,kCAAyC,CAAA;AAanE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,OAAO,GAClB,IAAI,CAUN;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAIpD"}
+{"version":3,"file":"node-cache.d.ts","sourceRoot":"","sources":["../../../src/ink/node-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAErD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;mCAG+B;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,8EAA8E;AAC9E,eAAO,MAAM,SAAS,mCAA0C,CAAA;AAEhE,kEAAkE;AAClE,eAAO,MAAM,aAAa,kCAAyC,CAAA;AAanE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,OAAO,GAClB,IAAI,CAUN;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAIpD"}

package/lib/types/ink/parse-keypress.d.ts

@@ -131,6 +131,14 @@ export type ParsedKey = {
     raw: string | undefined;
     code?: string;
     isPasted: boolean;
+    /**
+     * Pointer column (0-indexed) for wheel keys — SGR/X10 wheel sequences
+     * carry the position the wheel event occurred at. Undefined for
+     * non-wheel keys.
+     */
+    mouseCol?: number;
+    /** Pointer row (0-indexed) for wheel keys. See mouseCol. */
+    mouseRow?: number;
 };
 /** A terminal response sequence (DECRPM, DA1, OSC reply, etc.) parsed
  *  out of the input stream. Not user input — consumers should dispatch

package/lib/types/ink/parse-keypress.d.ts.map

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