@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/terminal-renderer.d.ts

@@ -0,0 +1,221 @@
+/**
+ * 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, type ModeTransition } from './render-modes.js';
+import type { ProviderRegistry } from './providers/types.js';
+import type { Footer } from './footer.js';
+export { RenderMode } from './render-modes.js';
+export interface TerminalRendererOptions {
+    /** Initial render mode (default: REPL) */
+    initialMode?: RenderMode;
+    /** Render debounce in milliseconds (default: 16 = ~60fps) */
+    renderDebounceMs?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Use scroll regions for footer isolation (default: false)
+     * When false, uses console.log for scroll content (legacy mode)
+     * When true, uses ANSI scroll regions (requires footer integration)
+     */
+    useScrollRegions?: boolean;
+}
+export interface TerminalRendererEvents {
+    'mode-change': (transition: ModeTransition) => void;
+    'resize': (cols: number, rows: number) => void;
+    'render': (mode: RenderMode) => void;
+    'error': (error: Error) => void;
+}
+export declare class TerminalRenderer extends EventEmitter {
+    private readonly renderDebounceMs;
+    private readonly debug;
+    private readonly useScrollRegions;
+    private mode;
+    private terminalRows;
+    private terminalCols;
+    private footerHeight;
+    private scrollRegionBottom;
+    private isRendering;
+    private renderPending;
+    private renderTimer;
+    private started;
+    private simpleMode;
+    private pendingScrollContent;
+    private scrollCursorRow;
+    private providers;
+    private footer;
+    private resizeHandler;
+    private renderLoopTimer;
+    private readonly renderLoopInterval;
+    constructor(options?: TerminalRendererOptions);
+    /**
+     * Start the renderer.
+     * Sets up terminal state and begins render loop.
+     */
+    start(): void;
+    /**
+     * Start the render loop (for scroll region mode)
+     * Polls footer for changes and re-renders
+     */
+    private startRenderLoop;
+    /**
+     * Stop the render loop
+     */
+    private stopRenderLoop;
+    /**
+     * Stop the renderer.
+     * Cleans up terminal state and stops render loop.
+     */
+    stop(): void;
+    /**
+     * Check if renderer is running
+     */
+    isStarted(): boolean;
+    /**
+     * Get current render mode
+     */
+    getMode(): RenderMode;
+    /**
+     * Switch to a different render mode
+     */
+    setMode(newMode: RenderMode, reason?: string): void;
+    /**
+     * Set up terminal for a specific mode
+     */
+    private setupMode;
+    /**
+     * Clean up terminal state when leaving a mode
+     */
+    private cleanupMode;
+    /**
+     * Register content providers
+     */
+    setProviders(providers: Partial<ProviderRegistry>): void;
+    /**
+     * Get a specific provider
+     */
+    getProvider<K extends keyof ProviderRegistry>(key: K): ProviderRegistry[K] | undefined;
+    /**
+     * 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: Footer): void;
+    /**
+     * Get the connected Footer instance
+     */
+    getFooter(): Footer | null;
+    /**
+     * 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: string | string[]): void;
+    /**
+     * Flush pending scroll content to terminal
+     *
+     * Uses tracked scroll position to append content naturally.
+     * When content would exceed scroll region, scrolling occurs automatically.
+     */
+    private flushScrollContent;
+    /**
+     * Request a render (debounced)
+     */
+    requestRender(): void;
+    /**
+     * Force immediate render (bypasses debounce)
+     */
+    forceRender(): void;
+    /**
+     * Main render method
+     */
+    private doRender;
+    /**
+     * Render in simple mode (non-TTY)
+     */
+    private renderSimpleMode;
+    /**
+     * Render MENU mode
+     */
+    private renderMenuMode;
+    /**
+     * Render REPL mode
+     */
+    private renderReplMode;
+    /**
+     * Build footer lines from providers
+     */
+    private buildFooterLines;
+    /**
+     * Calculate physical height of lines (accounting for wrapping)
+     */
+    private calculatePhysicalHeight;
+    /**
+     * Adjust scroll region when footer height changes
+     */
+    private adjustScrollRegion;
+    /**
+     * Render footer content
+     */
+    private renderFooter;
+    /**
+     * Position cursor for input (provider-based)
+     */
+    private positionCursor;
+    /**
+     * Position cursor for Footer integration (scroll region mode)
+     */
+    private positionFooterCursor;
+    /**
+     * Render OVERLAY mode
+     */
+    private renderOverlayMode;
+    /**
+     * Handle terminal resize
+     */
+    handleResize(): void;
+    /**
+     * Update terminal dimensions from stdout
+     */
+    private updateDimensions;
+    /**
+     * Get current terminal dimensions
+     */
+    getDimensions(): {
+        rows: number;
+        cols: number;
+    };
+    /**
+     * Write to stdout (single output point)
+     */
+    write(text: string): void;
+    /**
+     * Route keyboard input to appropriate handler
+     */
+    handleKeyboard(key: Buffer): void;
+    /**
+     * Log debug message if debug mode enabled
+     */
+    private log;
+}
+/**
+ * Get or create the default renderer instance
+ */
+export declare function getRenderer(options?: TerminalRendererOptions): TerminalRenderer;
+/**
+ * Reset the default renderer (for testing)
+ */
+export declare function resetRenderer(): void;