@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/terminal-renderer.js

@@ -0,0 +1,751 @@
+/**
+ * Terminal Renderer
+ *
+ * Single point of terminal output. All rendering goes through this class.
+ * Eliminates race conditions by ensuring only one writer.
+ *
+ * Key responsibilities:
+ * - Manage render modes (MENU, REPL, OVERLAY)
+ * - Set up and manage scroll regions (REPL mode)
+ * - Collect content from providers
+ * - Write to terminal (single writer)
+ * - Handle resize events
+ * - Route keyboard input
+ */
+import { EventEmitter } from 'events';
+import { RenderMode, isValidTransition } from './render-modes.js';
+// Re-export RenderMode for convenience
+export { RenderMode } from './render-modes.js';
+import * as codes from './terminal-codes.js';
+import { getPhysicalLineCount } from './line-utils.js';
+// =============================================================================
+// TerminalRenderer Class
+// =============================================================================
+export class TerminalRenderer extends EventEmitter {
+    // === Configuration ===
+    renderDebounceMs;
+    debug;
+    useScrollRegions;
+    // === State ===
+    mode;
+    terminalRows = 24;
+    terminalCols = 80;
+    footerHeight = 0;
+    scrollRegionBottom = 0;
+    isRendering = false;
+    renderPending = false;
+    renderTimer = null;
+    started = false;
+    simpleMode = false;
+    // === Content Queues ===
+    pendingScrollContent = [];
+    // === Scroll Position Tracking ===
+    // Track where the next output should go in scroll zone
+    scrollCursorRow = 1; // 1-indexed, starts at top
+    // === Providers ===
+    providers = {};
+    // === Footer (for scroll region mode) ===
+    footer = null;
+    // === Resize Handler ===
+    resizeHandler = null;
+    // === Render Loop (for scroll region mode) ===
+    renderLoopTimer = null;
+    renderLoopInterval = 60; // 60ms = ~16fps
+    constructor(options = {}) {
+        super();
+        this.mode = options.initialMode ?? RenderMode.REPL;
+        this.renderDebounceMs = options.renderDebounceMs ?? 16;
+        this.debug = options.debug ?? false;
+        this.useScrollRegions = options.useScrollRegions ?? false;
+        this.updateDimensions();
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    /**
+     * Start the renderer.
+     * Sets up terminal state and begins render loop.
+     */
+    start() {
+        if (this.started) {
+            this.log('Already started, ignoring start() call');
+            return;
+        }
+        this.log(`Starting in ${this.mode} mode`);
+        // Check if stdout is a TTY
+        if (!process.stdout.isTTY) {
+            this.log('Not a TTY, using simple mode');
+            this.simpleMode = true;
+            this.started = true;
+            return;
+        }
+        // Update dimensions
+        this.updateDimensions();
+        // Set up resize handler
+        this.resizeHandler = () => {
+            this.handleResize();
+        };
+        process.stdout.on('resize', this.resizeHandler);
+        // Mark as started
+        this.started = true;
+        // Initial mode setup
+        this.setupMode(this.mode);
+        // Start render loop if using scroll regions
+        if (this.useScrollRegions) {
+            this.startRenderLoop();
+        }
+        this.log('Started successfully');
+    }
+    /**
+     * Start the render loop (for scroll region mode)
+     * Polls footer for changes and re-renders
+     */
+    startRenderLoop() {
+        if (this.renderLoopTimer)
+            return;
+        this.log('Starting render loop');
+        this.renderLoopTimer = setInterval(() => {
+            if (this.started && !this.simpleMode) {
+                // In scroll region mode, always re-render to pick up footer changes
+                this.forceRender();
+            }
+        }, this.renderLoopInterval);
+    }
+    /**
+     * Stop the render loop
+     */
+    stopRenderLoop() {
+        if (this.renderLoopTimer) {
+            clearInterval(this.renderLoopTimer);
+            this.renderLoopTimer = null;
+            this.log('Render loop stopped');
+        }
+    }
+    /**
+     * Stop the renderer.
+     * Cleans up terminal state and stops render loop.
+     */
+    stop() {
+        if (!this.started) {
+            this.log('Not started, ignoring stop() call');
+            return;
+        }
+        this.log('Stopping');
+        // Stop render loop
+        this.stopRenderLoop();
+        // Clear any pending render
+        if (this.renderTimer) {
+            clearTimeout(this.renderTimer);
+            this.renderTimer = null;
+        }
+        // Remove resize handler
+        if (this.resizeHandler) {
+            process.stdout.off('resize', this.resizeHandler);
+            this.resizeHandler = null;
+        }
+        // Reset terminal state (only if TTY)
+        if (!this.simpleMode) {
+            // Reset scroll region
+            this.write(codes.resetScrollRegion);
+            // Show cursor
+            this.write(codes.showCursor);
+        }
+        this.started = false;
+        this.log('Stopped');
+    }
+    /**
+     * Check if renderer is running
+     */
+    isStarted() {
+        return this.started;
+    }
+    // ===========================================================================
+    // Mode Management
+    // ===========================================================================
+    /**
+     * Get current render mode
+     */
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * Switch to a different render mode
+     */
+    setMode(newMode, reason = 'programmatic') {
+        if (newMode === this.mode) {
+            this.log(`Already in ${newMode} mode, ignoring`);
+            return;
+        }
+        if (!isValidTransition(this.mode, newMode)) {
+            this.log(`Invalid transition: ${this.mode} -> ${newMode}`);
+            this.emit('error', new Error(`Invalid mode transition: ${this.mode} -> ${newMode}`));
+            return;
+        }
+        const transition = {
+            from: this.mode,
+            to: newMode,
+            reason,
+            timestamp: Date.now(),
+        };
+        this.log(`Mode transition: ${this.mode} -> ${newMode} (${reason})`);
+        // Cleanup current mode
+        this.cleanupMode(this.mode);
+        // Switch mode
+        this.mode = newMode;
+        // Setup new mode
+        this.setupMode(newMode);
+        // Emit event
+        this.emit('mode-change', transition);
+        // Force render
+        this.forceRender();
+    }
+    /**
+     * Set up terminal for a specific mode
+     */
+    setupMode(mode) {
+        if (this.simpleMode)
+            return;
+        switch (mode) {
+            case RenderMode.MENU:
+                // Full screen, no scroll region, hidden cursor
+                this.write(codes.resetScrollRegion);
+                this.write(codes.clearScreenAndHome);
+                this.write(codes.hideCursor);
+                break;
+            case RenderMode.REPL:
+                // Set up scroll region (will be adjusted on first render)
+                this.footerHeight = 0; // Will be calculated
+                this.write(codes.resetScrollRegion);
+                this.write(codes.showCursor);
+                break;
+            case RenderMode.OVERLAY:
+                // Full screen, no scroll region
+                this.write(codes.resetScrollRegion);
+                this.write(codes.clearScreenAndHome);
+                // Cursor visibility depends on overlay
+                break;
+        }
+    }
+    /**
+     * Clean up terminal state when leaving a mode
+     */
+    cleanupMode(mode) {
+        if (this.simpleMode)
+            return;
+        switch (mode) {
+            case RenderMode.MENU:
+                // Nothing special to clean up
+                break;
+            case RenderMode.REPL:
+                // Reset scroll region before leaving
+                this.write(codes.resetScrollRegion);
+                break;
+            case RenderMode.OVERLAY:
+                // Nothing special to clean up
+                break;
+        }
+    }
+    // ===========================================================================
+    // Provider Management
+    // ===========================================================================
+    /**
+     * Register content providers
+     */
+    setProviders(providers) {
+        this.providers = { ...this.providers, ...providers };
+        this.log(`Providers updated: ${Object.keys(providers).join(', ')}`);
+    }
+    /**
+     * Get a specific provider
+     */
+    getProvider(key) {
+        return this.providers[key];
+    }
+    // ===========================================================================
+    // Footer Integration (for scroll region mode)
+    // ===========================================================================
+    /**
+     * Set the Footer instance for scroll region rendering
+     * When useScrollRegions is true, TerminalRenderer uses footer.getFooterLines()
+     * and manages the scroll region. Footer's own render loop is disabled.
+     */
+    setFooter(footer) {
+        this.footer = footer;
+        this.log('Footer connected');
+        // When scroll regions are enabled, disable Footer's internal render loop
+        // TerminalRenderer will handle all rendering
+        if (this.useScrollRegions) {
+            footer.setExternalRenderer(true);
+            this.log('Footer external renderer enabled (scroll region mode)');
+        }
+    }
+    /**
+     * Get the connected Footer instance
+     */
+    getFooter() {
+        return this.footer;
+    }
+    // ===========================================================================
+    // Scroll Zone (REPL mode)
+    // ===========================================================================
+    /**
+     * Queue content for scroll zone (REPL mode only)
+     * Content will be written on next render
+     *
+     * In legacy mode (useScrollRegions=false), writes immediately via console.log
+     * In scroll region mode, queues for next render cycle
+     */
+    appendToScrollZone(content) {
+        if (this.mode !== RenderMode.REPL) {
+            this.log('appendToScrollZone called outside REPL mode, ignoring');
+            return;
+        }
+        const lines = Array.isArray(content) ? content : content.split('\n');
+        if (!this.useScrollRegions) {
+            // Legacy mode: write immediately via console.log
+            // This works with existing Footer class that manages its own rendering
+            for (const line of lines) {
+                console.log(line);
+            }
+            return;
+        }
+        // Scroll region mode: queue for render
+        this.pendingScrollContent.push(...lines);
+        this.requestRender();
+    }
+    /**
+     * Flush pending scroll content to terminal
+     *
+     * Uses tracked scroll position to append content naturally.
+     * When content would exceed scroll region, scrolling occurs automatically.
+     */
+    flushScrollContent() {
+        if (this.pendingScrollContent.length === 0)
+            return;
+        this.log(`Flushing ${String(this.pendingScrollContent.length)} lines at row ${String(this.scrollCursorRow)}`);
+        // Move to current scroll position (within scroll region)
+        this.write(codes.cursorTo(this.scrollCursorRow, 1));
+        // Write each line
+        for (const line of this.pendingScrollContent) {
+            this.write(line);
+            this.write('\n');
+            // Track position (clamped to scroll region bottom)
+            this.scrollCursorRow++;
+            if (this.scrollCursorRow > this.scrollRegionBottom) {
+                // Content will scroll, cursor stays at bottom of scroll region
+                this.scrollCursorRow = this.scrollRegionBottom;
+            }
+        }
+        this.pendingScrollContent = [];
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    /**
+     * Request a render (debounced)
+     */
+    requestRender() {
+        if (!this.started || this.simpleMode)
+            return;
+        if (this.renderPending)
+            return;
+        this.renderPending = true;
+        if (this.renderTimer) {
+            clearTimeout(this.renderTimer);
+        }
+        this.renderTimer = setTimeout(() => {
+            this.doRender();
+        }, this.renderDebounceMs);
+    }
+    /**
+     * Force immediate render (bypasses debounce)
+     */
+    forceRender() {
+        if (!this.started)
+            return;
+        // Clear any pending debounced render
+        if (this.renderTimer) {
+            clearTimeout(this.renderTimer);
+            this.renderTimer = null;
+        }
+        this.renderPending = false;
+        this.doRender();
+    }
+    /**
+     * Main render method
+     */
+    doRender() {
+        if (this.isRendering) {
+            // Already rendering, schedule another
+            this.renderPending = true;
+            return;
+        }
+        this.isRendering = true;
+        this.renderPending = false;
+        try {
+            if (this.simpleMode) {
+                this.renderSimpleMode();
+            }
+            else {
+                switch (this.mode) {
+                    case RenderMode.MENU:
+                        this.renderMenuMode();
+                        break;
+                    case RenderMode.REPL:
+                        this.renderReplMode();
+                        break;
+                    case RenderMode.OVERLAY:
+                        this.renderOverlayMode();
+                        break;
+                }
+            }
+            this.emit('render', this.mode);
+        }
+        catch (error) {
+            this.emit('error', error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            this.isRendering = false;
+            // Check if another render was requested during this one
+            // (renderPending can be set by callbacks during render)
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (this.renderPending) {
+                this.requestRender();
+            }
+        }
+    }
+    /**
+     * Render in simple mode (non-TTY)
+     */
+    renderSimpleMode() {
+        // In simple mode, just flush any pending content
+        for (const line of this.pendingScrollContent) {
+            console.log(line);
+        }
+        this.pendingScrollContent = [];
+    }
+    /**
+     * Render MENU mode
+     */
+    renderMenuMode() {
+        const menuProvider = this.providers.menu;
+        if (!menuProvider) {
+            this.log('No menu provider, skipping menu render');
+            return;
+        }
+        const lines = menuProvider.getLines();
+        // Clear and render from top
+        this.write(codes.cursorHome);
+        this.write(codes.clearToEndOfScreen);
+        for (const line of lines) {
+            this.write(line + '\n');
+        }
+    }
+    /**
+     * Render REPL mode
+     */
+    renderReplMode() {
+        // If scroll regions disabled (legacy mode), do nothing
+        // Footer manages its own rendering and scroll content goes via console.log
+        if (!this.useScrollRegions) {
+            return;
+        }
+        // 1. Build footer content (from Footer or providers)
+        const footerLines = this.footer ? this.footer.getFooterLines() : this.buildFooterLines();
+        const newFooterHeight = this.calculatePhysicalHeight(footerLines);
+        this.log(`renderReplMode: footerHeight=${String(newFooterHeight)}, pending=${String(this.pendingScrollContent.length)}, scrollCursor=${String(this.scrollCursorRow)}`);
+        // 2. Adjust scroll region if footer height changed
+        if (newFooterHeight !== this.footerHeight) {
+            this.adjustScrollRegion(newFooterHeight);
+        }
+        // 3. Flush pending scroll content
+        if (this.pendingScrollContent.length > 0) {
+            this.flushScrollContent();
+        }
+        // 4. Render footer
+        this.renderFooter(footerLines);
+        // 5. Position cursor if footer is connected
+        if (this.footer) {
+            this.positionFooterCursor();
+        }
+    }
+    /**
+     * Build footer lines from providers
+     */
+    buildFooterLines() {
+        const lines = [];
+        // 1. Subagent status (if any)
+        if (this.providers.subagent) {
+            lines.push(...this.providers.subagent.getLines());
+        }
+        // 2. Spinner OR Todo list (mutually exclusive)
+        if (this.providers.spinner?.isAgentRunning()) {
+            lines.push(...(this.providers.spinner.getLines()));
+        }
+        else if (this.providers.todo) {
+            lines.push(...this.providers.todo.getLines());
+        }
+        // 3. Input prompt (includes separator)
+        if (this.providers.input) {
+            lines.push(...this.providers.input.getLines());
+        }
+        // 4. Queued messages
+        if (this.providers.queue) {
+            lines.push(...this.providers.queue.getLines());
+        }
+        // 5. Mode indicator
+        if (this.providers.mode) {
+            lines.push(...this.providers.mode.getLines());
+        }
+        // Cap at 80% of terminal height
+        const maxHeight = Math.floor(this.terminalRows * 0.8);
+        const physicalHeight = this.calculatePhysicalHeight(lines);
+        if (physicalHeight > maxHeight) {
+            // TODO: Implement truncation (Phase 4)
+            this.log(`Footer too tall: ${String(physicalHeight)} > ${String(maxHeight)}`);
+        }
+        return lines;
+    }
+    /**
+     * Calculate physical height of lines (accounting for wrapping)
+     */
+    calculatePhysicalHeight(lines) {
+        let height = 0;
+        for (const line of lines) {
+            height += getPhysicalLineCount(line, this.terminalCols);
+        }
+        return height;
+    }
+    /**
+     * Adjust scroll region when footer height changes
+     */
+    adjustScrollRegion(newFooterHeight) {
+        if (newFooterHeight === this.footerHeight)
+            return;
+        const oldBottom = this.scrollRegionBottom;
+        this.footerHeight = newFooterHeight;
+        this.scrollRegionBottom = this.terminalRows - newFooterHeight;
+        this.log(`Scroll region: [1-${String(oldBottom)}] -> [1-${String(this.scrollRegionBottom)}] (footer: ${String(newFooterHeight)} lines)`);
+        // Set new scroll region (1-indexed)
+        this.write(codes.setScrollRegion(1, this.scrollRegionBottom));
+        // Keep scroll cursor within new bounds
+        if (this.scrollCursorRow > this.scrollRegionBottom) {
+            this.scrollCursorRow = this.scrollRegionBottom;
+        }
+    }
+    /**
+     * Render footer content
+     */
+    renderFooter(lines) {
+        if (lines.length === 0)
+            return;
+        // Move to footer area (row after scroll region)
+        const footerStartRow = this.scrollRegionBottom + 1;
+        this.write(codes.cursorTo(footerStartRow, 1));
+        // Clear footer area
+        this.write(codes.clearToEndOfScreen);
+        // Write footer lines
+        for (let i = 0; i < lines.length; i++) {
+            if (i > 0)
+                this.write('\n');
+            this.write(lines[i]);
+        }
+        // Position cursor for input
+        this.positionCursor();
+    }
+    /**
+     * Position cursor for input (provider-based)
+     */
+    positionCursor() {
+        const inputProvider = this.providers.input;
+        if (!inputProvider)
+            return;
+        const cursorPos = inputProvider.getCursorPosition();
+        // Calculate absolute row: footer start + provider's relative row
+        const footerStartRow = this.scrollRegionBottom + 1;
+        // Find which line in footer is the input
+        // For now, assume input is after subagent + spinner/todo lines
+        let inputStartRow = footerStartRow;
+        if (this.providers.subagent) {
+            inputStartRow += this.providers.subagent.getLines().length;
+        }
+        if (this.providers.spinner?.isAgentRunning()) {
+            inputStartRow += this.providers.spinner.getLines().length;
+        }
+        else if (this.providers.todo) {
+            inputStartRow += this.providers.todo.getLines().length;
+        }
+        // Add provider's relative row
+        const absoluteRow = inputStartRow + cursorPos.row;
+        const absoluteCol = cursorPos.col + 1; // 1-indexed
+        this.write(codes.cursorTo(absoluteRow, absoluteCol));
+        this.write(codes.showCursor);
+    }
+    /**
+     * Position cursor for Footer integration (scroll region mode)
+     */
+    positionFooterCursor() {
+        if (!this.footer)
+            return;
+        const cursorPos = this.footer.getFooterCursorPosition();
+        const footerStartRow = this.scrollRegionBottom + 1;
+        // cursorPos.row is 0-indexed from footer start
+        const absoluteRow = footerStartRow + cursorPos.row;
+        const absoluteCol = cursorPos.col + 1; // 1-indexed
+        this.write(codes.cursorTo(absoluteRow, absoluteCol));
+        this.write(codes.showCursor);
+    }
+    /**
+     * Render OVERLAY mode
+     */
+    renderOverlayMode() {
+        const overlayProvider = this.providers.overlay;
+        if (!overlayProvider || !overlayProvider.isActive()) {
+            this.log('No active overlay provider');
+            return;
+        }
+        const lines = overlayProvider.getLines();
+        // Clear and render from top
+        this.write(codes.cursorHome);
+        this.write(codes.clearToEndOfScreen);
+        for (let i = 0; i < lines.length; i++) {
+            if (i > 0)
+                this.write('\n');
+            this.write(lines[i]);
+        }
+        // Position cursor if overlay needs it
+        const cursorPos = overlayProvider.getCursorPosition();
+        if (cursorPos) {
+            this.write(codes.showCursor);
+            this.write(codes.cursorTo(cursorPos.row + 1, cursorPos.col + 1));
+        }
+        else {
+            this.write(codes.hideCursor);
+        }
+    }
+    // ===========================================================================
+    // Resize Handling
+    // ===========================================================================
+    /**
+     * Handle terminal resize
+     */
+    handleResize() {
+        const oldCols = this.terminalCols;
+        const oldRows = this.terminalRows;
+        this.updateDimensions();
+        this.log(`Resize: ${String(oldCols)}x${String(oldRows)} -> ${String(this.terminalCols)}x${String(this.terminalRows)}`);
+        // Emit event
+        this.emit('resize', this.terminalCols, this.terminalRows);
+        // Mode-specific handling
+        switch (this.mode) {
+            case RenderMode.REPL:
+                // Recalculate scroll region
+                if (this.footerHeight > 0) {
+                    this.scrollRegionBottom = this.terminalRows - this.footerHeight;
+                    this.write(codes.setScrollRegion(1, this.scrollRegionBottom));
+                }
+                break;
+            case RenderMode.MENU:
+            case RenderMode.OVERLAY:
+                // Full screen modes just re-render
+                break;
+        }
+        // Force full re-render
+        this.forceRender();
+    }
+    /**
+     * Update terminal dimensions from stdout
+     */
+    updateDimensions() {
+        this.terminalRows = process.stdout.rows || 24;
+        this.terminalCols = process.stdout.columns || 80;
+    }
+    /**
+     * Get current terminal dimensions
+     */
+    getDimensions() {
+        return { rows: this.terminalRows, cols: this.terminalCols };
+    }
+    // ===========================================================================
+    // Low-Level Output
+    // ===========================================================================
+    /**
+     * Write to stdout (single output point)
+     */
+    write(text) {
+        if (text.length === 0)
+            return;
+        process.stdout.write(text);
+    }
+    // ===========================================================================
+    // Keyboard Routing (stub for Phase 2+)
+    // ===========================================================================
+    /**
+     * Route keyboard input to appropriate handler
+     */
+    handleKeyboard(key) {
+        switch (this.mode) {
+            case RenderMode.MENU:
+                if (this.providers.menu) {
+                    const action = this.providers.menu.handleKey(key);
+                    if (action === 'select') {
+                        // TODO: Handle menu selection (Phase 2)
+                    }
+                    this.requestRender();
+                }
+                break;
+            case RenderMode.REPL:
+                if (this.providers.input) {
+                    const action = this.providers.input.handleKey(key);
+                    if (action) {
+                        // TODO: Handle input action (Phase 4)
+                    }
+                    this.requestRender();
+                }
+                break;
+            case RenderMode.OVERLAY:
+                if (this.providers.overlay) {
+                    const action = this.providers.overlay.handleKey(key);
+                    if (action?.type === 'close') {
+                        this.setMode(RenderMode.REPL, 'overlay-closed');
+                    }
+                    this.requestRender();
+                }
+                break;
+        }
+    }
+    // ===========================================================================
+    // Debug Logging
+    // ===========================================================================
+    /**
+     * Log debug message if debug mode enabled
+     */
+    log(message) {
+        if (this.debug) {
+            const timestamp = new Date().toISOString().slice(11, 23);
+            console.error(`[TerminalRenderer ${timestamp}] ${message}`);
+        }
+    }
+}
+// =============================================================================
+// Singleton Export (optional)
+// =============================================================================
+let defaultRenderer = null;
+/**
+ * Get or create the default renderer instance
+ */
+export function getRenderer(options) {
+    if (!defaultRenderer) {
+        defaultRenderer = new TerminalRenderer(options);
+    }
+    return defaultRenderer;
+}
+/**
+ * Reset the default renderer (for testing)
+ */
+export function resetRenderer() {
+    if (defaultRenderer) {
+        defaultRenderer.stop();
+        defaultRenderer = null;
+    }
+}