linecraft 0.2.0 → 0.2.2

package/lib/native/region-renderer.js

@@ -1,1238 +1,569 @@
-// Region management for terminal rendering - TypeScript implementation
-// Optimized for Node.js stdout performance
+import * as fs from 'fs';
+import * as path from 'path';
+import { diffFrames } from './diff';
 import * as ansi from './ansi';
 import { RenderBuffer } from './buffer';
 import { Throttle } from './throttle';
-import { queryCursorPosition } from '../utils/cursor-position';
-import { getTerminalWidth, onResize } from '../utils/terminal';
-import { logToFile as logToFileUtil } from '../utils/debug-log';
-/**
- * TerminalRegion manages a rectangular region of the terminal.
- *
- * The region reserves new lines at the bottom of the terminal and only
- * updates within those reserved lines. This prevents overwriting existing
- * terminal content.
- *
- * Performance optimizations:
- * - Frame diffing to minimize writes
- * - Throttling to limit render frequency
- * - Batched writes to stdout
- * - Efficient string operations
- * - Relative cursor movements (no absolute positioning)
- */
+import { getTerminalHeight as getDefaultTerminalHeight } from '../utils/terminal';
+import { truncateToWidth } from '../utils/text';
 export class RegionRenderer {
     width;
     height;
-    pendingFrame = [];
-    previousFrame = [];
-    renderScheduled = false;
+    pendingFrame;
+    previousFrame;
+    disableRendering;
+    lastRenderedHeight = 0;
+    stdout;
     throttle;
     renderBuffer;
-    stdout;
-    disableRendering;
     permanentlyDisabled;
-    isInitialized = false;
-    initializationPromise = null; // Promise for async initialization
-    resizeCleanup;
-    widthExplicitlySet;
-    savedCursorPosition = false; // Track if we've saved the cursor position
-    autoWrapDisabled = false; // Track if we've disabled terminal auto-wrap
-    startRow = null; // Absolute terminal row where region starts (1-based)
-    visibleRegionTopRow = null; // Terminal row of the top of the visible region (1-based, updated after scrolls)
-    lastRenderedHeight = 0; // Track height from last render to detect changes
-    hasRendered = false; // Track if we've rendered at least once
-    isRendering = false; // Prevent concurrent renders
-    resizeJustHappened = false; // Track if resize happened to re-initialize cursor
-    queriedCursorPosition = null; // Queried position after resize
-    static logFileCleared = false; // Track if log file has been cleared for this process
     onKeepAlive;
-    // Static tracking for exit handler (singleton pattern to prevent memory leak)
+    viewportWidth;
+    viewportHeight;
+    previousViewportFrame;
+    effectiveWidth;
+    autoWrapDisabled = false;
+    inAlternateScreen = false;
+    isRendering = false;
+    renderTimer = null;
+    resizeCleanup;
+    destroyed = false;
+    debugLogPath;
+    debugLogCleared = false;
+    cursorVisible = false;
     static exitHandlerSetup = false;
     static activeRegions = new Set();
     constructor(options = {}) {
-        this.widthExplicitlySet = options.width !== undefined;
-        // CRITICAL: getTerminalWidth() returns (terminal_width - 2) to prevent cursor wrapping
-        // Components receive this as availableWidth and can write up to the full availableWidth
-        const maxSafeWidth = getTerminalWidth();
-        this.width = options.width !== undefined
-            ? Math.min(options.width, maxSafeWidth)
-            : maxSafeWidth;
-        this.height = options.height ?? 1;
-        this.lastRenderedHeight = 0; // Start at 0 - will be set after first render
-        this.hasRendered = false; // Haven't rendered yet
         this.stdout = options.stdout ?? process.stdout;
-        this.permanentlyDisabled = options.disableRendering ?? false;
-        this.disableRendering = this.permanentlyDisabled;
         this.onKeepAlive = options.onKeepAlive;
-        // Initialize frames with empty lines
+        this.viewportWidth = this.readViewportWidth();
+        this.viewportHeight = this.readViewportHeight();
+        this.width = this.viewportWidth;
+        this.height = 1;
         this.pendingFrame = Array(this.height).fill('');
         this.previousFrame = Array(this.height).fill('');
-        this.throttle = new Throttle(60); // Default 60 FPS
+        this.previousViewportFrame = Array(Math.max(1, this.viewportHeight)).fill('');
+        this.throttle = new Throttle(30);
         this.renderBuffer = new RenderBuffer(this.stdout);
-        // Reserve space for the region by printing newlines
-        // Start initialization async (but don't await - it will be awaited on first flush)
+        this.permanentlyDisabled = options.disableRendering ?? false;
+        this.disableRendering = this.permanentlyDisabled;
+        this.debugLogPath = this.resolveDebugLogPath(options.debugLog);
+        this.effectiveWidth = this.viewportWidth;
         if (!this.permanentlyDisabled) {
-            this.initializationPromise = this.initializeRegion();
-        }
-        // Set up resize handling if width was not explicitly set (auto-resize enabled)
-        if (!this.widthExplicitlySet && !this.permanentlyDisabled) {
+            this.initializeTerminalState();
             this.setupResizeHandler();
-        }
-        // Set up automatic cleanup on process exit
-        // This ensures regions are properly cleaned up even if destroy() isn't called
-        // Use singleton pattern to prevent memory leak from multiple listeners
-        if (!this.permanentlyDisabled) {
-            RegionRenderer.setupExitHandler();
-            RegionRenderer.activeRegions.add(this);
+            RegionRenderer.registerRegion(this);
         }
     }
-    /**
-     * Set up process exit handler to automatically clean up all regions
-     * Uses singleton pattern to prevent memory leak from multiple listeners
-     */
-    static setupExitHandler() {
-        // Only set up once globally
-        if (RegionRenderer.exitHandlerSetup) {
-            return;
+    getWidth() {
+        this.width = this.viewportWidth;
+        this.effectiveWidth = this.viewportWidth;
+        return this.width;
+    }
+    getHeight() {
+        return this.height;
+    }
+    async getStartRow() {
+        return 1;
+    }
+    setThrottleFps(fps) {
+        this.throttle.setFps(fps);
+    }
+    setLine(lineNumber, content) {
+        if (lineNumber < 1) {
+            throw new Error('Line numbers start at 1');
         }
-        RegionRenderer.exitHandlerSetup = true;
-        // Cleanup function that destroys all active regions
-        const cleanup = () => {
-            // Destroy all active regions
-            for (const region of RegionRenderer.activeRegions) {
-                if (region.isInitialized) {
-                    region.destroy();
-                }
+        const index = lineNumber - 1;
+        this.ensureFrameSize(index + 1);
+        // Log if we're overwriting non-empty content (potential duplication)
+        if (this.pendingFrame[index] && this.pendingFrame[index].trim().length > 0 && content.trim().length > 0) {
+            const oldContent = this.pendingFrame[index].substring(0, 40);
+            const newContent = content.substring(0, 40);
+            if (oldContent !== newContent) {
+                this.logToFile(`[setLine] WARNING: Overwriting line ${lineNumber} - old: "${oldContent}", new: "${newContent}"`);
             }
-            RegionRenderer.activeRegions.clear();
-        };
-        // Register cleanup on various exit events (only once globally)
-        process.once('exit', cleanup);
-        process.once('SIGINT', cleanup);
-        process.once('SIGTERM', cleanup);
-        // Also handle uncaught exceptions (but don't prevent default behavior)
-        const originalUncaughtException = process.listeners('uncaughtException');
-        process.once('uncaughtException', (error, origin) => {
-            cleanup();
-            // Re-emit if there were other listeners
-            if (originalUncaughtException.length > 0) {
-                originalUncaughtException.forEach((listener) => {
-                    listener(error, origin);
-                });
+            else {
+                this.logToFile(`[setLine] Writing same content to line ${lineNumber}: "${newContent}"`);
             }
-        });
-    }
-    /**
-     * Set up resize event handler to react to terminal size changes
-     */
-    setupResizeHandler() {
-        // If a custom stdout is provided (e.g., for testing),
-        // listen to its resize events. Otherwise, use the global onResize utility.
-        if (this.stdout && this.stdout !== process.stdout) {
-            // Custom stdout - listen to its resize events directly
-            const resizeHandler = () => {
-                // CRITICAL: Don't modify terminal state if region is destroyed
-                // This prevents leaving terminal in bad state after program finishes
-                if (!this.isInitialized) {
-                    return;
-                }
-                // CRITICAL: Always re-disable auto-wrap on resize if region is initialized
-                // Some terminals reset auto-wrap state on resize, so we must re-disable it
-                // This ensures content doesn't reflow automatically when terminal resizes
-                // Write directly to stdout since this happens outside of render cycle
-                if (!this.disableRendering && this.isInitialized) {
-                    this.stdout.write(ansi.DISABLE_AUTO_WRAP);
-                    this.autoWrapDisabled = true;
-                }
-                // Only auto-resize if width wasn't explicitly set by the user
-                if (!this.widthExplicitlySet) {
-                    const oldWidth = this.width;
-                    // Read width directly from the custom stdout
-                    // CRITICAL: getTerminalWidth() returns (terminal_width - 2) to prevent cursor wrapping
-                    const actualWidth = getTerminalWidth();
-                    // Only update if it actually changed
-                    if (actualWidth !== oldWidth) {
-                        this.width = actualWidth;
-                        // Don't auto-render here - the high-level API (or user code) will handle rebuilding
-                        // grid layouts and other dynamic content with the new width
-                        // This prevents rendering broken layouts before they're rebuilt
-                    }
-                }
-                // CRITICAL: Mark that resize happened - cursor position may be invalid
-                // We'll re-initialize cursor position on next render
-                this.resizeJustHappened = true;
-                this.savedCursorPosition = false;
-                // CRITICAL: Trigger re-render via high-level API to update content with new width
-                // This prevents content from being rendered over (like spacebar prompt)
-                // The old code was a single class, so it didn't need this callback
-                // But our split architecture needs to notify the high-level API to re-render
-                if (this.onKeepAlive) {
-                    this.onKeepAlive();
-                }
-            };
-            this.stdout.on('resize', resizeHandler);
-            this.resizeCleanup = () => {
-                this.stdout.off('resize', resizeHandler);
-            };
         }
-        else {
-            // Use the global onResize utility (for real process.stdout)
-            this.resizeCleanup = onResize((newWidth, newHeight) => {
-                // CRITICAL: Don't modify terminal state if region is destroyed
-                // This prevents leaving terminal in bad state after program finishes
-                if (!this.isInitialized) {
-                    return;
-                }
-                // CRITICAL: Always re-disable auto-wrap on resize if region is initialized
-                // Some terminals reset auto-wrap state on resize, so we must re-disable it
-                // This ensures content doesn't reflow automatically when terminal resizes
-                // Write directly to stdout since this happens outside of render cycle
-                if (!this.disableRendering && this.isInitialized) {
-                    this.stdout.write(ansi.DISABLE_AUTO_WRAP);
-                    this.autoWrapDisabled = true;
-                }
-                // Only auto-resize if width wasn't explicitly set by the user
-                if (!this.widthExplicitlySet) {
-                    const oldWidth = this.width;
-                    // Read width directly from stdout to ensure we get the latest value
-                    // Node.js updates process.stdout.columns when resize happens
-                    // CRITICAL: getTerminalWidth() returns (terminal_width - 2) to prevent cursor wrapping
-                    const actualWidth = getTerminalWidth();
-                    // Only update if it actually changed
-                    if (actualWidth !== oldWidth) {
-                        this.width = actualWidth;
-                        // Don't auto-render here - the high-level API (or user code) will handle rebuilding
-                        // flex layouts and other dynamic content with the new width
-                        // This prevents rendering broken layouts before they're rebuilt
-                    }
-                }
-                // CRITICAL: Mark that resize happened - cursor position may be invalid
-                // We'll query the actual cursor position and recalibrate
-                // NOTE: Don't clear savedCursorPosition - we'll handle it in renderNow()
-                // by not restoring it when resizeJustHappened=true
-                this.logToFile(`[resize handler] SETTING resizeJustHappened=true`);
-                this.resizeJustHappened = true;
-                // DON'T clear savedCursorPosition - it might still be valid, and we'll handle
-                // the resize case in renderNow() by not restoring it
-                // CRITICAL: Query cursor position after resize to use actual position instead of saved
-                // The saved position becomes invalid when terminal scrolls
-                // NOTE: Disabled for now - the polling interferes with stdin (causes hang)
-                // this.queryCursorPositionAfterResize();
-                // Also poll multiple times for debugging
-                // NOTE: Disabled for now - the polling interferes with stdin (causes hang)
-                // this.pollCursorPositionAfterResize();
-                // CRITICAL: Trigger re-render via high-level API to update content with new width
-                // This prevents content from being rendered over (like spacebar prompt)
-                // The old code was a single class, so it didn't need this callback
-                // But our split architecture needs to notify the high-level API to re-render
-                // NOTE: Disabled cursor position querying for now - it was causing issues
-                // The queried position might be at the bottom of the screen, not where the region actually is
-                // if (this.onKeepAlive) {
-                //   this.onKeepAlive();
-                // }
-                // TODO: Re-enable cursor querying once we figure out how to use it correctly
-                if (this.onKeepAlive) {
-                    this.onKeepAlive();
-                }
-            });
+        this.pendingFrame[index] = content;
+        if (lineNumber > this.height) {
+            this.height = lineNumber;
         }
+        this.scheduleRender();
     }
-    /**
-     * Initialize the region by reserving new lines at the bottom of the terminal.
-     * This appends new lines so the region doesn't overwrite existing content.
-     *
-     * Also disables terminal auto-wrap so we can manage all wrapping ourselves.
-     */
-    async initializeRegion() {
-        // Disable terminal auto-wrap - we'll manage all wrapping ourselves
-        // This makes reflow math much easier because we control it, not the terminal
-        // IMPORTANT: Write directly to stdout and flush immediately so it takes effect before any content
-        if (!this.disableRendering && !this.autoWrapDisabled) {
-            this.stdout.write(ansi.DISABLE_AUTO_WRAP);
-            this.autoWrapDisabled = true;
-        }
-        if (this.isInitialized)
+    updateLines(updates) {
+        if (updates.length === 0) {
             return;
-        // CRITICAL: Query cursor position BEFORE printing newlines
-        // This establishes where the region starts in terminal space
-        // We query BEFORE rendering so stdin is restored before waitForSpacebar
-        let queriedRow = null;
-        if (process.stdin.isTTY && process.stdout.isTTY) {
-            const queryStartTime = Date.now();
-            try {
-                this.logToFile(`[initializeRegion] QUERYING cursor position before printing newlines (timestamp: ${new Date().toISOString()})...`);
-                const pos = await queryCursorPosition(500);
-                const queryEndTime = Date.now();
-                const queryDuration = queryEndTime - queryStartTime;
-                queriedRow = pos.row;
-                // CRITICAL: Start two lines BELOW the cursor to avoid overwriting the prompt and PNPM output
-                // The cursor is at the prompt line, and there may be PNPM output on the line above or at the cursor
-                // So we start the region two lines below to be safe
-                this.startRow = pos.row + 2;
-                this.logToFile(`[initializeRegion] ✓ GOT cursor position back: row=${pos.row}, col=${pos.col}, setting startRow=${this.startRow} (two lines below cursor to avoid overwriting prompt and PNPM output, query took ${queryDuration}ms, timestamp: ${new Date().toISOString()})`);
-                // CRITICAL: At this point, queryCursorPosition has cleaned up and restored stdin
-                // stdin should be in a clean state for waitForSpacebar
-            }
-            catch (err) {
-                const queryEndTime = Date.now();
-                const queryDuration = queryEndTime - queryStartTime;
-                // Query failed - estimate from terminal height
-                const terminalHeight = process.stdout.isTTY && process.stdout.rows ? process.stdout.rows : 24;
-                this.startRow = terminalHeight - this.height + 1;
-                this.logToFile(`[initializeRegion] ✗ Cursor query FAILED after ${queryDuration}ms: ${err instanceof Error ? err.message : String(err)}, estimating startRow=${this.startRow} (timestamp: ${new Date().toISOString()})`);
-            }
         }
-        else {
-            // Not a TTY - estimate
-            const terminalHeight = process.stdout.isTTY && process.stdout.rows ? process.stdout.rows : 24;
-            this.startRow = terminalHeight - this.height + 1;
-            this.logToFile(`[initializeRegion] Not a TTY, estimating startRow=${this.startRow} (timestamp: ${new Date().toISOString()})`);
-        }
-        this.isInitialized = true;
-        // CRITICAL: Position to startRow before printing newlines
-        // We queried the cursor position and set startRow = queriedRow + 2
-        // After query cleanup, the cursor should still be at approximately the queried position
-        // So we need to move down (startRow - queriedRow) = 2 lines to get to startRow
-        if (queriedRow !== null) {
-            const linesToMoveDown = this.startRow - queriedRow;
-            if (linesToMoveDown > 0) {
-                this.stdout.write(ansi.moveCursorDown(linesToMoveDown));
-                this.logToFile(`[initializeRegion] Moved down ${linesToMoveDown} lines to position at startRow=${this.startRow} (queriedRow=${queriedRow})`);
+        for (const { lineNumber, content } of updates) {
+            if (lineNumber < 1) {
+                throw new Error('Line numbers start at 1');
+            }
+            const index = lineNumber - 1;
+            this.ensureFrameSize(index + 1);
+            this.pendingFrame[index] = content;
+            if (lineNumber > this.height) {
+                this.height = lineNumber;
             }
         }
-        // Reserve space by printing newlines (this moves cursor down)
-        // Each newline reserves one line for the region
-        // The region starts where the cursor is BEFORE printing newlines (which is now at startRow)
-        // After printing newlines, we're at the line after the region
-        for (let i = 0; i < this.height; i++) {
-            this.stdout.write('\n');
-        }
-        // After printing newlines, cursor is at the start of the line after the region
-        // But we want to save at the START of the LAST line (to match where we save after rendering)
-        // So move up one line to get to the start of the last line
-        if (this.height > 0) {
-            this.stdout.write(ansi.moveCursorUp(1));
-        }
-        this.stdout.write(ansi.MOVE_TO_START_OF_LINE);
-        // Now we're at the start of the last line - save this position
-        // Note: After rendering (when there's content), we save at the END of content
-        // But for initialization, we're creating empty lines, so start of line is appropriate
-        this.stdout.write(ansi.SAVE_CURSOR);
-        this.savedCursorPosition = true;
+        this.scheduleRender();
+    }
+    set(content) {
+        const lines = content.split('\n');
+        this.pendingFrame = [...lines];
+        this.previousFrame = new Array(lines.length).fill('');
+        this.height = lines.length;
+        this.scheduleRender();
     }
-    /**
-     * Query cursor position after resize and store it for use in rendering
-     * This helps us position correctly when the saved cursor position is invalid
-     */
-    async queryCursorPositionAfterResize() {
-        if (this.disableRendering || !process.stdin.isTTY || !process.stdout.isTTY) {
-            return; // Can't query if not a TTY
+    getLine(lineNumber) {
+        if (lineNumber < 1) {
+            throw new Error('Line numbers start at 1');
         }
-        try {
-            // Query cursor position after a small delay to let resize settle
-            await new Promise(resolve => setTimeout(resolve, 50));
-            const pos = await queryCursorPosition(500);
-            this.queriedCursorPosition = pos;
-            this.logToFile(`[cursor query] After resize - queried cursor at row=${pos.row}, col=${pos.col}`);
+        return this.pendingFrame[lineNumber - 1] ?? '';
+    }
+    clearLine(lineNumber) {
+        if (lineNumber < 1) {
+            throw new Error('Line numbers start at 1');
         }
-        catch (err) {
-            this.logToFile(`[cursor query] Failed to query cursor position: ${err instanceof Error ? err.message : String(err)}`);
-            this.queriedCursorPosition = null;
+        const index = lineNumber - 1;
+        if (index >= this.pendingFrame.length) {
+            return;
         }
+        this.pendingFrame[index] = '';
+        this.scheduleRender();
     }
-    /**
-     * Poll cursor position multiple times after resize to understand if it's moving
-     * This helps debug cursor position inconsistencies on resize
-     */
-    pollCursorPositionAfterResize() {
-        if (this.disableRendering || !process.stdin.isTTY || !process.stdout.isTTY) {
-            return; // Can't poll if not a TTY
+    clear() {
+        for (let i = 0; i < this.pendingFrame.length; i++) {
+            this.pendingFrame[i] = '';
         }
-        let pollCount = 0;
-        const maxPolls = 10; // Poll 10 times over ~1 second
-        const pollInterval = 100; // 100ms between polls
-        const poll = async () => {
-            try {
-                const pos = await queryCursorPosition(500); // 500ms timeout per poll
-                pollCount++;
-                this.logToFile(`[cursor poll ${pollCount}/${maxPolls}] After resize - cursor at row=${pos.row}, col=${pos.col}`);
-                // After first few polls, trigger a redraw, then continue polling
-                // This helps us see if the cursor position changes after redraw
-                if (pollCount === 3 && this.onKeepAlive) {
-                    this.logToFile(`[cursor poll] Triggering redraw after 3 polls (cursor was at row=${pos.row}, col=${pos.col})`);
-                    this.onKeepAlive();
-                    // Wait a bit for redraw to complete, then continue polling
-                    setTimeout(() => {
-                        if (pollCount < maxPolls) {
-                            setTimeout(poll, pollInterval);
-                        }
-                    }, 100); // Give redraw more time to complete
-                }
-                else if (pollCount < maxPolls) {
-                    setTimeout(poll, pollInterval);
-                }
-                else {
-                    this.logToFile(`[cursor poll] Finished polling after ${maxPolls} attempts`);
-                }
-            }
-            catch (err) {
-                pollCount++;
-                this.logToFile(`[cursor poll ${pollCount}/${maxPolls}] Failed to query cursor position: ${err instanceof Error ? err.message : String(err)}`);
-                if (pollCount < maxPolls) {
-                    setTimeout(poll, pollInterval);
-                }
-            }
-        };
-        // Start polling after a small delay to let resize settle
-        setTimeout(() => {
-            this.logToFile(`[cursor poll] Starting cursor position polling after resize`);
-            poll();
-        }, 10);
+        this.scheduleRender();
     }
-    logToFile(message) {
-        logToFileUtil(message);
+    async flush() {
+        await this.renderNow();
     }
-    /**
-     * Strip ANSI escape codes from a string
-     */
-    stripAnsi(str) {
-        return str.replace(/\x1b\[[0-9;]*m/g, '');
+    expandTo(newHeight) {
+        if (newHeight <= this.height) {
+            return;
+        }
+        this.ensureFrameSize(newHeight);
+        this.height = newHeight;
     }
-    /**
-     * Get terminal height, with fallback
-     */
-    getTerminalHeight() {
-        return this.stdout.isTTY && this.stdout.rows
-            ? this.stdout.rows
-            : 24; // fallback
+    setHeight(height) {
+        this.height = height;
     }
-    /**
-     * Truncate content to maxWidth while preserving ANSI codes
-     * Only truncates if content is significantly longer (more than 2 chars) as a safety measure
-     */
-    truncateContent(content, maxWidth) {
-        const plainContent = this.stripAnsi(content);
-        // CRITICAL: Never write exactly maxWidth characters - it puts cursor at last column
-        // Writing exactly maxWidth (e.g., 71) puts cursor at column maxWidth+1 (e.g., 72 = terminal width)
-        // This can cause cursor positioning issues. Always truncate to maxWidth - 1
-        const safeMaxWidth = maxWidth - 1;
-        if (plainContent.length <= safeMaxWidth) {
-            return content;
+    shrinkFrame(startIndex, count) {
+        this.pendingFrame.splice(startIndex, count);
+        if (this.previousFrame.length >= startIndex + count) {
+            this.previousFrame.splice(startIndex, count);
+        }
+        // Clear previousViewportFrame so next render recalculates from scratch
+        // This ensures deleted lines are properly handled
+        this.previousViewportFrame = [];
+    }
+    async destroy(clearFirst = false) {
+        if (this.destroyed) {
+            return;
         }
-        // Find where to cut while preserving ANSI codes
-        let visualPos = 0;
-        let charPos = 0;
-        while (charPos < content.length && visualPos < safeMaxWidth) {
-            if (content[charPos] === '\x1b') {
-                // Skip ANSI code
-                let ansiEnd = charPos + 1;
-                while (ansiEnd < content.length) {
-                    if (content[ansiEnd] === 'm') {
-                        ansiEnd++;
-                        break;
-                    }
-                    if ((content[ansiEnd] >= '0' && content[ansiEnd] <= '9') ||
-                        content[ansiEnd] === ';' ||
-                        content[ansiEnd] === '[') {
-                        ansiEnd++;
-                    }
-                    else {
-                        break;
-                    }
-                }
-                charPos = ansiEnd;
-            }
-            else {
-                charPos++;
-                visualPos++;
-            }
+        this.destroyed = true;
+        RegionRenderer.activeRegions.delete(this);
+        if (this.renderTimer) {
+            clearTimeout(this.renderTimer);
+            this.renderTimer = null;
         }
-        return content.substring(0, charPos);
-    }
-    /**
-     * Clear the current line and move to start
-     */
-    clearCurrentLine() {
-        this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-        this.renderBuffer.write(ansi.CLEAR_LINE);
-        this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-    }
-    /**
-     * Move to top-left of region and save cursor position
-     */
-    moveToTopLeftAndSave(linesToRender, context = '') {
-        // After rendering, we're at the end of the last rendered line
-        // To get to the top-left (start of first line), we need to move up (linesToRender - 1) lines
-        // Then move to start of line
-        // CRITICAL: With auto-wrap disabled, the cursor stays on the same line after writing
-        // So if we rendered 1 line, we're on line 1 (at the end), and we move up 0 lines
-        // If we rendered N lines, we're on line N (at the end), and we move up (N - 1) lines
-        const linesToMoveUp = linesToRender > 1 ? linesToRender - 1 : 0;
-        this.logToFile(`[moveToTopLeftAndSave] linesToRender=${linesToRender}, moving up ${linesToMoveUp} lines to get to top-left (after rendering, cursor is at end of last line)`);
-        if (linesToMoveUp > 0) {
-            this.renderBuffer.write(ansi.moveCursorUp(linesToMoveUp));
+        if (this.resizeCleanup) {
+            this.resizeCleanup();
+            this.resizeCleanup = undefined;
         }
-        this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-        this.renderBuffer.write(ansi.SAVE_CURSOR);
-        this.savedCursorPosition = true;
-        if (context) {
-            this.logToFile(`[renderNow] Saved cursor at top-left ${context}`);
+        if (this.permanentlyDisabled) {
+            return;
         }
-        else {
-            this.logToFile(`[renderNow] Saved cursor at top-left of region (linesToRender=${linesToRender})`);
+        if (!clearFirst) {
+            await this.renderNow();
         }
+        this.leaveAlternateScreen(clearFirst);
+        this.pendingFrame = [];
+        this.previousFrame = [];
+        this.previousViewportFrame = [];
     }
-    /**
-     * Check if content has changed between previous and pending frames
-     */
-    hasContentChanged() {
-        const contentChanged = this.previousFrame.length !== this.pendingFrame.length ||
-            this.previousFrame.some((line, i) => {
-                const prevLine = this.stripAnsi(line);
-                const pendingLine = this.stripAnsi(this.pendingFrame[i] ?? '');
-                if (prevLine !== pendingLine) {
-                    // Log the first difference found for debugging
-                    if (i < 5) { // Only log first few differences to avoid spam
-                        this.logToFile(`[hasContentChanged] Difference at index ${i}: prev="${prevLine.substring(0, 40)}" vs pending="${pendingLine.substring(0, 40)}"`);
-                    }
-                    return true;
-                }
-                return false;
-            });
-        const heightChanged = this.height !== this.lastRenderedHeight;
-        return { contentChanged, heightChanged };
-    }
-    /**
-     * Expand region to accommodate more lines
-     */
-    expandTo(newHeight) {
-        this.logToFile(`[expandTo] CALLED: oldHeight=${this.height} newHeight=${newHeight} lastRenderedHeight=${this.lastRenderedHeight} isInitialized=${this.isInitialized} disableRendering=${this.disableRendering}`);
-        const oldHeight = this.height;
-        this.height = newHeight;
-        // Expand pending frame
-        while (this.pendingFrame.length < newHeight) {
-            this.pendingFrame.push('');
+    logToFile(message) {
+        if (!this.debugLogPath) {
+            return;
         }
-        // CRITICAL: Only expand previousFrame if we're actually rendering
-        // previousFrame should represent what was actually rendered, not what we plan to render
-        // If disableRendering=true, we haven't rendered yet, so don't expand previousFrame
-        // This prevents false negatives in content-change detection
-        if (!this.disableRendering) {
-            while (this.previousFrame.length < newHeight) {
-                this.previousFrame.push('');
+        try {
+            if (!this.debugLogCleared) {
+                fs.writeFileSync(this.debugLogPath, '# Linecraft Debug Log\n# Debug output from RegionRenderer\n\n', 'utf8');
+                this.debugLogCleared = true;
             }
+            const timestamp = new Date().toISOString();
+            fs.appendFileSync(this.debugLogPath, `[${timestamp}] ${message}\n`, 'utf8');
         }
-        // If we need more lines and region is initialized, reserve additional space
-        // CRITICAL: Only expand if height actually increased AND we haven't already expanded to this height
-        // This prevents writing newlines multiple times on resize when height hasn't changed
-        if (this.isInitialized && newHeight > oldHeight) {
-            const terminalHeight = this.getTerminalHeight();
-            const additionalLines = newHeight - oldHeight;
-            // CRITICAL: If rendering was permanently disabled (tests), never write to stdout
-            if (this.permanentlyDisabled) {
-                this.logToFile(`[expandTo] Rendering permanently disabled - skipping newline writes but tracking height (${this.lastRenderedHeight} -> ${newHeight})`);
-                this.lastRenderedHeight = newHeight;
-                return;
-            }
-            // Even if rendering is temporarily disabled (batching), we still need to reserve space
-            // Only print newlines if the region still fits in viewport
-            const shouldReserveLines = oldHeight < terminalHeight && this.lastRenderedHeight < newHeight;
-            this.logToFile(`[expandTo] oldHeight=${oldHeight} newHeight=${newHeight} lastRenderedHeight=${this.lastRenderedHeight} terminalHeight=${terminalHeight} shouldReserveLines=${shouldReserveLines} disableRendering=${this.disableRendering}`);
-            if (shouldReserveLines) {
-                this.logToFile(`[expandTo] WRITING ${additionalLines} newlines (reserving space even though disableRendering may be ${this.disableRendering})`);
-                for (let i = 0; i < additionalLines; i++) {
-                    this.stdout.write('\n');
-                }
-                if (newHeight > 0) {
-                    this.stdout.write(ansi.moveCursorUp(1));
-                }
-                this.stdout.write(ansi.MOVE_TO_START_OF_LINE);
-                this.stdout.write(ansi.SAVE_CURSOR);
-                this.savedCursorPosition = true;
-                this.logToFile(`[expandTo] UPDATING lastRenderedHeight from ${this.lastRenderedHeight} to ${newHeight} (after writing newlines)`);
-                this.lastRenderedHeight = newHeight;
-            }
-            else {
-                this.logToFile(`[expandTo] Region already exceeds viewport or already reserved at this height - skipping newline writes`);
-            }
+        catch {
+            // ignore logging failures
         }
     }
-    /**
-     * Get a single line (1-based line numbers)
-     * Returns empty string if line doesn't exist
-     */
-    getLine(lineNumber) {
-        if (lineNumber < 1) {
-            throw new Error('Line numbers start at 1');
-        }
-        const lineIndex = lineNumber - 1;
-        if (lineIndex >= this.pendingFrame.length) {
-            return '';
-        }
-        return this.pendingFrame[lineIndex] || '';
+    static registerRegion(region) {
+        RegionRenderer.activeRegions.add(region);
+        RegionRenderer.setupExitHandler();
     }
-    /**
-     * Set a single line (1-based line numbers)
-     *
-     * Note: With auto-wrap disabled, we manage all wrapping ourselves.
-     * This method sets a single line - if content needs to wrap, it should
-     * be handled by the component layer (col, flex, etc.) before calling this.
-     */
-    setLine(lineNumber, content) {
-        if (lineNumber < 1) {
-            throw new Error('Line numbers start at 1');
-        }
-        const lineIndex = lineNumber - 1;
-        // CRITICAL: Don't expand beyond current height if height was explicitly set
-        // The region.set() method for components sets the height explicitly,
-        // so we should not expand here. Only expand if we're in "auto-expand" mode.
-        // For now, we'll allow expansion but the caller (region.set) will truncate after rendering.
-        if (lineIndex >= this.height) {
-            this.expandTo(lineIndex + 1);
-            // Update height to match
-            this.height = lineIndex + 1;
-        }
-        // Ensure pending frame has enough lines
-        while (this.pendingFrame.length <= lineIndex) {
-            this.pendingFrame.push('');
+    static setupExitHandler() {
+        if (RegionRenderer.exitHandlerSetup) {
+            return;
         }
-        // Update the line
-        this.pendingFrame[lineIndex] = content;
-        // Schedule render
-        this.scheduleRender();
+        RegionRenderer.exitHandlerSetup = true;
+        const cleanup = () => {
+            for (const region of RegionRenderer.activeRegions) {
+                region.destroy(true).catch(() => { });
+            }
+            RegionRenderer.activeRegions.clear();
+        };
+        process.once('exit', cleanup);
+        process.once('SIGINT', cleanup);
+        process.once('SIGTERM', cleanup);
     }
-    /**
-     * Set entire content (multiple lines with \n separators)
-     */
-    set(content) {
-        // Split by newlines
-        const lines = content.split('\n');
-        // Expand region if needed
-        if (lines.length > this.height) {
-            this.expandTo(lines.length);
-        }
-        // Update all lines in pending frame
-        // If new content has fewer lines than current height, clear the extra lines
-        this.pendingFrame = [...lines];
-        // Ensure frame is the right size - pad with empty strings if needed
-        while (this.pendingFrame.length < this.height) {
+    ensureFrameSize(size) {
+        while (this.pendingFrame.length < size) {
             this.pendingFrame.push('');
         }
-        // If we shrunk (fewer lines than before), clear the extra lines in previous frame too
-        // This ensures the diff algorithm will detect them as needing to be cleared
-        if (lines.length < this.previousFrame.length) {
-            for (let i = lines.length; i < this.previousFrame.length; i++) {
-                this.previousFrame[i] = this.previousFrame[i] || '';
-            }
+        while (this.previousFrame.length < size) {
+            this.previousFrame.push('');
         }
-        // Schedule render
-        this.scheduleRender();
     }
-    /**
-     * Schedule a render (respects throttle)
-     */
     scheduleRender() {
-        if (this.disableRendering) {
-            // CRITICAL: Don't copy pendingFrame to previousFrame when disableRendering=true
-            // previousFrame should represent what was actually rendered, not what we plan to render
-            // If we copy here, content-change detection will fail because previousFrame will match pendingFrame
-            // The copy will happen after actual rendering in renderNow() or copyPendingToPrevious()
+        if (this.disableRendering || this.permanentlyDisabled || this.destroyed) {
+            return;
+        }
+        if (this.renderTimer) {
             return;
         }
         if (this.throttle.shouldRender()) {
-            // Note: renderNow() is async but we don't await here - it's scheduled via throttle
-            // The actual render will happen asynchronously
             void this.renderNow();
+            return;
         }
-        else {
-            this.renderScheduled = true;
-        }
-    }
-    /**
-     * Copy pending frame to previous frame
-     */
-    copyPendingToPrevious() {
-        // Use spread operator for efficient shallow copy
-        this.previousFrame = [...this.pendingFrame];
+        const delay = Math.max(0, this.throttle.timeUntilNextFrame());
+        this.renderTimer = setTimeout(() => {
+            this.renderTimer = null;
+            void this.renderNow();
+        }, delay);
     }
-    /**
-     * Render immediately (bypasses throttle)
-     * Uses relative cursor movements to update only within reserved lines
-     */
     async renderNow() {
+        if (this.destroyed || this.permanentlyDisabled) {
+            return;
+        }
         if (this.disableRendering) {
             this.copyPendingToPrevious();
             return;
         }
-        // CRITICAL: Prevent concurrent renders
-        // If we're already rendering, skip this render (the current render will show the latest state)
         if (this.isRendering) {
             return;
         }
         this.isRendering = true;
+        this.renderTimer = null;
         try {
-            // CRITICAL: Ensure region is initialized before rendering
-            // Await initialization if it's in progress (this ensures cursor query completes and stdin is restored)
-            if (!this.isInitialized && this.initializationPromise) {
-                await this.initializationPromise;
-            }
-            else if (!this.isInitialized) {
-                // Shouldn't happen, but fallback
-                await this.initializeRegion();
-            }
-            // CRITICAL: Always disable auto-wrap before every render
-            // Some terminals reset this state, or other code might enable it
-            // We MUST write it directly to stdout (not to render buffer) so it takes effect immediately
-            // Node.js stdout.write() is synchronous and blocks until written, so it's effectively flushed
-            if (!this.disableRendering) {
-                // Write directly to stdout (bypasses render buffer) to ensure immediate effect
-                this.stdout.write(ansi.DISABLE_AUTO_WRAP);
-                this.autoWrapDisabled = true;
-            }
-            // CRITICAL: Check if content has actually changed before rendering
-            // This prevents unnecessary re-renders that cause duplicates
-            const { contentChanged, heightChanged } = this.hasContentChanged();
-            // Log detailed comparison to understand why content is changing
-            if (contentChanged && this.hasRendered) {
-                const firstDiffIndex = this.previousFrame.findIndex((line, i) => {
-                    const prevLine = this.stripAnsi(line);
-                    const pendingLine = this.stripAnsi(this.pendingFrame[i] ?? '');
-                    return prevLine !== pendingLine;
-                });
-                const prevLine = firstDiffIndex >= 0 ? this.stripAnsi(this.previousFrame[firstDiffIndex]) : 'N/A';
-                const pendingLine = firstDiffIndex >= 0 ? this.stripAnsi(this.pendingFrame[firstDiffIndex] ?? '') : 'N/A';
-                this.logToFile(`[renderNow] contentChanged=true (first diff at index ${firstDiffIndex})`);
-                this.logToFile(`[renderNow]   prev[${firstDiffIndex}]: "${prevLine.substring(0, 80)}..."`);
-                this.logToFile(`[renderNow]   pending[${firstDiffIndex}]: "${pendingLine.substring(0, 80)}..."`);
-            }
-            this.logToFile(`[renderNow] contentChanged=${contentChanged} heightChanged=${heightChanged} previousFrame.length=${this.previousFrame.length} pendingFrame.length=${this.pendingFrame.length} resizeJustHappened=${this.resizeJustHappened}`);
-            // CRITICAL: Skip render if content and height haven't changed (unless it's the first render)
-            // If only height changed but content hasn't, we still need to render to write newlines
-            // for the new lines. But if both are unchanged, we can skip.
-            if (this.hasRendered && !contentChanged && !heightChanged) {
-                // Content and height are static - skip render to prevent duplicates
-                this.logToFile(`[renderNow] SKIPPING render - content and height unchanged`);
-                this.isRendering = false;
-                return;
-            }
-            // If content hasn't changed but height changed, we still need to render
-            // to write newlines for the new lines, but we can optimize by not re-rendering
-            // existing lines that haven't changed. However, for simplicity, we'll render
-            // everything and let the newline logic handle it.
-            // If resize happened, reset the flag after we've checked content
-            if (this.resizeJustHappened) {
-                this.logToFile(`[renderNow] NOT skipping render - contentChanged=${contentChanged} heightChanged=${heightChanged}`);
-            }
-            // Hide cursor in render buffer too (for consistency)
-            this.renderBuffer.write(ansi.HIDE_CURSOR);
-            // CRITICAL: When region exceeds viewport, we can only render visible lines
-            // Get terminal height to determine which lines are visible
-            const terminalHeight = this.getTerminalHeight();
-            const regionExceedsViewport = this.height > terminalHeight;
-            // CRITICAL: On first render (!hasRendered), we're already at the end of the region from initializeRegion().
-            // On resize (resizeJustHappened), we need to restore to saved position to get back to the region.
-            // On subsequent normal renders, restore to saved position UNLESS region exceeds viewport.
-            // When region exceeds viewport, the saved position is in scrollback, and restoring
-            // then moving up would cause us to write outside the region.
-            if (!this.hasRendered) {
-                // First render - we're at the start of the last line from initializeRegion()
-                // CRITICAL: We know the region starts at startRow (absolute terminal row)
-                // After initialization, we're at startRow + height (the line after the region)
-                // We need to position to startRow to begin rendering
-                this.logToFile(`[renderNow] First render - region starts at terminal row ${this.startRow}, currently at row ${this.startRow !== null ? this.startRow + this.height : 'unknown'} (after initialization)`);
-                // CRITICAL: Only write a newline at the bottom if the region exceeds viewport
-                // If region fits in viewport, just move up to the first line and paint
-                // The newline-at-bottom logic is only needed when expanding past viewport
-                if (regionExceedsViewport) {
-                    // Region exceeds viewport: we need to render only the visible lines (last terminalHeight lines)
-                    // Calculate which lines are visible
-                    const visibleStartLineIndex = this.height - terminalHeight;
-                    this.logToFile(`[renderNow] First render - region exceeds viewport, rendering only visible lines (startLineIndex=${visibleStartLineIndex}, linesToRender=${terminalHeight})`);
-                    // Write newline at bottom first to scroll everything up
-                    // This ensures we're not overwriting anything above the region
-                    this.renderBuffer.write('\n');
-                    // After writing newline, we're at startRow + height (one line below the region)
-                    // We want to position to startRow + visibleStartLineIndex (start of visible region)
-                    // So we need to move up: (startRow + height) - (startRow + visibleStartLineIndex) = height - visibleStartLineIndex = terminalHeight
-                    if (terminalHeight > 0) {
-                        this.renderBuffer.write(ansi.moveCursorUp(terminalHeight));
+            this.ensureTerminalState();
+            const frame = this.buildViewportFrame();
+            // CRITICAL: If previousViewportFrame is empty (e.g., on resize), do a full redraw
+            // On resize, viewport dimensions change and content may wrap differently,
+            // causing the viewport to show different logical lines. Since we control all rendering,
+            // we can simply clear and redraw the entire viewport fresh.
+            if (this.previousViewportFrame.length === 0) {
+                const viewportHeight = Math.max(1, this.viewportHeight);
+                const normalized = this.getEffectiveFrame();
+                this.logToFile(`[renderNow] FULL REDRAW - viewportHeight: ${viewportHeight}, frame.length: ${frame.length}, normalized.length: ${normalized.length}, height: ${this.height}`);
+                this.logToFile(`[renderNow] Frame content (first 5): ${frame.slice(0, 5).map((l, i) => `[${i}]: "${l.substring(0, 50)}"`).join(', ')}`);
+                this.logToFile(`[renderNow] Frame content (last 5): ${frame.slice(-5).map((l, i) => `[${frame.length - 5 + i}]: "${l.substring(0, 50)}"`).join(', ')}`);
+                // Full redraw: clear and write all viewport lines fresh
+                // Instead of ERASE_SCREEN (which might have issues during resize),
+                // we clear each line individually for more reliable behavior
+                this.renderBuffer.write(ansi.HIDE_CURSOR);
+                // Clear all viewport lines first (from bottom to top to avoid cursor issues)
+                this.logToFile(`[renderNow] Clearing ${viewportHeight} lines (from bottom to top)`);
+                for (let i = viewportHeight - 1; i >= 0; i--) {
+                    const row = i + 1;
+                    this.renderBuffer.write(ansi.moveCursorTo(1, row));
+                    this.renderBuffer.write(ansi.CLEAR_LINE);
+                }
+                // Now write all lines in the frame (frame.length should equal viewportHeight)
+                const linesToWrite = Math.min(frame.length, viewportHeight);
+                this.logToFile(`[renderNow] Writing ${linesToWrite} lines to viewport`);
+                for (let i = 0; i < linesToWrite; i++) {
+                    const row = i + 1;
+                    const lineContent = frame[i] ?? '';
+                    this.renderBuffer.write(ansi.moveCursorTo(1, row));
+                    if (lineContent.length > 0) {
+                        this.renderBuffer.write(this.truncateContent(lineContent, this.effectiveWidth));
+                        this.renderBuffer.write(ansi.RESET);
                     }
-                    this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                    this.logToFile(`[renderNow] After positioning, cursor should be at terminal row ${this.startRow !== null ? this.startRow + visibleStartLineIndex : 'unknown'} (start of visible region)`);
-                }
-                else {
-                    // Region fits in viewport: just move up to the first line and paint
-                    // After initialization, we're at the start of the last line of the region
-                    // So we need to move up (height-1) lines to get to the first line (startRow)
-                    this.logToFile(`[renderNow] First render - region fits in viewport, moving up to first line and painting`);
-                    this.logToFile(`[renderNow] Currently at start of last line (line ${this.height} at row ${this.startRow !== null ? this.startRow + this.height - 1 : 'unknown'}), moving up ${this.height > 1 ? this.height - 1 : 0} lines to get to first line (row ${this.startRow})`);
-                    // CRITICAL: Flush any pending writes before positioning to ensure we're at the correct location
-                    this.renderBuffer.flush();
-                    if (this.height > 1) {
-                        this.renderBuffer.write(ansi.moveCursorUp(this.height - 1));
+                    // Log first few and last few lines being written
+                    if (i < 3 || i >= linesToWrite - 3) {
+                        this.logToFile(`[renderNow] Writing row ${row}: "${lineContent.substring(0, 60)}"`);
                     }
-                    this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                    // Flush again to ensure positioning is executed before we start rendering
-                    this.renderBuffer.flush();
-                    this.logToFile(`[renderNow] After positioning, cursor should be at terminal row ${this.startRow} (start of region)`);
-                }
-                // CRITICAL: First render needs to actually render the content!
-                // Calculate which lines to render
-                let startLineIndex = 0;
-                let linesToRender = Math.min(this.pendingFrame.length, this.height);
-                if (regionExceedsViewport) {
-                    startLineIndex = this.height - terminalHeight;
-                    linesToRender = terminalHeight;
                 }
-                // Render all lines
-                for (let i = 0; i < linesToRender; i++) {
-                    const lineIndex = startLineIndex + i;
-                    const content = this.pendingFrame[lineIndex] || '';
-                    const isLastLine = (i === linesToRender - 1);
-                    this.clearCurrentLine();
-                    const contentToWrite = this.truncateContent(content, this.width);
-                    const isFirstLine = lineIndex === 0;
-                    this.logToFile(`[renderNow] WRITING content for line ${lineIndex + 1} (region line ${lineIndex + 1}/${this.height}, visible line ${i + 1}/${linesToRender}, startLineIndex=${startLineIndex}, isFirstLine=${isFirstLine}): "${contentToWrite.substring(0, 50)}${contentToWrite.length > 50 ? '...' : ''}"`);
-                    this.renderBuffer.write(contentToWrite);
-                    if (!isLastLine) {
-                        // Move to next line
-                        this.renderBuffer.write(ansi.moveCursorDown(1));
-                        this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
+                // CRITICAL: Clear any lines beyond what we wrote (if viewport is larger than frame)
+                // This ensures we don't have leftover content from previous renders
+                if (linesToWrite < viewportHeight) {
+                    this.logToFile(`[renderNow] Clearing ${viewportHeight - linesToWrite} extra lines (${linesToWrite} to ${viewportHeight - 1})`);
+                    for (let i = linesToWrite; i < viewportHeight; i++) {
+                        const row = i + 1;
+                        this.renderBuffer.write(ansi.moveCursorTo(1, row));
+                        this.renderBuffer.write(ansi.CLEAR_LINE);
                     }
                 }
-                // After rendering, move to top-left and save cursor position
-                const linesToMoveUp = linesToRender > 1 ? linesToRender - 1 : 0;
-                if (linesToMoveUp > 0) {
-                    this.renderBuffer.write(ansi.moveCursorUp(linesToMoveUp));
-                }
-                this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
                 this.renderBuffer.flush();
-                this.stdout.write(ansi.SAVE_CURSOR);
-                this.savedCursorPosition = true;
-                // Track visible region top row for region-exceeds-viewport case
-                if (regionExceedsViewport && this.startRow !== null) {
-                    this.visibleRegionTopRow = this.startRow + startLineIndex;
-                    this.logToFile(`[renderNow] First render - region exceeds viewport, set visibleRegionTopRow=${this.visibleRegionTopRow}`);
-                }
-                else if (!regionExceedsViewport && this.startRow !== null) {
-                    this.visibleRegionTopRow = this.startRow;
-                }
-                this.logToFile(`[renderNow] Saved cursor at top-left${regionExceedsViewport ? ' of visible region' : ' of region'} (first render)`);
-                // Move visible cursor to after the region
-                this.stdout.write(ansi.moveCursorDown(linesToRender));
-                this.stdout.write(ansi.MOVE_TO_START_OF_LINE);
-                this.stdout.write(ansi.SHOW_CURSOR);
-                this.logToFile(`[renderNow] Moved visible cursor DOWN ${linesToRender} lines to position AFTER region`);
-                // Copy pending to previous and mark as rendered
-                this.copyPendingToPrevious();
-                this.lastRenderedHeight = this.height;
-                this.hasRendered = true;
-                this.renderScheduled = false;
-                this.isRendering = false;
-                return;
-            }
-            else if (this.resizeJustHappened) {
-                // After resize - DON'T restore cursor position because it might be invalid
-                // The terminal may have scrolled or the viewport changed, making the saved
-                // position wrong. Instead, we'll position from the current location or use
-                // relative movements. The actual positioning will happen in the region-exceeds-viewport
-                // or region-fits logic below.
-                this.logToFile(`[renderNow] After resize - NOT restoring cursor (position may be invalid, will recalculate)`);
-                // Don't restore cursor - let the positioning logic below handle it
-                // This prevents writing content in the wrong place
-                // CRITICAL: Mark that we just had a resize so positioning logic knows not to restore cursor
-                // We'll reset this flag after positioning is done
-                // CRITICAL: On resize, we need to re-initialize positioning, but DON'T reset lastRenderedHeight
-                // We need to keep the previous height so we can correctly calculate if height increased
-                // Only write newlines if height actually increased from before resize
-                // NOTE: Don't reset resizeJustHappened yet - we need it for the positioning logic below
+                this.hideCursor();
             }
             else {
-                // Subsequent renders - unified positioning and rendering logic
-                // Calculate which lines to render first (needed for positioning)
-                let startLineIndex = 0;
-                let linesToRender = Math.min(this.pendingFrame.length, this.height);
-                if (regionExceedsViewport) {
-                    // Region exceeds viewport: render only visible lines (last terminalHeight lines)
-                    startLineIndex = this.height - terminalHeight;
-                    linesToRender = terminalHeight;
-                    this.logToFile(`[renderNow] Region exceeds viewport: height=${this.height} terminalHeight=${terminalHeight} startLineIndex=${startLineIndex} linesToRender=${linesToRender}`);
-                }
-                // Track current terminal row as we render (helps detect bottom of viewport)
-                let currentTerminalRow = null;
-                // Unified positioning logic for both region-fits and region-exceeds-viewport
-                if (this.visibleRegionTopRow !== null) {
-                    currentTerminalRow = this.visibleRegionTopRow;
-                    this.logToFile(`[renderNow] Using tracked visibleRegionTopRow=${this.visibleRegionTopRow}`);
-                }
-                else if (regionExceedsViewport) {
-                    // Estimate for region-exceeds-viewport
-                    currentTerminalRow = terminalHeight - linesToRender + 1;
-                    this.logToFile(`[renderNow] Estimating currentTerminalRow=${currentTerminalRow} (terminalHeight=${terminalHeight} - linesToRender=${linesToRender} + 1)`);
-                }
-                else if (this.startRow !== null) {
-                    // Estimate for region-fits
-                    currentTerminalRow = this.startRow;
-                }
-                // Position cursor: use saved position if available, otherwise fallback
-                if (this.savedCursorPosition && !this.resizeJustHappened) {
-                    // Use saved cursor position (at top-left of region/visible region from previous render)
-                    this.logToFile(`[renderNow] Subsequent render - RESTORING cursor (at top-left${regionExceedsViewport ? ' of visible region' : ' of region'})`);
-                    this.renderBuffer.write(ansi.RESTORE_CURSOR);
-                    this.clearCurrentLine();
-                    // Update tracked position if we don't have it
-                    if (this.visibleRegionTopRow === null && currentTerminalRow !== null) {
-                        this.visibleRegionTopRow = currentTerminalRow;
-                    }
-                }
-                else if (this.startRow !== null && !regionExceedsViewport) {
-                    // Fallback for region-fits: use startRow (only on first subsequent render before we've saved)
-                    this.logToFile(`[renderNow] Subsequent render - no saved cursor, using startRow=${this.startRow} as fallback`);
-                    this.renderBuffer.write(ansi.moveCursorTo(this.startRow, 1));
-                    this.visibleRegionTopRow = this.startRow;
-                    currentTerminalRow = this.startRow;
-                }
-                else {
-                    // Fallback: relative positioning
-                    this.logToFile(`[renderNow] Subsequent render - no saved cursor, using relative positioning`);
-                    this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                    if (linesToRender > 1) {
-                        this.renderBuffer.write(ansi.moveCursorUp(linesToRender - 1));
-                    }
-                    this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                    if (!regionExceedsViewport) {
-                        currentTerminalRow = null;
-                        this.visibleRegionTopRow = null;
-                    }
-                }
-                // CRITICAL: If height changed, adjust saved position (only for region-fits)
-                if (!regionExceedsViewport && this.lastRenderedHeight !== this.height && this.lastRenderedHeight > 0) {
-                    const heightDiff = this.height - this.lastRenderedHeight;
-                    if (heightDiff > 0) {
-                        this.renderBuffer.write(ansi.moveCursorDown(heightDiff));
-                        this.renderBuffer.write(ansi.SAVE_CURSOR);
-                    }
-                    else if (heightDiff < 0) {
-                        this.renderBuffer.write(ansi.moveCursorUp(-heightDiff));
-                        this.renderBuffer.write(ansi.SAVE_CURSOR);
-                    }
-                }
-                // Calculate newline logic
-                const heightIncreased = this.hasRendered && this.lastRenderedHeight > 0 && this.height > this.lastRenderedHeight;
-                const newLinesCount = heightIncreased ? this.height - this.lastRenderedHeight : 0;
-                const shouldWriteNewlines = newLinesCount > 0 && heightIncreased;
-                this.logToFile(`[renderNow] hasRendered=${this.hasRendered} height=${this.height} lastRenderedHeight=${this.lastRenderedHeight} heightIncreased=${heightIncreased} newLinesCount=${newLinesCount} shouldWriteNewlines=${shouldWriteNewlines}`);
-                // CRITICAL: When region exceeds viewport and we're adding a new line at bottom:
-                // Write the top line that will scroll out BEFORE the loop (so it's in scrollback)
-                const lastLineIndex = startLineIndex + linesToRender - 1;
-                const isLastLineNew = shouldWriteNewlines && lastLineIndex === (this.height - 1);
-                const willScroll = regionExceedsViewport && isLastLineNew && startLineIndex > 0;
-                if (willScroll) {
-                    const topLineIndex = startLineIndex;
-                    const topLineContent = this.pendingFrame[topLineIndex] || '';
-                    this.logToFile(`[renderNow] About to write newline at bottom - first writing top line ${topLineIndex + 1} that will scroll out`);
-                    this.clearCurrentLine();
-                    const topContentToWrite = this.truncateContent(topLineContent, this.width);
-                    this.renderBuffer.write(topContentToWrite);
-                    this.renderBuffer.write(ansi.moveCursorDown(1));
-                    this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                    if (currentTerminalRow !== null) {
-                        currentTerminalRow = currentTerminalRow + 1;
-                    }
-                }
-                // Unified rendering loop for both region-fits and region-exceeds-viewport
-                const loopStart = willScroll ? 1 : 0;
-                let actuallyWroteNewlineAtBottom = false;
-                let wroteNewlineForLastLine = false; // Track if we wrote newline for last line (region-fits case)
-                for (let i = loopStart; i < linesToRender; i++) {
-                    const lineIndex = startLineIndex + i;
-                    const content = this.pendingFrame[lineIndex] || '';
-                    const isLastLine = (i === linesToRender - 1);
-                    // CRITICAL: Check if this line is one of the new lines: lineIndex >= (this.height - newLinesCount)
-                    // Only write newline if region is expanding (shouldWriteNewlines is true)
-                    const isNewLine = shouldWriteNewlines && lineIndex >= (this.height - newLinesCount);
-                    // CRITICAL: Always clear the line BEFORE writing
-                    // This prevents any leftover content from causing duplicates
-                    this.clearCurrentLine();
-                    // CRITICAL: For region-exceeds-viewport with new line at bottom, write newline FIRST to trigger scroll
-                    // For region-fits, write content first, then newline (normal order)
-                    const isNewLineAtBottom = isNewLine && isLastLine;
-                    if (isNewLineAtBottom && regionExceedsViewport) {
-                        // Region exceeds viewport: write newline FIRST to trigger scroll, then query cursor
-                        // CRITICAL: Only query cursor if we're actually at the bottom of the viewport (will trigger scrolling)
-                        const isAtBottomOfViewport = currentTerminalRow !== null && currentTerminalRow === terminalHeight;
-                        this.logToFile(`[renderNow] WRITING newline FIRST for new line ${lineIndex + 1} at bottom (region expanding${isAtBottomOfViewport ? ', will trigger scroll' : ''})`);
-                        this.renderBuffer.write('\n');
-                        if (currentTerminalRow !== null) {
-                            currentTerminalRow = currentTerminalRow + 1;
-                        }
-                        actuallyWroteNewlineAtBottom = true;
-                        if (isAtBottomOfViewport) {
-                            // CRITICAL: Flush buffer to ensure newline is written before querying
-                            this.renderBuffer.flush();
-                            // CRITICAL: Query cursor position to confirm terminal has finished scrolling
-                            // Terminal scrolling may be asynchronous, so we need to wait for it to complete
-                            this.logToFile(`[renderNow] At bottom of viewport - querying cursor to confirm scroll completed...`);
-                            try {
-                                const pos = await queryCursorPosition(500);
-                                this.logToFile(`[renderNow] ✓ Cursor query after newline: row=${pos.row}, col=${pos.col} (expected row=${terminalHeight + 1} if scroll occurred)`);
-                                if (pos.row === terminalHeight + 1) {
-                                    // Scroll happened - move up one to get back to the last visible line
-                                    this.renderBuffer.write(ansi.moveCursorUp(1));
-                                    this.visibleRegionTopRow = terminalHeight - (linesToRender - 1);
-                                    this.logToFile(`[renderNow] Scroll confirmed - updated visibleRegionTopRow=${this.visibleRegionTopRow}`);
-                                }
-                                else {
-                                    this.logToFile(`[renderNow] WARNING: Scroll did not occur (cursor at row=${pos.row}, expected ${terminalHeight + 1})`);
-                                    this.visibleRegionTopRow = terminalHeight - (linesToRender - 1);
-                                }
-                            }
-                            catch (err) {
-                                this.logToFile(`[renderNow] ✗ Cursor query failed: ${err instanceof Error ? err.message : String(err)}, proceeding anyway`);
-                                this.renderBuffer.write(ansi.moveCursorUp(1));
-                                this.visibleRegionTopRow = terminalHeight - (linesToRender - 1);
-                            }
-                        }
-                        else {
-                            // Not at bottom of viewport - just move up to get back to the line
-                            this.renderBuffer.write(ansi.moveCursorUp(1));
-                            this.logToFile(`[renderNow] Not at bottom of viewport (currentTerminalRow was ${currentTerminalRow !== null ? currentTerminalRow - 1 : 'null'}), moved up 1 to get back to line`);
-                        }
-                    }
-                    // CRITICAL: Trust the grid layout system - it should ensure content fits within width
-                    const contentToWrite = this.truncateContent(content, this.width);
-                    // Write content (truncated only if significantly too long)
-                    const isFirstLine = lineIndex === 0;
-                    this.logToFile(`[renderNow] WRITING content for line ${lineIndex + 1} (region line ${lineIndex + 1}/${this.height}, visible line ${i + 1}/${linesToRender}, startLineIndex=${startLineIndex}, isFirstLine=${isFirstLine}): "${contentToWrite.substring(0, 50)}${contentToWrite.length > 50 ? '...' : ''}"`);
-                    this.renderBuffer.write(contentToWrite);
-                    // CRITICAL: Write newline for new lines (handled differently for last line vs non-last line)
-                    if (isNewLine && !isLastLine) {
-                        // New line, not at bottom: write newline normally
-                        this.logToFile(`[renderNow] WRITING newline for line ${lineIndex + 1} (new line, region expanding, not at bottom)`);
-                        this.renderBuffer.write('\n');
-                        if (currentTerminalRow !== null) {
-                            currentTerminalRow = currentTerminalRow + 1;
-                        }
-                    }
-                    else if (isNewLineAtBottom && !regionExceedsViewport) {
-                        // New line at bottom, region fits: write newline after content (normal order)
-                        this.logToFile(`[renderNow] WRITING newline for last line ${lineIndex + 1} (new line, region expanding, region fits)`);
-                        this.renderBuffer.write('\n');
-                        wroteNewlineForLastLine = true;
-                    }
-                    else if (!isLastLine && !isNewLine) {
-                        // Not the last line and not a new line: move to next line
-                        this.renderBuffer.write(ansi.moveCursorDown(1));
-                        this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                    }
-                    // After rendering last line, we're at the end of the last line
-                    // We'll move to top-left after the loop
-                }
-                // After rendering, move to top-left of VISIBLE region and save that position
-                // This ensures we always know where the visible region starts for the next render
-                const lastRenderedLineIndex = startLineIndex + linesToRender - 1;
-                const isLastLineOfRegion = lastRenderedLineIndex === (this.height - 1);
-                this.logToFile(`[renderNow] After rendering loop: lastRenderedLineIndex=${lastRenderedLineIndex} (region line ${lastRenderedLineIndex + 1}/${this.height}), isLastLineOfRegion=${isLastLineOfRegion}, actuallyWroteNewlineAtBottom=${actuallyWroteNewlineAtBottom}, terminalHeight=${terminalHeight}`);
-                // CRITICAL: After writing a newline at the bottom, the terminal scrolled
-                // The top of the visible region has moved up by one line
-                // So we need to adjust how many lines we move up to get to the top-left
-                // If we wrote a newline, we're at the end of the last rendered line
-                // The top of the visible region is now (linesToRender - 1) lines up (because it scrolled)
-                // So we should move up (linesToRender - 1) lines, not linesToRender lines
-                if (actuallyWroteNewlineAtBottom) {
-                    // We wrote a newline at the bottom, terminal scrolled
-                    // We're at the end of the last rendered line (which is now below the viewport after scroll)
-                    // The top of the visible region moved up by 1 line due to the scroll
-                    // So if we were at row X, we're now at row X+1, and the top moved from row Y to row Y+1
-                    // We need to move up (linesToRender - 1) lines to get to the new top-left
-                    this.logToFile(`[renderNow] Wrote newline at bottom of viewport (viewport line ${linesToRender}/${linesToRender}) - terminal scrolled, top of visible region moved up 1 line`);
-                    this.logToFile(`[renderNow] Moving up ${linesToRender - 1} lines to get to top-left (accounting for scroll)`);
-                    if (linesToRender > 1) {
-                        this.renderBuffer.write(ansi.moveCursorUp(linesToRender - 1));
-                    }
-                    this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                    // CRITICAL: Flush buffer BEFORE saving cursor so all movements are executed
-                    this.renderBuffer.flush();
-                    // Write SAVE_CURSOR directly to stdout (not buffer) so it executes immediately
-                    this.stdout.write(ansi.SAVE_CURSOR);
-                    this.savedCursorPosition = true;
-                    this.logToFile(`[renderNow] Saved cursor at top-left of visible region (startLineIndex=${startLineIndex + 1} after scroll)`);
-                }
-                else if (wroteNewlineForLastLine) {
-                    // Wrote newline for last line (region-fits case) - we're at the start of the line after the region
-                    // So we need to move up linesToRender lines to get to the top-left
-                    this.logToFile(`[renderNow] Wrote newline for last line (region-fits) - moving up ${linesToRender} lines to get to top-left`);
-                    if (linesToRender > 0) {
-                        this.renderBuffer.write(ansi.moveCursorUp(linesToRender));
-                    }
-                    this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                    this.renderBuffer.flush();
-                    this.stdout.write(ansi.SAVE_CURSOR);
-                    this.savedCursorPosition = true;
-                    this.logToFile(`[renderNow] Saved cursor at top-left of region`);
-                }
-                else {
-                    // No newline written, normal case - move up (linesToRender - 1) lines
-                    this.logToFile(`[renderNow] No newline written at bottom - normal case, moving up ${linesToRender - 1} lines`);
-                    this.moveToTopLeftAndSave(linesToRender, regionExceedsViewport ? `of visible region (startLineIndex=${startLineIndex})` : `of region`);
-                }
-                // CRITICAL: Move the VISIBLE cursor to the line AFTER the region (below it)
-                // This prevents user input from overwriting the region content
-                // We saved the position at top-left for our internal tracking, but the visible cursor should be out of the way
-                this.stdout.write(ansi.moveCursorDown(linesToRender));
-                this.stdout.write(ansi.MOVE_TO_START_OF_LINE);
-                this.stdout.write(ansi.SHOW_CURSOR);
-                this.logToFile(`[renderNow] Moved visible cursor DOWN ${linesToRender} lines to position AFTER region (so user input won't interfere)`);
+                // Normal diff-based rendering (for incremental updates)
+                this.applyDiff(frame);
             }
-            // Handle deletions (lines that were in previousFrame but not in pendingFrame)
-            // Since we've already cleared and re-rendered all lines, deletions are handled
-            // by the fact that those lines are no longer in pendingFrame
-            // No additional action needed - the lines are already cleared
-            // CRITICAL: After rendering, we've saved the cursor at the top-left of the region
-            // This ensures we always know where the region starts for the next render
-            // The cursor position is saved at the first line, start of line, of the region
-            // This is more reliable than saving at the end, especially after resize/scroll
-            // Copy pending to previous
+            this.previousViewportFrame = [...frame];
             this.copyPendingToPrevious();
-            // Update last rendered height for next render
             this.lastRenderedHeight = this.height;
-            this.hasRendered = true; // Mark that we've rendered at least once
-            // CRITICAL: Reset resize flag after rendering is complete
-            // This ensures the flag is only active during the render that handles the resize
-            if (this.resizeJustHappened) {
-                this.logToFile(`[renderNow] RESETTING resizeJustHappened=false (after render complete)`);
-                this.resizeJustHappened = false;
-            }
-            this.renderScheduled = false;
         }
         finally {
             this.isRendering = false;
         }
     }
-    /**
-     * Force immediate render of pending updates (bypasses throttle)
-     * Returns a promise that resolves when rendering is complete
-     */
-    async flush() {
-        // CRITICAL: Await initialization before rendering
-        // This ensures cursor query completes and stdin is restored before any rendering
-        if (!this.isInitialized && this.initializationPromise) {
-            await this.initializationPromise;
+    copyPendingToPrevious() {
+        const normalized = this.getEffectiveFrame();
+        this.previousFrame = [...normalized];
+    }
+    buildViewportFrame() {
+        const viewportHeight = Math.max(1, this.viewportHeight);
+        const normalized = this.getEffectiveFrame();
+        const visibleLines = Math.min(viewportHeight, normalized.length);
+        const frame = new Array(viewportHeight).fill('');
+        if (visibleLines === 0) {
+            this.logToFile(`[buildViewportFrame] No visible lines - normalized.length: ${normalized.length}, viewportHeight: ${viewportHeight}`);
+            return frame;
+        }
+        const startIndex = normalized.length > viewportHeight
+            ? normalized.length - viewportHeight
+            : 0;
+        this.logToFile(`[buildViewportFrame] normalized.length: ${normalized.length}, viewportHeight: ${viewportHeight}, startIndex: ${startIndex}, visibleLines: ${visibleLines}`);
+        for (let i = 0; i < visibleLines; i++) {
+            frame[i] = normalized[startIndex + i];
+        }
+        // Log what we're putting in the frame
+        if (startIndex > 0 || visibleLines < normalized.length) {
+            this.logToFile(`[buildViewportFrame] Frame shows lines ${startIndex + 1} to ${startIndex + visibleLines} of ${normalized.length} total lines`);
+            this.logToFile(`[buildViewportFrame] First frame line: "${frame[0]?.substring(0, 50)}"`);
+            this.logToFile(`[buildViewportFrame] Last frame line: "${frame[visibleLines - 1]?.substring(0, 50)}"`);
+        }
+        return frame;
+    }
+    mapLineToViewportRow(lineNumber) {
+        const viewportHeight = Math.max(1, this.viewportHeight);
+        const visibleStart = Math.max(1, this.height - viewportHeight + 1);
+        const visibleEnd = visibleStart + viewportHeight - 1;
+        if (lineNumber < visibleStart || lineNumber > visibleEnd) {
+            return null;
+        }
+        return lineNumber - visibleStart + 1;
+    }
+    hideCursor() {
+        if (this.permanentlyDisabled) {
+            return;
         }
-        await this.renderNow();
+        this.stdout.write(ansi.HIDE_CURSOR);
+        this.cursorVisible = false;
     }
-    /**
-     * Set throttle FPS
-     */
-    setThrottleFps(fps) {
-        this.throttle.setFps(fps);
+    showCursorAt(lineNumber, column) {
+        if (this.permanentlyDisabled) {
+            return;
+        }
+        this.ensureTerminalState();
+        const row = this.mapLineToViewportRow(lineNumber);
+        if (row === null) {
+            return;
+        }
+        const col = Math.max(1, Math.min(column, this.viewportWidth));
+        this.stdout.write(ansi.moveCursorTo(col, row));
+        this.stdout.write(ansi.SHOW_CURSOR);
+        this.cursorVisible = true;
     }
-    /**
-     * Clear a single line (1-based)
-     */
-    clearLine(lineNumber) {
-        if (lineNumber < 1) {
-            throw new Error('Line numbers start at 1');
+    getEffectiveFrame() {
+        const target = Math.max(0, this.height);
+        const frame = this.pendingFrame.slice(0, target);
+        while (frame.length < target) {
+            frame.push('');
+        }
+        // Log if frame seems corrupted (has content but in wrong order)
+        if (frame.length > 0 && frame.some((line, i) => line.length > 0)) {
+            const nonEmptyLines = frame.map((line, i) => ({ index: i, content: line.substring(0, 50) })).filter(l => l.content.length > 0);
+            if (nonEmptyLines.length > 1) {
+                // Check if first non-empty line looks like it should be later (e.g., contains "Press SPACEBAR" or is a border)
+                const firstNonEmpty = nonEmptyLines[0];
+                if (firstNonEmpty.content.includes('Press SPACEBAR') || firstNonEmpty.content.includes('╰') || firstNonEmpty.content.includes('│')) {
+                    this.logToFile(`[getEffectiveFrame] WARNING: Frame might be corrupted - first non-empty line at index ${firstNonEmpty.index}: "${firstNonEmpty.content}"`);
+                }
+            }
         }
-        this.setLine(lineNumber, '');
+        return frame;
     }
-    /**
-     * Clear entire region
-     */
-    clear() {
-        // CRITICAL: Disable rendering during clear to prevent multiple renders
-        // We'll render once at the end if needed
-        const wasRenderingDisabled = this.disableRendering;
-        this.disableRendering = true;
-        // Clear all lines in pendingFrame (which may be larger than height if region expanded)
-        const maxLines = Math.max(this.height, this.pendingFrame.length);
-        for (let i = 1; i <= maxLines; i++) {
-            this.setLine(i, '');
+    applyDiff(nextFrame) {
+        const ops = diffFrames(this.previousViewportFrame, nextFrame);
+        let wrote = false;
+        for (const op of ops) {
+            if (op.type === 'no_change') {
+                continue;
+            }
+            if (!wrote) {
+                this.renderBuffer.write(ansi.HIDE_CURSOR);
+                wrote = true;
+            }
+            const row = op.line + 1;
+            if (op.type === 'delete_line') {
+                // Delete line: clear it completely using CLEAR_LINE
+                this.renderBuffer.write(ansi.moveCursorTo(1, row));
+                this.renderBuffer.write(ansi.CLEAR_LINE);
+                // Note: After delete, all lines below shift up, so they'll be redrawn by subsequent ops
+            }
+            else {
+                // Full line update: clear and redraw
+                const lineContent = nextFrame[op.line] ?? op.content ?? '';
+                this.renderBuffer.write(ansi.moveCursorTo(1, row));
+                this.renderBuffer.write(ansi.CLEAR_LINE);
+                if (lineContent.length > 0) {
+                    this.renderBuffer.write(this.truncateContent(lineContent, this.effectiveWidth));
+                    this.renderBuffer.write(ansi.RESET);
+                }
+            }
+        }
+        if (wrote) {
+            this.renderBuffer.flush();
+            this.hideCursor();
         }
-        // Re-enable rendering
-        this.disableRendering = wasRenderingDisabled;
     }
-    /**
-     * Destroy the region (cleanup)
-     * Automatically deletes any blank lines from the terminal, but preserves content
-     *
-     * @param clearFirst - If true, clears the region before destroying (default: false)
-     *
-     * Note: This is automatically called on process exit, but you can also call it explicitly
-     * to clean up resources earlier (e.g., before continuing with other terminal output)
-     */
-    async destroy(clearFirst = false) {
-        // CRITICAL: Mark as destroyed FIRST to prevent resize handler from interfering
-        // This ensures resize handler won't re-disable auto-wrap after we re-enable it
-        const wasInitialized = this.isInitialized;
-        this.isInitialized = false;
-        // Remove from active regions set (prevent memory leak)
-        RegionRenderer.activeRegions.delete(this);
-        // Re-enable terminal auto-wrap if we disabled it
-        // Write directly to stdout to ensure it takes effect immediately
-        // CRITICAL: Always re-enable auto-wrap on destroy to prevent zsh/terminal issues
-        // When auto-wrap is disabled and terminal resizes, zsh may insert lines
-        if (!this.disableRendering && this.autoWrapDisabled) {
+    truncateContent(content, maxWidth) {
+        return truncateToWidth(content, maxWidth);
+    }
+    initializeTerminalState() {
+        if (this.inAlternateScreen) {
+            return;
+        }
+        this.stdout.write(ansi.ENTER_ALTERNATE_SCREEN);
+        this.stdout.write(ansi.DISABLE_AUTO_WRAP);
+        this.stdout.write(ansi.ERASE_SCREEN);
+        this.stdout.write(ansi.moveCursorTo(1, 1));
+        this.autoWrapDisabled = true;
+        this.inAlternateScreen = true;
+    }
+    ensureTerminalState() {
+        if (!this.inAlternateScreen) {
+            this.initializeTerminalState();
+        }
+        if (!this.autoWrapDisabled) {
+            this.stdout.write(ansi.DISABLE_AUTO_WRAP);
+            this.autoWrapDisabled = true;
+        }
+    }
+    leaveAlternateScreen(clearFirst) {
+        if (!this.inAlternateScreen) {
+            return;
+        }
+        this.stdout.write(ansi.SHOW_CURSOR);
+        if (this.autoWrapDisabled) {
             this.stdout.write(ansi.ENABLE_AUTO_WRAP);
             this.autoWrapDisabled = false;
         }
-        // Prevent double-destruction
-        if (!wasInitialized && this.pendingFrame.length === 0) {
+        this.stdout.write(ansi.EXIT_ALTERNATE_SCREEN);
+        this.inAlternateScreen = false;
+        if (!clearFirst) {
+            const finalLines = this.getEffectiveFrame();
+            // Remove trailing empty lines - don't add extra blank lines to original screen
+            let lastNonEmpty = finalLines.length;
+            while (lastNonEmpty > 0 && finalLines[lastNonEmpty - 1].trim() === '') {
+                lastNonEmpty--;
+            }
+            const trimmedLines = finalLines.slice(0, lastNonEmpty);
+            if (trimmedLines.length > 0) {
+                const output = trimmedLines.join('\n');
+                this.stdout.write(`${output}\n`);
+            }
+        }
+    }
+    setupResizeHandler() {
+        if (!this.stdout.isTTY || typeof this.stdout.on !== 'function') {
             return;
         }
-        // Clean up resize handler if it exists
-        if (this.resizeCleanup) {
-            this.resizeCleanup();
-            this.resizeCleanup = undefined;
+        const handler = () => {
+            const oldViewportHeight = this.viewportHeight;
+            const oldViewportWidth = this.viewportWidth;
+            this.updateViewportMetrics();
+            const newViewportHeight = this.viewportHeight;
+            const newViewportWidth = this.viewportWidth;
+            this.logToFile(`[resize] ========================================`);
+            this.logToFile(`[resize] OLD: height=${oldViewportHeight}, width=${oldViewportWidth}`);
+            this.logToFile(`[resize] NEW: height=${newViewportHeight}, width=${newViewportWidth}`);
+            this.logToFile(`[resize] Content height: ${this.height}, pendingFrame.length: ${this.pendingFrame.length}`);
+            this.logToFile(`[resize] previousViewportFrame.length: ${this.previousViewportFrame.length}`);
+            if (this.previousViewportFrame.length > 0) {
+                this.logToFile(`[resize] Previous frame (first 3): ${this.previousViewportFrame.slice(0, 3).map((l, i) => `[${i}]: "${l.substring(0, 40)}"`).join(', ')}`);
+                this.logToFile(`[resize] Previous frame (last 3): ${this.previousViewportFrame.slice(-3).map((l, i) => `[${this.previousViewportFrame.length - 3 + i}]: "${l.substring(0, 40)}"`).join(', ')}`);
+            }
+            // CRITICAL: On resize, clear the screen and do a full redraw
+            // This bypasses the diff algorithm which can get confused when:
+            // 1. Viewport dimensions change
+            // 2. Content wraps differently, changing logical line positions
+            // 3. The viewport frame represents different logical lines
+            // Clear previousViewportFrame to signal renderNow() to do a full redraw
+            this.previousViewportFrame = [];
+            this.lastRenderedHeight = 0;
+            // Trigger re-render of all content with new width
+            // NOTE: onKeepAlive() will call reRenderLastContent() which calls flush(),
+            // so we don't need to call scheduleRender() here - that would cause double rendering
+            if (this.onKeepAlive) {
+                this.onKeepAlive();
+            }
+        };
+        this.stdout.on('resize', handler);
+        this.resizeCleanup = () => {
+            if (typeof this.stdout.off === 'function') {
+                this.stdout.off('resize', handler);
+            }
+            else if (typeof this.stdout.removeListener === 'function') {
+                this.stdout.removeListener('resize', handler);
+            }
+        };
+    }
+    updateViewportMetrics() {
+        const width = this.readViewportWidth();
+        const height = this.readViewportHeight();
+        this.viewportWidth = width;
+        this.viewportHeight = height;
+        this.width = this.viewportWidth;
+        this.effectiveWidth = this.viewportWidth;
+    }
+    readViewportWidth() {
+        if (this.stdout.isTTY && typeof this.stdout.columns === 'number' && this.stdout.columns > 0) {
+            return this.stdout.columns;
         }
-        // Clear if requested
-        if (clearFirst) {
-            this.clear();
-            // Render the clear immediately so previousFrame is updated
-            await this.renderNow();
+        if (process.stdout.isTTY && typeof process.stdout.columns === 'number' && process.stdout.columns > 0) {
+            return process.stdout.columns;
         }
-        if (!this.disableRendering && wasInitialized) {
-            // Check if all lines are blank
-            // After clearFirst + renderNow(), previousFrame will have empty lines
-            // Otherwise, check previousFrame to see if content exists
-            const allLinesBlank = this.previousFrame.every(line => line.trim() === '');
-            // Only delete lines if they are blank
-            // If clearFirst was true, we've already cleared and rendered, so previousFrame will be empty
-            // If clearFirst was false, we check previousFrame to see if content exists
-            if (allLinesBlank && this.height > 0) {
-                // CRITICAL: Don't use RESTORE_CURSOR here - it might be invalid after destroy
-                // Instead, just move to the end of the region using relative movement
-                // We know we're at the end because that's where we save the cursor
-                // Move to start of first line of region (go up by height)
-                this.renderBuffer.write(ansi.moveCursorUp(this.height));
-                // Use MOVE_TO_START_OF_LINE which is more reliable than \r
-                this.renderBuffer.write(ansi.MOVE_TO_START_OF_LINE);
-                // Delete the blank lines (shifts content up if supported)
-                // This will remove the lines from the terminal display
-                this.renderBuffer.write(ansi.deleteLines(this.height));
-                // Flush the cleanup
-                this.renderBuffer.flush();
+        if (process.env.COLUMNS) {
+            const parsed = parseInt(process.env.COLUMNS, 10);
+            if (!Number.isNaN(parsed) && parsed > 0) {
+                return parsed;
             }
-            // CRITICAL: Clear any saved cursor position to prevent zsh from restoring it
-            // Some terminals/shells (like zsh) may try to restore saved cursor positions
-            // We don't want to leave a stale saved position that could cause issues
-            // Note: There's no standard ANSI code to "clear" saved position, but we can
-            // ensure we're at a known position and not relying on saved position
-            // If lines have content, we leave them as-is - the user can see the output
         }
-        // Clear buffers (internal state only, doesn't affect terminal)
-        this.pendingFrame = [];
-        this.previousFrame = [];
-        this.renderBuffer.clear();
-        // Mark as destroyed to prevent double-cleanup
-        this.isInitialized = false;
+        return 80;
     }
-    // Getters for width and height
-    getWidth() {
-        return this.width;
+    readViewportHeight() {
+        if (this.stdout.isTTY && typeof this.stdout.rows === 'number' && this.stdout.rows > 0) {
+            return this.stdout.rows;
+        }
+        if (process.stdout.isTTY && typeof process.stdout.rows === 'number' && process.stdout.rows > 0) {
+            return process.stdout.rows;
+        }
+        return getDefaultTerminalHeight();
     }
-    getHeight() {
-        return this.height;
+    resolveDebugLogPath(debugLog) {
+        if (!debugLog) {
+            return undefined;
+        }
+        return path.isAbsolute(debugLog) ? debugLog : path.join(process.cwd(), debugLog);
     }
 }
 //# sourceMappingURL=region-renderer.js.map