@askdkc/dsh-cli 0.11.3

package/lib/types/ink/log-update.js

@@ -0,0 +1,1000 @@
+import { ansiCodesToString, } from '@alcalzone/ansi-tokenize';
+import { logForDebugging } from '../utils/debug.js';
+import { cellAt, charInCellAt, diffEach, isEmptyCellAt, shiftRows, transitionAnsiCodes, visibleCellAtIndex, } from './screen.js';
+import { CURSOR_HOME, cursorDown, eraseToEndOfScreen, scrollDown as csiScrollDown, scrollUp as csiScrollUp, RESET_SCROLL_REGION, SGR_RESET, setScrollRegion, } from './termio/csi.js';
+import { isJetBrainsIdeTerminal } from './terminal.js';
+import { LINK_END, link as oscLink } from './termio/osc.js';
+const CARRIAGE_RETURN = { type: 'carriageReturn' };
+const NEWLINE = { type: 'stdout', content: '\n' };
+/**
+ * Converts frame diffs into terminal write patches. Holds per-instance
+ * state (previous output, style pool, TTY mode) across frames.
+ */
+export class LogUpdate {
+    options;
+    state;
+    constructor(options) {
+        this.options = options;
+        this.state = {
+            previousOutput: '',
+            reanchorPending: false,
+            anchoredPad: 0,
+        };
+    }
+    /**
+     * Request a one-shot viewport re-anchor on the next main-screen frame.
+     *
+     * The main-screen diff engine addresses rows purely relative to where it
+     * left the cursor — it has no absolute anchor and no way to notice when a
+     * third party moved it. A subprocess writing directly to the tty (an MCP
+     * server's stderr, a stray native log line — issue #17) advances the
+     * cursor and scrolls the terminal; every subsequent diff then lands N
+     * rows off, garbling the UI (missing labels, shifted rows — issue #16)
+     * until some full repaint happens to run. There is nothing to detect
+     * after the fact (a newline-terminated write parks the cursor back at
+     * the bottom column 0, exactly where the engine expects it), so the
+     * recovery is a blind idempotent repaint: rebuild the viewport from the
+     * physical cursor position, which re-syncs the virtual↔physical mapping
+     * no matter how far they had drifted. Wired to the stdin-gap reassert
+     * (>5s idle then a keypress) — the same trigger that re-asserts DEC
+     * modes after tmux attach / ssh reconnect.
+     */
+    requestViewportReanchor() {
+        this.state.reanchorPending = true;
+    }
+    /**
+     * Render the terminal state for a finished run, for streams that no
+     * longer support string output.
+     * @param prevFrame - the previously rendered frame.
+     * @returns the patches that restore the terminal to the previous frame's state.
+     */
+    renderPreviousOutput_DEPRECATED(prevFrame) {
+        if (!this.options.isTTY) {
+            // Non-TTY output is no longer supported (string output was removed)
+            return [NEWLINE];
+        }
+        return this.getRenderOpsForDone(prevFrame);
+    }
+    // Called when process resumes from suspension (SIGCONT) to prevent clobbering terminal content
+    /** Drop the previous-output state after the process resumes from suspension (SIGCONT) so terminal content is not clobbered. */
+    reset() {
+        this.state.previousOutput = '';
+        // Any anchored-pad offset is void: the next frame repaints from the
+        // physical cursor without it (SIGCONT resume, repaint(), forceRedraw,
+        // and alt-screen entry all land here — without the clear, rows the
+        // repaint just drew at the viewport top would stay marked unreachable).
+        this.state.anchoredPad = 0;
+    }
+    renderFullFrame(frame) {
+        const { screen } = frame;
+        const lines = [];
+        let currentStyles = [];
+        let currentHyperlink = undefined;
+        for (let y = 0; y < screen.height; y++) {
+            let line = '';
+            for (let x = 0; x < screen.width; x++) {
+                const cell = cellAt(screen, x, y);
+                if (cell && cell.width !== 2 /* CellWidth.SpacerTail */) {
+                    // Handle hyperlink transitions
+                    if (cell.hyperlink !== currentHyperlink) {
+                        if (currentHyperlink !== undefined) {
+                            line += LINK_END;
+                        }
+                        if (cell.hyperlink !== undefined) {
+                            line += oscLink(cell.hyperlink);
+                        }
+                        currentHyperlink = cell.hyperlink;
+                    }
+                    const cellStyles = this.options.stylePool.get(cell.styleId);
+                    const styleDiff = transitionAnsiCodes(currentStyles, cellStyles);
+                    if (styleDiff.length > 0) {
+                        line += ansiCodesToString(styleDiff);
+                        currentStyles = cellStyles;
+                    }
+                    line += cell.char;
+                }
+            }
+            // Close any open hyperlink before resetting styles
+            if (currentHyperlink !== undefined) {
+                line += LINK_END;
+                currentHyperlink = undefined;
+            }
+            // Reset styles at end of line so trimEnd doesn't leave dangling codes
+            const resetCodes = transitionAnsiCodes(currentStyles, []);
+            if (resetCodes.length > 0) {
+                line += ansiCodesToString(resetCodes);
+                currentStyles = [];
+            }
+            lines.push(line.trimEnd());
+        }
+        if (lines.length === 0) {
+            return [];
+        }
+        return [{ type: 'stdout', content: lines.join('\n') }];
+    }
+    getRenderOpsForDone(prev) {
+        this.state.previousOutput = '';
+        if (!prev.cursor.visible) {
+            return [{ type: 'cursorShow' }];
+        }
+        return [];
+    }
+    /**
+     * Diff the previous and next frames and produce the patches that update
+     * the terminal from one to the other.
+     * @param prev - the previously rendered frame.
+     * @param next - the frame to render.
+     * @param altScreen - whether the frame renders to the alternate screen.
+     * @param decstbmSafe - whether the DECSTBM scroll sequence can be made atomic (DEC 2026 / BSU/ESU).
+     * @returns the terminal write patches.
+     */
+    render(prev, next, altScreen = false, decstbmSafe = true) {
+        if (!this.options.isTTY) {
+            return this.renderFullFrame(next);
+        }
+        const startTime = performance.now();
+        const stylePool = this.options.stylePool;
+        // Since we assume the cursor is at the bottom on the screen, we only need
+        // to clear when the viewport gets shorter (i.e. the cursor position drifts)
+        // or when it gets thinner (and text wraps). We _could_ figure out how to
+        // not reset here but that would involve predicting the current layout
+        // _after_ the viewport change which means calcuating text wrapping.
+        // Resizing is a rare enough event that it's not practically a big issue.
+        if (next.viewport.height !== prev.viewport.height ||
+            (prev.viewport.width !== 0 && next.viewport.width !== prev.viewport.width)) {
+            // A resize re-aligns the whole terminal (reflow rewraps scrollback):
+            // any anchored-pad offset from a previous shrink repaint is void.
+            // Height-only growth is included: the shrink branches below would
+            // otherwise mix the old and new viewport heights in their geometry.
+            this.state.anchoredPad = 0;
+            return fullResetSequence_CAUSES_FLICKER(next, 'resize', stylePool);
+        }
+        // One-shot viewport re-anchor (see requestViewportReanchor): repaint
+        // the whole visible window from the physical cursor position, blind to
+        // whatever a third-party tty write did to it. Main-screen only — the
+        // alt-screen path already self-heals with CSI H every frame. Checked
+        // after the resize reset (which supersedes it; the flag survives to
+        // the next frame) and before the DECSTBM path (alt-screen only, so
+        // mutually exclusive anyway).
+        if (this.state.reanchorPending && !altScreen) {
+            this.state.reanchorPending = false;
+            // Plain in-place viewport repaint, and the anchored layout (if any)
+            // is superseded: pad 0. An earlier revision routed pad>0 frames
+            // through shrinkAnchoredRepaint here to preserve the anchored layout
+            // — empirically that occasionally painted nothing after alt-screen
+            // exits (verify-trace-scene's settle-gap check, ~15% flake), while
+            // the plain path is verified stable; a reanchor-with-pad is rare
+            // (idle gap right after a settle shrink) and its cost is one stale
+            // scrollback copy, not a lost paint.
+            this.state.anchoredPad = 0;
+            return repaintViewportInPlace(prev, next, stylePool);
+        }
+        // DECSTBM scroll optimization: when a ScrollBox's scrollTop changed,
+        // shift content with a hardware scroll (CSI top;bot r + CSI n S/T)
+        // instead of rewriting the whole scroll region. The shiftRows on
+        // prev.screen simulates the shift so the diff loop below naturally
+        // finds only the rows that scrolled IN as diffs. prev.screen is
+        // about to become backFrame (reused next render) so mutation is safe.
+        // CURSOR_HOME after RESET_SCROLL_REGION is defensive — DECSTBM reset
+        // homes cursor per spec but terminal implementations vary.
+        //
+        // decstbmSafe: caller passes false when the DECSTBM→diff sequence
+        // can't be made atomic (no DEC 2026 / BSU/ESU). Without atomicity the
+        // outer terminal renders the intermediate state — region scrolled,
+        // edge rows not yet painted — a visible vertical jump on every frame
+        // where scrollTop moves. Falling through to the diff loop writes all
+        // shifted rows: more bytes, no intermediate state. next.screen from
+        // render-node-to-output's blit+shift is correct either way.
+        let scrollPatch = [];
+        if (altScreen && next.scrollHint && decstbmSafe) {
+            const { top, bottom, delta } = next.scrollHint;
+            if (top >= 0 &&
+                bottom < prev.screen.height &&
+                bottom < next.screen.height) {
+                shiftRows(prev.screen, top, bottom, delta);
+                // The hardware scroll's blank fill uses the terminal's CURRENT
+                // background (BCE); the SGR reset at the head of every frame buffer
+                // (writeDiffToTerminal) guarantees the default background here even
+                // after a truncated previous frame left a colored SGR stuck.
+                scrollPatch = [
+                    {
+                        type: 'stdout',
+                        content: setScrollRegion(top + 1, bottom + 1) +
+                            (delta > 0 ? csiScrollUp(delta) : csiScrollDown(-delta)) +
+                            RESET_SCROLL_REGION +
+                            CURSOR_HOME,
+                    },
+                ];
+            }
+        }
+        // We have to use purely relative operations to manipulate the cursor since
+        // we don't know its starting point.
+        //
+        // When content height >= viewport height AND cursor is at the bottom,
+        // the cursor restore at the end of the previous frame caused terminal scroll.
+        // viewportY tells us how many rows are in scrollback from content overflow.
+        // Additionally, the cursor-restore scroll pushes 1 more row into scrollback.
+        // We need fullReset if any changes are to rows that are now in scrollback.
+        //
+        // This early full-reset check only applies in "steady state" (not growing).
+        // For growing, the viewportY calculation below (with cursorRestoreScroll)
+        // catches unreachable scrollback rows in the diff loop instead.
+        const cursorAtBottom = prev.cursor.y >= prev.screen.height;
+        const isGrowing = next.screen.height > prev.screen.height;
+        // When content fills the viewport exactly (height == viewport) and the
+        // cursor is at the bottom, the cursor-restore LF at the end of the
+        // previous frame scrolled 1 row into scrollback. Use >= to catch this.
+        const prevHadScrollback = cursorAtBottom && prev.screen.height >= prev.viewport.height;
+        const isShrinking = next.screen.height < prev.screen.height;
+        const nextFitsViewport = next.screen.height <= prev.viewport.height;
+        // When shrinking from above-viewport to at-or-below-viewport, the rows
+        // that scrolled into scrollback during growth come BACK into the live
+        // frame, so their scrollback snapshots are now duplicates (seen as the
+        // duplicated whale logo after the first turn). Use a clear-terminal
+        // reset, not an in-place repaint: at this point the UI's scrollback
+        // footprint is at most a viewport tall (prev was at most one row past
+        // the viewport), which is exactly what the clear sequence blanks — the
+        // in-place repaint kept both copies (snapshot + live). The former full
+        // reset here was once changed to an in-place repaint to stop the
+        // per-shrink stale-copy deposits (#38 #39 #19), but that fix traded
+        // them for a different duplication: the repainted viewport overlaps
+        // rows whose growth snapshots are still in scrollback.
+        // Use <= (not <) because even when next height equals viewport height,
+        // the scrollback depth from the previous render differs from a fresh
+        // render.
+        if (!altScreen && prevHadScrollback && nextFitsViewport && isShrinking) {
+            // Anchored tail repaint (see shrinkAnchoredRepaint): rows already in
+            // scrollback keep their originals; only the changed tail is
+            // repainted. The former full reset here reprinted the whole short
+            // frame from the viewport top — duplicating every pre-shrink row the
+            // user scrolls up to (the whale-logo / duplicated-transcript
+            // reports).
+            const scrollbackRows = Math.max(0, Math.max(prev.screen.height, next.screen.height) -
+                next.viewport.height +
+                (prevHadScrollback ? 1 : 0));
+            const { patches, anchoredPad } = shrinkAnchoredRepaint(prev, next, stylePool, scrollbackRows);
+            this.state.anchoredPad = anchoredPad;
+            logForDebugging(`Anchored shrink repaint (shrink->below): prevHeight=${prev.screen.height}, nextHeight=${next.screen.height}, viewport=${prev.viewport.height}, skip=${anchoredPad}`);
+            return patches;
+        }
+        // Steady-state scrollback check removed: rows above the viewport used
+        // to force a full reset (ESC[2J+ESC[3J) whenever they changed, which
+        // wipes terminal scrollback and snaps the viewport to the top — firing
+        // on every streaming pause frame. The diff loop below now skips those
+        // rows instead (y < viewportY → skip), repainting them when they
+        // scroll back into view. Shrink and resize resets below are kept.
+        const screen = new VirtualScreen(prev.cursor, next.viewport.width);
+        // Treat empty screen as height 1 to avoid spurious adjustments on first render
+        const heightDelta = Math.max(next.screen.height, 1) - Math.max(prev.screen.height, 1);
+        const shrinking = heightDelta < 0;
+        const growing = heightDelta > 0;
+        // Handle shrinking: clear lines from the bottom
+        // When prevHadScrollback, add 1 for the cursor-restore LF that scrolled
+        // an additional row out of view at the end of the previous frame.
+        const cursorRestoreScroll = prevHadScrollback ? 1 : 0;
+        if (shrinking) {
+            const linesToClear = prev.screen.height - next.screen.height;
+            // Main-screen mode + content taller than the viewport: the terminal
+            // viewport does NOT follow the content bottom when content shrinks —
+            // a diff-loop path would write rows at stale physical offsets. Two
+            // sub-cases:
+            //
+            // 1. Frame shrinks but stays >= viewport height: take the ordinary
+            //    diff loop. Its viewportY bookkeeping (the shrinking formula plus
+            //    cursorRestoreScroll below) addresses rows through the parked
+            //    cursor correctly, and the diff only touches the few rows that
+            //    actually changed. A viewport repaint here re-paints the whole
+            //    window from the viewport top while the frame top sits a few rows
+            //    ABOVE it (frame is taller than the window) — the growth frames
+            //    around the shrink freeze those overlapped rows into scrollback
+            //    as snapshots while the same rows stay live in the window, which
+            //    the user sees as duplicated transcript rows when scrolling up.
+            // 2. Frame shrinks to BELOW the viewport (content now fits): the rows
+            //    that scrolled into scrollback during growth come BACK into the
+            //    live frame, so their scrollback snapshots are now duplicates
+            //    (seen as the duplicated whale logo after the first turn). Use a
+            //    clear-terminal reset here, not an in-place repaint: at this
+            //    point the UI's scrollback footprint is at most a viewport tall,
+            //    which is exactly what the clear sequence blanks, while the
+            //    in-place repaint would keep both copies. Only fires early in a
+            //    session (frame ~= viewport); once the transcript outgrows the
+            //    viewport, case 1 handles every shrink.
+            if (!altScreen &&
+                prev.screen.height > prev.viewport.height &&
+                next.screen.height < next.viewport.height) {
+                // Same anchored tail repaint as the shrink->below branch above —
+                // rows already in scrollback keep their originals; only the
+                // non-scrollback tail is repainted. The former full reset
+                // reprinted the whole frame, duplicating the scrollback rows
+                // (whale-logo / duplicated-transcript reports).
+                const scrollbackRows = Math.max(0, prev.screen.height - prev.viewport.height + cursorRestoreScroll);
+                const { patches, anchoredPad } = shrinkAnchoredRepaint(prev, next, this.options.stylePool, scrollbackRows);
+                this.state.anchoredPad = anchoredPad;
+                logForDebugging(`Anchored shrink repaint (shrink to fit): prevHeight=${prev.screen.height}, nextHeight=${next.screen.height}, viewport=${prev.viewport.height}, skip=${anchoredPad}`);
+                return patches;
+            }
+            // eraseLines only works within the viewport - it can't clear scrollback.
+            // If we need to clear more lines than fit in the viewport, some are in
+            // scrollback, so we need a full reset.
+            if (linesToClear > prev.viewport.height) {
+                return fullResetSequence_CAUSES_FLICKER(next, 'offscreen', this.options.stylePool);
+            }
+            // Record the scrollback rows stranded by this shrink. The terminal's
+            // scrollback cannot shrink with the content: rows that were above the
+            // viewport BEFORE the shrink stay there after it, but the heights
+            // formula below (height - viewport + cursorRestoreScroll) recomputes
+            // scrollback from the SMALLER next height on every following frame and
+            // undercounts by the shrink delta. Those frames then treat a
+            // scrolled-away row as reachable, the cursor-up move clamps at the
+            // viewport top, and the whole relative write chain lands one row low —
+            // stale duplicate rows and torn leading cells that no later sparse
+            // diff ever repairs (verify-trace-scene settle-gap flake). The
+            // shrink-to-below-viewport branch above already records this via
+            // shrinkAnchoredRepaint; this ordinary-diff shrink path must record it
+            // too. viewportY takes max(anchoredPad, heights formula), so the pad
+            // naturally hands back to the formula once growth scrolls the gap away.
+            if (!altScreen) {
+                const strandedScrollback = Math.max(0, prev.screen.height - prev.viewport.height) +
+                    cursorRestoreScroll;
+                if (strandedScrollback > this.state.anchoredPad) {
+                    this.state.anchoredPad = strandedScrollback;
+                }
+            }
+            // clear(N) moves cursor UP by N-1 lines and to column 0
+            // This puts us at line prev.screen.height - N = next.screen.height
+            // But we want to be at next.screen.height - 1 (bottom of new screen)
+            screen.txn(prev2 => [
+                [
+                    { type: 'clear', count: linesToClear },
+                    { type: 'cursorMove', x: 0, y: -1 },
+                ],
+                { dx: -prev2.x, dy: -linesToClear },
+            ]);
+        }
+        // viewportY = number of rows in scrollback (not visible on terminal).
+        // For shrinking: use max(prev, next) because terminal clears don't scroll.
+        // For growing: use prev state because new rows haven't scrolled old ones yet.
+        // When prevHadScrollback, add 1 for the cursor-restore LF that scrolled
+        // an additional row out of view at the end of the previous frame. Without
+        // this, the diff loop treats that row as reachable — but the cursor clamps
+        // at viewport top, causing writes to land 1 row off and garbling the output.
+        // Unreachable frame rows = terminal scrollback. Two contributors, take
+        // the MAX, never the sum: after an anchored shrink repaint the pad rows
+        // ARE the scrollback (heights undercount while H < V); once growth
+        // scrolls the blank band away, the heights formula takes over (summing
+        // would overcount and skip REACHABLE viewport rows — changes inside
+        // the viewport would never paint, scrambling the layout on mid-frame
+        // edits like Ctrl+O expansion).
+        const viewportY = Math.max(this.state.anchoredPad, growing
+            ? Math.max(0, prev.screen.height - prev.viewport.height + cursorRestoreScroll)
+            : Math.max(prev.screen.height, next.screen.height) -
+                next.viewport.height +
+                cursorRestoreScroll);
+        // Rows above viewportY live in terminal scrollback and are skipped by the
+        // diff loop (see below). Clip the damage region to the visible area so the
+        // loop doesn't scan scrollback rows cell-by-cell every frame — with a tall
+        // conversation that's a per-frame O(full screen) cost and stalls rendering.
+        // prev.damage participates in diffEach's region union, so clip it too
+        // (blit doesn't read damage — renderer.ts uses it only in comments).
+        if (viewportY > 0) {
+            for (const src of [next.screen, prev.screen]) {
+                const dmg = src.damage;
+                if (dmg && dmg.y < viewportY) {
+                    const overhang = viewportY - dmg.y;
+                    src.damage = {
+                        x: dmg.x,
+                        y: viewportY,
+                        width: dmg.width,
+                        height: Math.max(0, dmg.height - overhang),
+                    };
+                }
+            }
+        }
+        let currentStyleId = stylePool.none;
+        let currentHyperlink = undefined;
+        // First pass: render changes to existing rows (rows < prev.screen.height)
+        diffEach(prev.screen, next.screen, (x, y, removed, added) => {
+            // Skip new rows - we'll render them directly after
+            if (growing && y >= prev.screen.height) {
+                return;
+            }
+            // Skip spacers during rendering because the terminal will automatically
+            // advance 2 columns when we write the wide character itself.
+            // SpacerTail: Second cell of a wide character
+            // SpacerHead: Marks line-end position where wide char wraps to next line
+            if (added &&
+                (added.width === 2 /* CellWidth.SpacerTail */ ||
+                    added.width === 3 /* CellWidth.SpacerHead */)) {
+                return;
+            }
+            if (removed &&
+                (removed.width === 2 /* CellWidth.SpacerTail */ ||
+                    removed.width === 3 /* CellWidth.SpacerHead */) &&
+                !added) {
+                return;
+            }
+            // Skip empty cells that don't need to overwrite existing content.
+            // This prevents writing trailing spaces that would cause unnecessary
+            // line wrapping at the edge of the screen.
+            // Uses isEmptyCellAt to check if both packed words are zero (empty cell).
+            if (added && isEmptyCellAt(next.screen, x, y) && !removed) {
+                return;
+            }
+            // Rows above the viewport live in terminal scrollback — the cursor
+            // can't reach them, and the only way to repaint them is a full reset
+            // (ESC[2J+ESC[3J), which wipes the scrollback and snaps the terminal
+            // viewport back to the top (user scrolled up → jumps to the very
+            // first line). Skip updating them; they repaint normally when they
+            // scroll back into the viewport. Chat history is static content, so
+            // nothing visible is lost by leaving scrollback rows stale.
+            if (y < viewportY) {
+                return;
+            }
+            moveCursorTo(screen, x, y);
+            if (added) {
+                const targetHyperlink = added.hyperlink;
+                currentHyperlink = transitionHyperlink(screen.diff, currentHyperlink, targetHyperlink);
+                const styleStr = stylePool.transition(currentStyleId, added.styleId);
+                if (writeCellWithStyleStr(screen, added, styleStr)) {
+                    currentStyleId = added.styleId;
+                }
+            }
+            else if (removed) {
+                // Cell was removed - clear it with a space
+                // (This handles shrinking content)
+                // Reset any active styles/hyperlinks first to avoid leaking into cleared cells
+                const styleIdToReset = currentStyleId;
+                const hyperlinkToReset = currentHyperlink;
+                currentStyleId = stylePool.none;
+                currentHyperlink = undefined;
+                screen.txn(() => {
+                    const patches = [];
+                    transitionStyle(patches, stylePool, styleIdToReset, stylePool.none);
+                    transitionHyperlink(patches, hyperlinkToReset, undefined);
+                    patches.push({ type: 'stdout', content: ' ' });
+                    return [patches, { dx: 1, dy: 0 }];
+                });
+            }
+        });
+        // Reset styles before rendering new rows (they'll set their own styles)
+        currentStyleId = transitionStyle(screen.diff, stylePool, currentStyleId, stylePool.none);
+        currentHyperlink = transitionHyperlink(screen.diff, currentHyperlink, undefined);
+        // Handle growth: render new rows directly (they naturally scroll the terminal)
+        if (growing) {
+            renderFrameSlice(screen, next, prev.screen.height, next.screen.height, stylePool);
+        }
+        // Restore cursor. Skipped in alt-screen: the cursor is hidden, its
+        // position only matters as the starting point for the NEXT frame's
+        // relative moves, and in alt-screen the next frame always begins with
+        // CSI H (see ink.tsx onRender) which resets to (0,0) regardless. This
+        // saves a CR + cursorMove round-trip (~6-10 bytes) every frame.
+        //
+        // Main screen: if cursor needs to be past the last line of content
+        // (typical: cursor.y = screen.height), emit \n to create that line
+        // since cursor movement can't create new lines.
+        //
+        // LFs are only for CREATING rows: past the viewport bottom they scroll a
+        // row into scrollback, which is what grows the transcript. A target row
+        // that is still on screen (cursor.y < viewport.height) is reachable by
+        // plain cursor movement, and LF-ing to it instead scrolls the terminal
+        // one row per LF for no content gain — the idle-repaint churn: a settled
+        // session whose header only animates wrote 9-22 LF per frame (5 frames/s,
+        // ~73 LF/s measured) for a screen that changed nothing visible, refilling
+        // a 1000-row phone scrollback window with duplicate viewports in seconds.
+        // Same destination, no scroll: fall through to moveCursorTo.
+        if (altScreen) {
+            // no-op; next frame's CSI H anchors cursor
+        }
+        else if (next.cursor.y >= next.viewport.height) {
+            // Target row is below the visible viewport: only LF can create it.
+            // Move to column 0 of current line, then emit newlines to reach target row
+            screen.txn(prev => {
+                const rowsToCreate = next.cursor.y - prev.y;
+                if (rowsToCreate > 0) {
+                    // Use CR to resolve pending wrap (if any) without advancing
+                    // to the next line, then LF to create each new row.
+                    const patches = new Array(1 + rowsToCreate);
+                    patches[0] = CARRIAGE_RETURN;
+                    for (let i = 0; i < rowsToCreate; i++) {
+                        patches[1 + i] = NEWLINE;
+                    }
+                    return [patches, { dx: -prev.x, dy: rowsToCreate }];
+                }
+                // At or past target row - need to move cursor to correct position
+                const dy = next.cursor.y - prev.y;
+                if (dy !== 0 || prev.x !== next.cursor.x) {
+                    // Use CR to clear pending wrap (if any), then cursor move
+                    const patches = [CARRIAGE_RETURN];
+                    patches.push({ type: 'cursorMove', x: next.cursor.x, y: dy });
+                    return [patches, { dx: next.cursor.x - prev.x, dy }];
+                }
+                return [[], { dx: 0, dy: 0 }];
+            });
+        }
+        else {
+            moveCursorTo(screen, next.cursor.x, next.cursor.y);
+        }
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 50) {
+            const damage = next.screen.damage;
+            const damageInfo = damage
+                ? `${damage.width}x${damage.height} at (${damage.x},${damage.y})`
+                : 'none';
+            logForDebugging(`Slow render: ${elapsed.toFixed(1)}ms, screen: ${next.screen.height}x${next.screen.width}, damage: ${damageInfo}, changes: ${screen.diff.length}`);
+        }
+        let result = scrollPatch.length > 0
+            ? [...scrollPatch, ...screen.diff]
+            : screen.diff;
+        // JetBrains IDE terminals (JediTerm) in main-screen (inline) mode:
+        // append a visible-frame rewrite to the incremental diff.
+        //
+        // JediTerm's reworked block renderer (the default terminal in JetBrains
+        // IDEs 2025.2+) repaints a view row only when its model cells change,
+        // and it re-renders between writes. The incremental diff above writes
+        // only the cells that changed since the previous frame — so a row the
+        // block renderer misrendered mid-frame (partial reflow) is never
+        // touched again, and the garbage persists and accumulates as the
+        // transcript streams and scrolls: the "works in VS Code, slowly garbles
+        // in JetBrains" symptom. xterm.js-family terminals (VS Code) repaint
+        // the fixed grid on every write, so the same byte stream is clean
+        // there; the model-level state is identical on both (verified by
+        // replaying captured frame bytes through the IDE's bundled JediTerm
+        // emulator against xterm.js) — the divergence is purely the view
+        // layer's incremental repaint.
+        //
+        // The rewrite runs AFTER the incremental writes instead of replacing
+        // them: the growth path's CR+LF writes are what scroll scrolled-off
+        // rows into the terminal's native scrollback (inline mode's whole
+        // point). A pure full-repaint mode would never emit those scrolls and
+        // the transcript above the viewport would vanish. Appending a repaint
+        // anchored at the visible frame start (CR + CUU(visibleRows) + ED0 +
+        // frame tail) overwrites every application cell, forcing the block
+        // renderer to a correct full repaint without touching scrollback or
+        // shell output above a short frame. The appended slice lands its
+        // row-ending CR+LFs inside the viewport so nothing extra scrolls. The
+        // anchor prefixes SGR_RESET + link('') so the ED0's BCE fill uses the
+        // default background and any hyperlink the incremental writes left open
+        // is closed first. Frames that took a full-reset path already repaint
+        // everything and are skipped. A one-row viewport has no separate park
+        // row, so it keeps the original incremental output. Alt-screen is
+        // unaffected: its per-frame CSI H anchor + BSU/ESU atomic frames already
+        // keep the block renderer consistent.
+        if (!altScreen &&
+            isJetBrainsIdeTerminal() &&
+            prev.viewport.height > 1 &&
+            !result.some(patch => patch.type === 'clearTerminal')) {
+            logForDebugging(`JetBrains inline frame: append viewport repaint (height=${next.screen.height}, viewport=${prev.viewport.height})`);
+            result = [
+                ...result,
+                ...viewportRepaintPatches(prev, next, stylePool, true, 'frame-end'),
+            ];
+        }
+        return result;
+    }
+}
+function transitionHyperlink(diff, current, target) {
+    if (current !== target) {
+        diff.push({ type: 'hyperlink', uri: target ?? '' });
+        return target;
+    }
+    return current;
+}
+function transitionStyle(diff, stylePool, currentId, targetId) {
+    const str = stylePool.transition(currentId, targetId);
+    if (str.length > 0) {
+        diff.push({ type: 'styleStr', str });
+    }
+    return targetId;
+}
+function readLine(screen, y) {
+    let line = '';
+    for (let x = 0; x < screen.width; x++) {
+        line += charInCellAt(screen, x, y) ?? ' ';
+    }
+    return line.trimEnd();
+}
+function fullResetSequence_CAUSES_FLICKER(frame, reason, stylePool, debug) {
+    // After clearTerminal the viewport is blank and the cursor is at (0, 0), so
+    // this paints downward from the top — and therefore must paint only what
+    // fits. Every row here ends in CR+LF, the bottom viewport row is reserved
+    // for the cursor park, and so at most viewportHeight-1 rows of content can
+    // land above it. Painting the whole frame regardless overflows as soon as
+    // the frame is as tall as the viewport: the trailing CR+LF is emitted on the
+    // bottom row, the terminal scrolls, and the frame's last row — the status
+    // hint, always the final row of the main screen — is carried off the bottom.
+    // A narrowing resize is what makes a frame reach full height (content wraps
+    // onto more rows while the row count stays put), which is why that direction
+    // lost its bottom row while widening never did.
+    //
+    // Painting the frame's tail instead keeps the same end state the in-place
+    // viewport repaint documents — frame rows [H-contentRows, H) on screen with
+    // the cursor parked one row below the last of them — so the next frame's
+    // bookkeeping needs no special case for having come through a reset.
+    const height = frame.screen.height;
+    const contentRows = Math.min(height, Math.max(1, frame.viewport.height - 1));
+    const startY = height - contentRows;
+    const screen = new VirtualScreen({ x: 0, y: startY }, frame.viewport.width);
+    renderFrameSlice(screen, frame, startY, height, stylePool, false);
+    return [{ type: 'clearTerminal', reason, debug }, ...screen.diff];
+}
+/**
+ * Anchored tail repaint for shrink-to-fit frames — the fix for the
+ * duplicated-whale/duplicated-transcript family. When growth pushed frame
+ * rows into terminal scrollback and a shrink then brings the frame back
+ * below the viewport, repainting the whole (short) frame from the viewport
+ * top re-prints rows whose originals already sit in scrollback — the user
+ * scrolls up and sees every pre-shrink row twice.
+ *
+ * Two layouts, decided by content:
+ *  - The new frame's top rows are UNCHANGED from the previous frame (the
+ *    common small shrink — a fold, a spinner unmounting): those rows
+ *    already live in scrollback and keep their originals. Erase the
+ *    viewport in place (no 2J — history untouched) and repaint ONLY the
+ *    changed tail, anchored at the viewport BOTTOM so the frame continues
+ *    the scrollback seamlessly. The leading blank band is recorded as
+ *    `anchoredPad` so later frames' viewportY math skips the scrollback
+ *    rows and relative addressing stays consistent (the band scrolls away
+ *    naturally as the next turn grows).
+ *  - The frame's top content CHANGED (a panel collapsing, 38 rows → 2):
+ *    nothing in scrollback represents the new frame — repaint the whole
+ *    short frame top-anchored, matching a fresh render (collapse-shrink's
+ *    contract), pad 0.
+ */
+function shrinkAnchoredRepaint(prev, next, stylePool, scrollbackRows) {
+    // Seam check, not prefix equality: the scrollback's DEEPEST row (old row
+    // skip-1) sits directly above the region we are about to paint — if it
+    // equals the new frame's row at the same index, the frame's lineage is
+    // intact (the shrink removed rows from the bottom region) and the
+    // scrollback originals stay authoritative. Volatile top rows (the
+    // status header's ticking counters) don't matter — only the seam does.
+    // Walk the skip down until the seam matches; 0 means the frame's top
+    // content changed (a collapsing panel) and the whole short frame gets a
+    // top-anchored repaint instead.
+    const width = Math.min(prev.screen.width, next.screen.width);
+    const rowsDiffer = (y) => {
+        if (y >= prev.screen.height || y >= next.screen.height)
+            return true;
+        const po = y * prev.screen.width * 2;
+        const no = y * next.screen.width * 2;
+        for (let x = 0; x < width * 2; x++) {
+            if (prev.screen.cells[po + x] !== next.screen.cells[no + x])
+                return true;
+        }
+        return false;
+    };
+    let skip = Math.min(scrollbackRows, next.screen.height);
+    while (skip > 0 && rowsDiffer(skip - 1))
+        skip -= 1;
+    const viewportHeight = prev.viewport.height;
+    const height = next.screen.height;
+    if (skip <= 0) {
+        // Top-anchored whole-frame repaint — the fresh-render layout.
+        const contentRows = Math.min(height, Math.max(1, viewportHeight - 1));
+        const startY = height - contentRows;
+        const anchor = CURSOR_HOME + eraseToEndOfScreen();
+        const screen = new VirtualScreen({ x: 0, y: startY }, next.viewport.width);
+        renderFrameSlice(screen, next, startY, height, stylePool, false);
+        return { patches: [{ type: 'stdout', content: anchor }, ...screen.diff], anchoredPad: 0 };
+    }
+    const rowsToPaint = Math.max(1, Math.min(height, viewportHeight - 1, height - skip));
+    const startY = height - rowsToPaint;
+    const blankBand = Math.max(0, viewportHeight - 1 - rowsToPaint);
+    const anchor = CURSOR_HOME + eraseToEndOfScreen() + (blankBand > 0 ? cursorDown(blankBand) : '');
+    const screen = new VirtualScreen({ x: 0, y: startY }, next.viewport.width);
+    renderFrameSlice(screen, next, startY, height, stylePool, false);
+    return {
+        patches: [{ type: 'stdout', content: anchor }, ...screen.diff],
+        // Cap at height-1: a seam that matches every row of a very short frame
+        // must not mark the WHOLE frame as scrollback — the last row (the
+        // input area) stays live and repaintable.
+        anchoredPad: Math.min(skip, height - 1),
+    };
+}
+/**
+ * Repaint the visible viewport in place — the main-screen shrink recovery
+ * that replaces fullResetSequence's clearTerminal + whole-frame reprint.
+ *
+ * Precondition (caller-guarded): the cursor is parked on the physical
+ * bottom row (the renderer pins cursor.y = screen.height every main-screen
+ * frame), so the viewport top is exactly viewportHeight-1 rows up. Walk
+ * there, erase to the end of the screen, and repaint the frame's tail
+ * directly into the viewport. Nothing scrolls: no rows are pushed into
+ * (WT semantics) or spliced out of (xterm.js semantics) the terminal
+ * scrollback, so the shrink frames that fire on EVERY turn — thinking
+ * fold, spinner/esc-hint rows unmounting at end of turn, streaming
+ * markdown reflow — stop depositing a full stale UI copy per turn into
+ * the user's scroll history (issues #38 #39 #19).
+ *
+ * Frame-row bookkeeping stays on the steady-state formulas: the repaint
+ * leaves frame rows [H-min(H,V-1), H) on the viewport with the cursor at
+ * frame row H on the physical bottom row — exactly the mapping viewportY
+ * derives (viewport top = H-V+1 when H >= V), so the next frame needs no
+ * special casing. Cost is O(viewport) cells once per shrink frame, well
+ * under the fullReset path it replaces (whole frame + 10000-row scroll).
+ *
+ * Also reused by the viewport re-anchor (requestViewportReanchor), where
+ * the cursor may NOT be exactly on the park row — a third-party write
+ * left it somewhere in the bottom region. The CR + cursorUp(V-1) still
+ * lands on the viewport top because CUU clamps at the top margin, so the
+ * repaint re-syncs the mapping from any bottom-region start. (On legacy
+ * conhost the clamp can drag the viewport instead — see
+ * hasCursorUpViewportYankBug — but only when the cursor starts above the
+ * bottom row, which no known writer produces.)
+ */
+function repaintViewportInPlace(prev, next, stylePool) {
+    return viewportRepaintPatches(prev, next, stylePool, false, 'viewport-bottom');
+}
+/**
+ * Patches that rewrite the visible viewport in place, then paint the frame
+ * tail top-to-bottom. See repaintViewportInPlace for the layout rationale.
+ *
+ * When these patches are APPENDED to an incremental diff (rather than being
+ * the whole frame), the incremental writes may have left an SGR style and/or
+ * an OSC 8 hyperlink open; `resetPrefix` then prepends SGR_RESET + link('')
+ * so the ED0 BCE fill and the slice's style/hyperlink transitions start from
+ * a clean state. In that path the physical cursor is at the frame end, so a
+ * short frame must move up only its visible row count. Moving up V-1 rows
+ * would clamp at the terminal top, erase shell history above the application,
+ * and relocate the application to the top of the viewport.
+ */
+function viewportRepaintPatches(prev, next, stylePool, resetPrefix, origin) {
+    const viewportHeight = prev.viewport.height;
+    const height = next.screen.height;
+    // The bottom viewport row stays reserved for the cursor park; content
+    // occupies at most viewportHeight-1 rows above it (same split as the
+    // steady state, where the park LF materializes one row below the frame).
+    const contentRows = Math.min(height, viewportHeight - 1);
+    const startY = height - contentRows;
+    // Anchor with CSI H (cursor to viewport origin) instead of a RELATIVE
+    // cursor-up walk. The relative form assumed the physical cursor sits
+    // exactly on the park row — an assumption that breaks after a terminal
+    // reflow (a width change rewraps scrollback, shifting the buffer/cursor
+    // bookkeeping by a row or two). The over-shot cursor-up lands ABOVE the
+    // viewport top, and the subsequent erase+repaint writes a full UI copy
+    // into the scrollback (duplicated-history reports). CSI H has absolute
+    // semantics — it always lands on the current viewport's top-left — so the
+    // repaint can never cross into scrollback regardless of cursor drift.
+    // Erase down from there (BCE fill — the SGR reset guarantees the default
+    // background). The erase also blanks the park row, so no stale
+    // prompt/status pixels survive below short content.
+    const anchor = (resetPrefix ? SGR_RESET + LINK_END : '') +
+        CURSOR_HOME +
+        eraseToEndOfScreen();
+    const screen = new VirtualScreen({ x: 0, y: startY }, next.viewport.width);
+    renderFrameSlice(screen, next, startY, height, stylePool, false);
+    return [{ type: 'stdout', content: anchor }, ...screen.diff];
+}
+/**
+ * Render a slice of rows from the frame's screen.
+ * Each row is rendered followed by a newline. Cursor ends at (0, endY).
+ */
+function renderFrameSlice(screen, frame, startY, endY, stylePool, 
+/**
+ * When false (repaint / full-reset paths), advance rows with
+ * CR + cursor-down instead of bare LFs. The repaint paints exactly a
+ * viewport of rows starting at the viewport top; a trailing LF on the
+ * bottom row SCROLLS the terminal, pushing a copy of the just-painted
+ * rows into the scrollback that the cursor bookkeeping never accounted
+ * for — every later relative move lands offset, writing content into
+ * the history (duplicated transcript rows on scroll-up). cursor-down
+ * clamps at the bottom margin instead of scrolling, so the physical
+ * cursor stays exactly where the model expects it.
+ */
+allowScroll = true) {
+    let currentStyleId = stylePool.none;
+    let currentHyperlink = undefined;
+    // Track the styleId of the last rendered cell on this line (-1 if none).
+    // Passed to visibleCellAtIndex to enable fg-only space optimization.
+    let lastRenderedStyleId = -1;
+    const { width: screenWidth, cells, charPool, hyperlinkPool } = frame.screen;
+    let index = startY * screenWidth;
+    for (let y = startY; y < endY; y += 1) {
+        // Advance cursor to this row. With allowScroll, use LF (not CSI CUD /
+        // cursor-down): CSI CUD stops at the viewport bottom margin and cannot
+        // scroll, but LF scrolls the viewport to create new lines. Without this,
+        // when the cursor is at the viewport bottom, moveCursorTo's
+        // cursor-down silently fails, creating a permanent off-by-one
+        // between the virtual cursor and the real terminal cursor.
+        if (screen.cursor.y < y) {
+            const rowsToAdvance = y - screen.cursor.y;
+            if (allowScroll) {
+                screen.txn(prev => {
+                    const patches = new Array(1 + rowsToAdvance);
+                    patches[0] = CARRIAGE_RETURN;
+                    for (let i = 0; i < rowsToAdvance; i++) {
+                        patches[1 + i] = NEWLINE;
+                    }
+                    return [patches, { dx: -prev.x, dy: rowsToAdvance }];
+                });
+            }
+            else {
+                screen.txn(prev => [
+                    [CARRIAGE_RETURN, { type: 'cursorMove', x: 0, y: rowsToAdvance }],
+                    { dx: -prev.x, dy: rowsToAdvance },
+                ]);
+            }
+        }
+        // Reset at start of each line — no cell rendered yet
+        lastRenderedStyleId = -1;
+        for (let x = 0; x < screenWidth; x += 1, index += 1) {
+            // Skip spacers, unstyled empty cells, and fg-only styled spaces that
+            // match the last rendered style (since cursor-forward produces identical
+            // visual result). visibleCellAtIndex handles the optimization internally
+            // to avoid allocating Cell objects for skipped cells.
+            const cell = visibleCellAtIndex(cells, charPool, hyperlinkPool, index, lastRenderedStyleId);
+            if (!cell) {
+                continue;
+            }
+            moveCursorTo(screen, x, y);
+            // Handle hyperlink
+            const targetHyperlink = cell.hyperlink;
+            currentHyperlink = transitionHyperlink(screen.diff, currentHyperlink, targetHyperlink);
+            // Style transition — cached string, zero allocations after warmup
+            const styleStr = stylePool.transition(currentStyleId, cell.styleId);
+            if (writeCellWithStyleStr(screen, cell, styleStr)) {
+                currentStyleId = cell.styleId;
+                lastRenderedStyleId = cell.styleId;
+            }
+        }
+        // Reset styles/hyperlinks before newline so background color doesn't
+        // bleed into the next line when the terminal scrolls. The old code
+        // reset implicitly by writing trailing unstyled spaces; now that we
+        // skip empty cells, we must reset explicitly.
+        currentStyleId = transitionStyle(screen.diff, stylePool, currentStyleId, stylePool.none);
+        currentHyperlink = transitionHyperlink(screen.diff, currentHyperlink, undefined);
+        // CR+LF (or CR+cursor-down for non-scrolling slices) at end of row —
+        // \r resets to column 0. Without \r, the terminal cursor stays at
+        // whatever column content ended (since we skip trailing spaces, this
+        // can be mid-row).
+        if (allowScroll) {
+            screen.txn(prev => [[CARRIAGE_RETURN, NEWLINE], { dx: -prev.x, dy: 1 }]);
+        }
+        else {
+            screen.txn(prev => [
+                [CARRIAGE_RETURN, { type: 'cursorMove', x: 0, y: 1 }],
+                { dx: -prev.x, dy: 1 },
+            ]);
+        }
+    }
+    // Reset any open style/hyperlink at end of slice
+    transitionStyle(screen.diff, stylePool, currentStyleId, stylePool.none);
+    transitionHyperlink(screen.diff, currentHyperlink, undefined);
+    return screen;
+}
+/**
+ * Write a cell with a pre-serialized style transition string (from
+ * StylePool.transition). Inlines the txn logic to avoid closure/tuple/delta
+ * allocations on every cell.
+ *
+ * Returns true if the cell was written, false if skipped (wide char at
+ * viewport edge). Callers MUST gate currentStyleId updates on this — when
+ * skipped, styleStr is never pushed and the terminal's style state is
+ * unchanged. Updating the virtual tracker anyway desyncs it from the
+ * terminal, and the next transition is computed from phantom state.
+ */
+function writeCellWithStyleStr(screen, cell, styleStr) {
+    const cellWidth = cell.width === 1 /* CellWidth.Wide */ ? 2 : 1;
+    const px = screen.cursor.x;
+    const vw = screen.viewportWidth;
+    // Don't write wide chars that would cross the viewport edge.
+    // Single-codepoint chars (CJK) at vw-2 are safe; multi-codepoint
+    // graphemes (flags, ZWJ emoji) need stricter threshold.
+    if (cellWidth === 2 && px < vw) {
+        const threshold = cell.char.length > 2 ? vw : vw + 1;
+        if (px + 2 >= threshold) {
+            return false;
+        }
+    }
+    const diff = screen.diff;
+    if (styleStr.length > 0) {
+        diff.push({ type: 'styleStr', str: styleStr });
+    }
+    const needsCompensation = cellWidth === 2 && needsWidthCompensation(cell.char);
+    // On terminals with old wcwidth tables, a compensated emoji only advances
+    // the cursor 1 column, so the CHA below skips column x+1 without painting
+    // it. Write a styled space there first — on correct terminals the emoji
+    // glyph (width 2) overwrites it harmlessly; on old terminals it fills the
+    // gap with the emoji's background. Also clears any stale content at x+1.
+    // CHA is 1-based, so column px+1 (0-based) is CHA target px+2.
+    if (needsCompensation && px + 1 < vw) {
+        diff.push({ type: 'cursorTo', col: px + 2 });
+        diff.push({ type: 'stdout', content: ' ' });
+        diff.push({ type: 'cursorTo', col: px + 1 });
+    }
+    diff.push({ type: 'stdout', content: cell.char });
+    // Force terminal cursor to correct column after the emoji.
+    if (needsCompensation) {
+        diff.push({ type: 'cursorTo', col: px + cellWidth + 1 });
+    }
+    // Update cursor — mutate in place to avoid Point allocation
+    if (px >= vw) {
+        screen.cursor.x = cellWidth;
+        screen.cursor.y++;
+    }
+    else {
+        screen.cursor.x = px + cellWidth;
+    }
+    return true;
+}
+function moveCursorTo(screen, targetX, targetY) {
+    screen.txn(prev => {
+        const dx = targetX - prev.x;
+        const dy = targetY - prev.y;
+        const inPendingWrap = prev.x >= screen.viewportWidth;
+        // Already there (and not in pending wrap): nothing to emit. Without this
+        // the patch below is returned for a zero-length move, which is a non-empty
+        // diff — it costs a content-free write on every frame that only re-parks
+        // the cursor (exactly what the inline idle tail now does, see #995), and it
+        // breaks fixtures that assert on the final stdout chunk.
+        if (!inPendingWrap && dx === 0 && dy === 0)
+            return [[], { dx: 0, dy: 0 }];
+        // If we're in pending wrap state (cursor.x >= width), use CR
+        // to reset to column 0 on the current line without advancing
+        // to the next line, then issue the cursor movement.
+        if (inPendingWrap) {
+            return [
+                [CARRIAGE_RETURN, { type: 'cursorMove', x: targetX, y: dy }],
+                { dx, dy },
+            ];
+        }
+        // When moving to a different line, use carriage return (\r) to reset to
+        // column 0 first, then cursor move.
+        if (dy !== 0) {
+            return [
+                [CARRIAGE_RETURN, { type: 'cursorMove', x: targetX, y: dy }],
+                { dx, dy },
+            ];
+        }
+        // Standard same-line cursor move
+        return [[{ type: 'cursorMove', x: dx, y: dy }], { dx, dy }];
+    });
+}
+/**
+ * Identify emoji where the terminal's wcwidth may disagree with Unicode.
+ * On terminals with correct tables, the CHA we emit is a harmless no-op.
+ *
+ * Two categories:
+ * 1. Newer emoji (Unicode 12.0+) missing from terminal wcwidth tables.
+ * 2. Text-by-default emoji + VS16 (U+FE0F): the base codepoint is width 1
+ *    in wcwidth, but VS16 triggers emoji presentation making it width 2.
+ *    Examples: ⚔️ (U+2694), ☠️ (U+2620), ❤️ (U+2764).
+ */
+function needsWidthCompensation(char) {
+    const cp = char.codePointAt(0);
+    if (cp === undefined)
+        return false;
+    // U+1FA70-U+1FAFF: Symbols and Pictographs Extended-A (Unicode 12.0-15.0)
+    // U+1FB00-U+1FBFF: Symbols for Legacy Computing (Unicode 13.0)
+    if ((cp >= 0x1fa70 && cp <= 0x1faff) || (cp >= 0x1fb00 && cp <= 0x1fbff)) {
+        return true;
+    }
+    // Text-by-default emoji with VS16: scan for U+FE0F in multi-codepoint
+    // graphemes. Single BMP chars (length 1) and surrogate pairs without VS16
+    // skip this check. VS16 (0xFE0F) can't collide with surrogates (0xD800-0xDFFF).
+    if (char.length >= 2) {
+        for (let i = 0; i < char.length; i++) {
+            if (char.charCodeAt(i) === 0xfe0f)
+                return true;
+        }
+    }
+    return false;
+}
+class VirtualScreen {
+    viewportWidth;
+    // Public for direct mutation by writeCellWithStyleStr (avoids txn overhead).
+    // File-private class — not exposed outside log-update.ts.
+    cursor;
+    diff = [];
+    constructor(origin, viewportWidth) {
+        this.viewportWidth = viewportWidth;
+        this.cursor = { ...origin };
+    }
+    txn(fn) {
+        const [patches, next] = fn(this.cursor);
+        for (const patch of patches) {
+            this.diff.push(patch);
+        }
+        this.cursor.x += next.dx;
+        this.cursor.y += next.dy;
+    }
+}