@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/terminal-ui.js

@@ -0,0 +1,819 @@
+/**
+ * TerminalUI - Single Renderer for Terminal Applications
+ *
+ * Single point of control for all terminal UI:
+ * - Owns all rendering decisions (when to clear, when to render)
+ * - Owns all UI state (agentRunning, todos, currentTool, etc.)
+ * - Provides output methods that handle clear/render automatically
+ * - Manages overlays (render, input routing)
+ * - REPL emits events, doesn't manage rendering timing
+ *
+ * Key principles:
+ * - NO scroll regions (preserves terminal scrollback)
+ * - Deterministic render cycle
+ * - All output goes through TerminalUI (no external console.log)
+ */
+import { EventEmitter } from 'events';
+import { getVisibleLength } from './line-utils.js';
+import { getStyles } from '../themes/index.js';
+import { renderItem } from './terminal-render-item.js';
+import { TurnMetrics } from './turn-metrics.js';
+import { StatusBarController } from './status-bar-controller.js';
+import { ConversationStore } from './conversation-store.js';
+import { AutocompleteController } from './autocomplete-controller.js';
+import { InputController } from './input-controller.js';
+import { LiveRegionFacade } from './live-region-facade.js';
+import { OverlayManager } from './overlay-manager.js';
+import { FooterRenderer } from './footer-renderer.js';
+import { KeyboardHandler } from './keyboard-handler.js';
+import { DEFAULT_TERMINAL_UI_CONFIG, } from './terminal-types.js';
+export { DEFAULT_TERMINAL_UI_CONFIG, MASCOT } from './terminal-types.js';
+import { getPendingRequestsManager } from '../multi-agent/index.js';
+import { getSessionRegistry } from '../multi-agent/session-registry.js';
+import { getNotificationManager } from '../multi-agent/notification-manager.js';
+// =============================================================================
+// Footer V2 Class
+// =============================================================================
+export class TerminalUI extends EventEmitter {
+    // Configuration
+    promptPrefix;
+    promptPrefixLen;
+    config;
+    // Conversation history, restored history, and filtering
+    conversation = new ConversationStore();
+    // Input state (delegated to InputController)
+    input = new InputController();
+    get lines() { return this.input.lines; }
+    set lines(v) { this.input.lines = v; }
+    get currentLine() { return this.input.currentLine; }
+    set currentLine(v) { this.input.currentLine = v; }
+    get cursorPos() { return this.input.cursorPos; }
+    set cursorPos(v) { this.input.cursorPos = v; }
+    get suggestion() { return this.input.suggestion; }
+    set suggestion(v) { this.input.suggestion = v; }
+    get queuedInputs() { return this.input.queuedInputs; }
+    set queuedInputs(v) { this.input.queuedInputs = v; }
+    mode;
+    projectName = null;
+    todos = [];
+    // Plan mode state
+    activePlanId = null;
+    activePlanName = null;
+    spinnerText = null;
+    agentRunning = false;
+    agentMessageQueue = [];
+    currentTool = null;
+    // Per-turn token and tool call tracking
+    turnMetrics = new TurnMetrics();
+    // LiveRegion for running tools (bash, subagents)
+    live = new LiveRegionFacade({
+        requestRender: () => { this.needsRender = true; },
+        print: (item) => { this.print(item); },
+        emit: (event, ...args) => { this.emit(event, ...args); },
+        setSpinnerText: (text) => { this.spinnerText = text; },
+    });
+    // Autocomplete controller (command, file, agent)
+    ac = new AutocompleteController();
+    // Render tracking
+    isRunning = false;
+    isPaused = false;
+    renderTimer = null;
+    needsRender = false;
+    // Active team agent (for multi-agent footer display)
+    activeTeamAgent = null;
+    // Todo visibility (Ctrl+T to toggle)
+    showTodos = true;
+    // View mode (Ctrl+O to toggle verbose view)
+    // normal: compact output
+    // verbose-temp: temporarily show last N items verbose (any key returns to normal)
+    viewMode = 'normal';
+    // Status bar navigation (down arrow into footer indicators)
+    statusBar = new StatusBarController({
+        requestRender: () => { this.needsRender = true; },
+        emit: (event, ...args) => { this.emit(event, ...args); },
+    });
+    // Overlay lifecycle (stack, resolvers, render state, print buffer)
+    overlay = new OverlayManager({
+        clearFooter: () => { this.footer.clear(); },
+        renderFooter: () => { this.footer.render(); },
+        print: (item) => { this.print(item); },
+        renderItemToConsole: (item) => { this.renderItemToConsole(item); },
+    });
+    // Footer renderer (clear, render, spinner animation, line builders)
+    footer = new FooterRenderer({
+        isFooterRenderAllowed: () => this.isRunning && !this.isPaused && !this.overlay.hasActiveOverlay(),
+        getRenderData: () => ({
+            liveRegion: this.live.region,
+            liveVerbose: this.config.verbose,
+            agentRunning: this.agentRunning,
+            currentTool: this.currentTool,
+            spinnerText: this.spinnerText,
+            activeBashInfo: this.live.getActiveBashInfo(),
+            turnMetrics: this.turnMetrics,
+            todos: this.todos,
+            showTodos: this.showTodos,
+            lines: this.lines,
+            currentLine: this.currentLine,
+            cursorPos: this.cursorPos,
+            queuedInputs: this.queuedInputs,
+            suggestion: this.suggestion,
+            promptPrefix: this.promptPrefix,
+            promptPrefixLen: this.promptPrefixLen,
+            ac: this.ac,
+            statusBar: this.statusBar,
+            mode: this.mode,
+            activePlanName: this.activePlanName,
+            activeTeamAgent: this.activeTeamAgent,
+            projectName: this.projectName,
+            conversationFilterActive: this.conversation.isFilterActive,
+            hasRestoredHistory: this.conversation.hasRestoredHistory(),
+            config: this.config,
+        }),
+    });
+    // Keyboard input handler (capture, escape, overlay routing, keypress dispatch)
+    keyboard = new KeyboardHandler({
+        isGuardActive: () => !this.isRunning || this.isPaused,
+        isAgentRunning: () => this.agentRunning,
+        getViewMode: () => this.viewMode,
+        setViewMode: (mode) => { this.viewMode = mode; },
+        requestRender: () => { this.needsRender = true; },
+        emit: (event, ...args) => { this.emit(event, ...args); },
+        input: this.input,
+        ac: this.ac,
+        overlay: this.overlay,
+        statusBar: this.statusBar,
+        getActiveOverlay: () => this.overlay.getActiveOverlay(),
+        hasActiveOverlay: () => this.overlay.hasActiveOverlay(),
+        hasActiveBash: () => this.live.hasActiveBash(),
+        backgroundBashCommand: () => { this.backgroundBashCommand(); },
+        hasRestoredHistory: () => this.conversation.hasRestoredHistory(),
+        showRestoredHistory: () => { this.showRestoredHistory(); },
+        toggleVerboseView: () => { this.toggleVerboseView(); },
+        toggleLiveRegionExpanded: () => { this.toggleLiveRegionExpanded(); },
+        toggleTodos: () => { this.toggleTodos(); },
+        reRenderConversationVerbose: (verbose) => { this.reRenderConversationVerbose(verbose); },
+    });
+    constructor(options = {}) {
+        super();
+        const s = getStyles();
+        this.promptPrefix = options.prompt ?? s.primaryBold('compilr>') + ' ';
+        this.promptPrefixLen = getVisibleLength(this.promptPrefix);
+        this.mode = options.initialMode ?? 'normal';
+        this.config = { ...DEFAULT_TERMINAL_UI_CONFIG, ...options.config };
+    }
+    // ===========================================================================
+    // Status bar navigation (delegated to StatusBarController)
+    // ===========================================================================
+    /** Set background agent count (called by REPL to keep UI in sync). */
+    setBackgroundAgentCount(count) {
+        this.statusBar.setBackgroundAgentCount(count);
+    }
+    /** Set MCP loading state for status bar indicator. */
+    setMCPLoading(loading, toolCount) {
+        this.statusBar.setMCPLoading(loading, toolCount);
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    start(skipInitialRender) {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        this.isPaused = false;
+        // Start keyboard input handling
+        this.keyboard.startCapture();
+        // Initial render (skip when a startup overlay will be shown immediately)
+        if (!skipInitialRender) {
+            this.footer.render();
+        }
+        // Phase 3b: Listen for pending requests changes to trigger re-render
+        const pendingManager = getPendingRequestsManager();
+        pendingManager.on('count-changed', () => {
+            this.needsRender = true;
+        });
+        // Multi-terminal: Listen for session count changes (other terminals joining/leaving)
+        const registry = getSessionRegistry();
+        if (registry) {
+            registry.onCountChange(() => {
+                this.needsRender = true;
+            });
+        }
+        // Cross-session notifications: re-render when count changes
+        const notifMgr = getNotificationManager();
+        if (notifMgr) {
+            notifMgr.on('count-changed', () => {
+                this.needsRender = true;
+            });
+        }
+        // Start render loop (60ms = ~16fps)
+        this.renderTimer = setInterval(() => {
+            if (this.needsRender && !this.isPaused) {
+                this.footer.render();
+                this.needsRender = false;
+            }
+        }, 60);
+    }
+    stop() {
+        if (!this.isRunning)
+            return;
+        this.isRunning = false;
+        // Stop render loop
+        if (this.renderTimer) {
+            clearInterval(this.renderTimer);
+            this.renderTimer = null;
+        }
+        // Stop spinner
+        this.footer.stopSpinnerAnimation();
+        // Stop keyboard capture
+        this.keyboard.stopCapture();
+        // Clear footer
+        this.footer.clear();
+    }
+    // ===========================================================================
+    // Public API - Output (THE KEY METHODS)
+    // ===========================================================================
+    /**
+     * Print a semantic item to the scrolling zone.
+     * Items are stored in conversation history for re-rendering when config changes.
+     *
+     * IMPORTANT: When an overlay is active, items are buffered and rendered after
+     * the overlay closes. This prevents cursor position corruption that causes
+     * ghost lines and visual artifacts.
+     */
+    print(item) {
+        // Store in history for re-render capability
+        this.conversation.addItem(item);
+        // Check if item should be shown based on current filter
+        if (!this.conversation.shouldShowItem(item)) {
+            return; // Filtered out - stored but not displayed
+        }
+        // If overlay is active, buffer the item to render later
+        // This prevents output from corrupting overlay cursor tracking
+        if (this.overlay.hasActiveOverlay()) {
+            this.overlay.bufferItem(item);
+            return;
+        }
+        // IMPORTANT: If needsRender is true, render FIRST to update lastRenderHeight.
+        // This prevents ghost lines when footer height changed (e.g., spinner started)
+        // but render loop hasn't fired yet. Without this, clear() uses stale height.
+        if (this.needsRender) {
+            this.footer.render();
+            this.needsRender = false;
+        }
+        // Clear footer, render item, re-render footer
+        this.footer.clear();
+        this.renderItemToConsole(item);
+        this.footer.render();
+    }
+    /**
+     * Render a single item to the console.
+     * Config-aware: respects verbose, showMascot settings.
+     * Delegates to standalone renderItem() function.
+     */
+    renderItemToConsole(item) {
+        const suggestion = renderItem(item, this.config);
+        if (suggestion !== null) {
+            this.setSuggestion(suggestion);
+        }
+    }
+    /**
+     * Execute a callback that outputs to terminal.
+     * Handles clear → callback → render automatically.
+     * Use this for complex output that needs multiple console.log calls.
+     * @deprecated Prefer using print() with PrintableItem
+     */
+    output(callback) {
+        this.footer.clear();
+        callback();
+        this.footer.render();
+    }
+    // ===========================================================================
+    // Public API - State setters
+    // ===========================================================================
+    setAgentRunning(running) {
+        const wasRunning = this.agentRunning;
+        this.agentRunning = running;
+        if (running && !wasRunning) {
+            this.footer.startSpinnerAnimation(() => { this.needsRender = true; });
+            // Let render loop handle it
+        }
+        else if (!running && wasRunning) {
+            this.footer.stopSpinnerAnimation();
+            this.currentTool = null;
+        }
+        this.needsRender = true;
+    }
+    isAgentRunning() {
+        return this.agentRunning;
+    }
+    setTodos(todos) {
+        this.todos = todos;
+        this.needsRender = true;
+    }
+    getTodos() {
+        return [...this.todos];
+    }
+    setSpinnerText(text) {
+        this.spinnerText = text;
+        this.needsRender = true;
+    }
+    setCurrentTool(tool) {
+        this.currentTool = tool;
+        if (tool) {
+            this.spinnerText = tool;
+        }
+        this.needsRender = true;
+    }
+    /**
+     * Set whether extended thinking mode is active
+     * Shows "thinking" indicator in status line
+     */
+    setThinking(thinking) {
+        this.turnMetrics.isThinking = thinking;
+        this.needsRender = true;
+    }
+    // ===========================================================================
+    // Token Tracking (per-turn metrics)
+    // ===========================================================================
+    /**
+     * Add input/output tokens for live display
+     * @param thinkingTokens - Optional thinking tokens (Gemini 2.5+ models)
+     * @param cacheReadTokens - Optional cache read tokens (Anthropic/Gemini)
+     * @param debugPayload - Optional debug payload sizes (char counts)
+     */
+    addTokens(inputTokens, outputTokens, thinkingTokens, cacheReadTokens, debugPayload) {
+        this.turnMetrics.addTokens(inputTokens, outputTokens, thinkingTokens, cacheReadTokens, debugPayload);
+        this.needsRender = true;
+    }
+    /**
+     * Increment tool call counter
+     */
+    incrementToolCalls() {
+        this.turnMetrics.incrementToolCalls();
+    }
+    /**
+     * Increment API call counter (called on each LLM request completion)
+     */
+    incrementApiCalls() {
+        this.turnMetrics.incrementApiCalls();
+    }
+    /**
+     * Reset turn metrics (call when agent starts a new turn)
+     */
+    resetTurnMetrics() {
+        this.turnMetrics.reset();
+    }
+    /**
+     * Get current turn metrics
+     */
+    getTurnMetrics() {
+        return this.turnMetrics.getSnapshot();
+    }
+    setMode(mode) {
+        this.mode = mode;
+        this.needsRender = true;
+    }
+    getMode() {
+        return this.mode;
+    }
+    setProjectName(name) {
+        this.projectName = name;
+        this.needsRender = true;
+    }
+    getProjectName() {
+        return this.projectName;
+    }
+    /**
+     * Set the active team agent (displayed in footer)
+     * Pass null to clear (default agent or no team)
+     */
+    setActiveTeamAgent(agent) {
+        this.activeTeamAgent = agent;
+        this.needsRender = true;
+    }
+    /**
+     * Get the active team agent
+     */
+    getActiveTeamAgent() {
+        return this.activeTeamAgent;
+    }
+    /**
+     * Set the callback to get available team agents for $ autocomplete
+     */
+    setAgentSuggestionsCallback(callback) {
+        this.ac.getAgentSuggestions = callback;
+    }
+    /**
+     * Set the callback to get available commands for / autocomplete
+     */
+    setCommandsCallback(callback) {
+        this.ac.getCommands = callback;
+    }
+    /**
+     * Set the active plan (for Plan Mode display in footer)
+     */
+    setActivePlan(planId, planName) {
+        this.activePlanId = planId;
+        this.activePlanName = planName;
+        this.needsRender = true;
+    }
+    /**
+     * Get the active plan info
+     */
+    getActivePlan() {
+        return { id: this.activePlanId, name: this.activePlanName };
+    }
+    /**
+     * Clear the active plan
+     */
+    clearActivePlan() {
+        this.activePlanId = null;
+        this.activePlanName = null;
+        this.needsRender = true;
+    }
+    /**
+     * Set ghost text suggestion (shown when input is empty)
+     */
+    setSuggestion(text) {
+        this.input.suggestion = text;
+        this.needsRender = true;
+    }
+    getSuggestion() {
+        return this.input.suggestion;
+    }
+    clearSuggestion() {
+        this.input.suggestion = null;
+        this.needsRender = true;
+    }
+    // ===========================================================================
+    // Public API - LiveRegion (subagents, bash commands)
+    // ===========================================================================
+    addSubagent(id, agentType, description) {
+        this.live.addSubagent(id, agentType, description);
+    }
+    updateSubagentTool(id, toolName, summary) {
+        this.live.updateSubagentTool(id, toolName, summary);
+    }
+    completeSubagent(id, success, tokenCount, _error) {
+        this.live.completeSubagent(id, success, tokenCount, _error);
+    }
+    removeSubagent(id) {
+        return this.live.removeSubagent(id);
+    }
+    clearLiveRegion() {
+        this.live.clearLiveRegion();
+    }
+    toggleLiveRegionExpanded() {
+        this.live.toggleLiveRegionExpanded();
+    }
+    hasLiveItems() {
+        return this.live.hasLiveItems();
+    }
+    getLiveRegion() {
+        return this.live.getLiveRegion();
+    }
+    addBashCommand(id, command) {
+        this.live.addBashCommand(id, command);
+    }
+    updateBashOutput(id, line) {
+        this.live.updateBashOutput(id, line);
+    }
+    completeBashCommand(id, exitCode) {
+        this.live.completeBashCommand(id, exitCode);
+    }
+    commitBashCommand(id) {
+        this.live.commitBashCommand(id);
+    }
+    backgroundBashCommand() {
+        this.live.backgroundBashCommand();
+    }
+    hasActiveBash() {
+        return this.live.hasActiveBash();
+    }
+    getActiveBashInfo() {
+        return this.live.getActiveBashInfo();
+    }
+    commitSubagent(id, resultContent, success) {
+        return this.live.commitSubagent(id, resultContent, success);
+    }
+    /**
+     * Toggle todo list visibility (Ctrl+T)
+     */
+    toggleTodos() {
+        this.showTodos = !this.showTodos;
+        this.needsRender = true;
+    }
+    /**
+     * Set todo list visibility
+     */
+    setShowTodos(show) {
+        this.showTodos = show;
+        this.needsRender = true;
+    }
+    /**
+     * Get todo list visibility
+     */
+    getShowTodos() {
+        return this.showTodos;
+    }
+    /**
+     * Toggle verbose view mode (Ctrl+O)
+     * Shows conversation in verbose mode temporarily.
+     * Any key returns to normal view.
+     */
+    toggleVerboseView() {
+        if (this.viewMode === 'normal') {
+            this.viewMode = 'verbose-temp';
+            this.reRenderConversationVerbose(true);
+        }
+        else {
+            this.viewMode = 'normal';
+            this.reRenderConversationVerbose(false);
+        }
+    }
+    /**
+     * Re-render conversation with temporary verbose setting.
+     */
+    reRenderConversationVerbose(verbose) {
+        const s = getStyles();
+        // Clear screen and scrollback buffer
+        process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+        // Reset footer state
+        this.footer.resetRenderState();
+        // Show mode indicator at top
+        if (verbose) {
+            console.log(s.info(`[Verbose View Mode] Press any key to return to normal view`));
+            console.log('');
+        }
+        // Re-render all items with temporary verbose override
+        const originalVerbose = this.config.verbose;
+        this.config.verbose = verbose;
+        for (const item of this.conversation.history) {
+            this.renderItemToConsole(item);
+        }
+        // Restore original config
+        this.config.verbose = originalVerbose;
+        // Footer will be re-rendered by the render loop
+        this.needsRender = true;
+    }
+    // ===========================================================================
+    // Public API - Restored History (Ctrl+R)
+    // ===========================================================================
+    /**
+     * Store restored conversation items for Ctrl+R history view.
+     * Called when a session is resumed/restored.
+     */
+    setRestoredHistory(items) {
+        this.conversation.setRestoredHistory(items);
+    }
+    /**
+     * Check if there is restored history available.
+     */
+    hasRestoredHistory() {
+        return this.conversation.hasRestoredHistory();
+    }
+    /**
+     * Show restored conversation history (Ctrl+R).
+     * Renders items permanently into the scrollback buffer.
+     * Stays in normal mode — the output persists like any other printed content.
+     */
+    showRestoredHistory() {
+        const s = getStyles();
+        // Clear existing footer to make room for output
+        this.footer.clear();
+        // Print header
+        console.log('');
+        console.log(s.info(`── Conversation History (${String(this.conversation.restoredHistory.length)} items) ──`));
+        console.log('');
+        // Render each restored item into the scrollback
+        for (const item of this.conversation.restoredHistory) {
+            this.renderItemToConsole(item);
+        }
+        console.log('');
+        console.log(s.muted(`── End of history ──`));
+        console.log('');
+        // Reset footer state so it re-renders cleanly below the output
+        this.footer.resetRenderState();
+        this.needsRender = true;
+    }
+    // ===========================================================================
+    // Public API - Config
+    // ===========================================================================
+    /**
+     * Update configuration at runtime.
+     * If verbose changes, re-renders the entire conversation.
+     */
+    setConfig(newConfig) {
+        const oldVerbose = this.config.verbose;
+        this.config = { ...this.config, ...newConfig };
+        // If verbose changed, re-render entire conversation
+        if (newConfig.verbose !== undefined && newConfig.verbose !== oldVerbose) {
+            this.reRenderConversation();
+        }
+        // Theme change requires prompt refresh
+        if (newConfig.theme !== undefined) {
+            this.refreshPrompt();
+        }
+        this.needsRender = true;
+    }
+    /**
+     * Get current configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Re-render entire conversation with current config.
+     * Called when verbose mode changes.
+     */
+    reRenderConversation() {
+        // Clear screen AND scrollback buffer, then move to home
+        process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+        // Reset footer state since we cleared everything
+        this.footer.resetRenderState();
+        // Show filter indicator if active
+        if (this.conversation.isFilterActive) {
+            const agentList = [...this.conversation.filterAgentIds].map(id => `$${id}`).join(', ');
+            const s = getStyles();
+            console.log(s.muted(`── Showing messages from: ${agentList} ──`));
+            console.log('');
+        }
+        // Re-render all items with new config (applying filter)
+        for (const item of this.conversation.history) {
+            if (this.conversation.shouldShowItem(item)) {
+                this.renderItemToConsole(item);
+            }
+        }
+        // Footer will be re-rendered by the render loop
+        this.needsRender = true;
+    }
+    // ===========================================================================
+    // Public API - Conversation History
+    // ===========================================================================
+    /**
+     * Clear conversation history.
+     * Called by /clear command.
+     */
+    clearConversationHistory() {
+        this.conversation.clearHistory();
+    }
+    /**
+     * Get conversation history (copy).
+     */
+    getConversationHistory() {
+        return this.conversation.getHistory();
+    }
+    // ===========================================================================
+    // Public API - Conversation Filter (delegated to ConversationStore)
+    // ===========================================================================
+    setConversationFilter(agentIds) {
+        this.conversation.setFilter(agentIds);
+        this.reRenderConversation();
+    }
+    clearConversationFilter() {
+        this.conversation.clearFilter();
+        this.reRenderConversation();
+    }
+    getConversationFilter() {
+        return this.conversation.getFilter();
+    }
+    addToConversationFilter(agentId) {
+        return this.conversation.addToFilter(agentId);
+    }
+    isAgentInFilter(agentId) {
+        return this.conversation.isAgentInFilter(agentId);
+    }
+    // ===========================================================================
+    // Public API - Overlays (delegated to OverlayManager)
+    // ===========================================================================
+    hasActiveOverlay() {
+        return this.overlay.hasActiveOverlay();
+    }
+    getActiveOverlay() {
+        return this.overlay.getActiveOverlay();
+    }
+    async showOverlay(overlay) {
+        return this.overlay.showOverlay(overlay);
+    }
+    requestOverlayRender() {
+        this.overlay.requestOverlayRender();
+    }
+    // ===========================================================================
+    // Public API - Input queue
+    // ===========================================================================
+    getQueuedInputs() {
+        return this.input.getQueuedInputs();
+    }
+    popQueuedInput() {
+        const result = this.input.popQueuedInput();
+        if (result !== null)
+            this.needsRender = true;
+        return result;
+    }
+    hasQueuedInput() {
+        return this.input.hasQueuedInput();
+    }
+    clearQueue() {
+        this.input.clearQueue();
+        this.needsRender = true;
+    }
+    // ===========================================================================
+    // Public API - Agent message queue
+    // ===========================================================================
+    /**
+     * Queue a message to be sent to the agent.
+     * Used by commands that need to invoke the agent programmatically.
+     */
+    queueAgentMessage(options) {
+        this.agentMessageQueue.push(options);
+    }
+    /**
+     * Pop the next agent message from the queue.
+     */
+    popAgentMessage() {
+        return this.agentMessageQueue.shift() ?? null;
+    }
+    /**
+     * Check if there are queued agent messages.
+     */
+    hasAgentMessage() {
+        return this.agentMessageQueue.length > 0;
+    }
+    /**
+     * Clear all queued agent messages.
+     */
+    clearAgentMessageQueue() {
+        this.agentMessageQueue = [];
+    }
+    // ===========================================================================
+    // Public API - Animation control (for overlays)
+    // ===========================================================================
+    /**
+     * Pause footer completely (for overlays)
+     */
+    pauseAnimation() {
+        this.isPaused = true;
+        // Stop render loop
+        if (this.renderTimer) {
+            clearInterval(this.renderTimer);
+            this.renderTimer = null;
+        }
+        // Stop spinner
+        this.footer.stopSpinnerAnimation();
+        // Stop keyboard capture
+        this.keyboard.stopCapture();
+        // Clear footer from screen
+        this.footer.clear();
+    }
+    /**
+     * Resume footer after pause
+     */
+    resumeAnimation() {
+        this.isPaused = false;
+        // Resume spinner if agent running
+        if (this.agentRunning) {
+            this.footer.startSpinnerAnimation(() => { this.needsRender = true; });
+        }
+        // Restart keyboard capture
+        this.keyboard.startCapture();
+        // Restart render loop
+        this.footer.render();
+        this.renderTimer = setInterval(() => {
+            if (this.needsRender && !this.isPaused) {
+                this.footer.render();
+                this.needsRender = false;
+            }
+        }, 60);
+    }
+    /**
+     * Restart input after command
+     */
+    restartInput() {
+        this.footer.render();
+    }
+    /**
+     * Refresh prompt with theme colors
+     */
+    refreshPrompt() {
+        const s = getStyles();
+        this.promptPrefix = s.primaryBold('compilr>') + ' ';
+        this.promptPrefixLen = getVisibleLength(this.promptPrefix);
+        this.needsRender = true;
+    }
+    // ===========================================================================
+    // Public API - Legacy compatibility (for gradual migration)
+    // ===========================================================================
+    /**
+     * @deprecated Use print() or output() instead
+     */
+    clearForOutput() {
+        this.footer.clear();
+    }
+    /**
+     * @deprecated Use print() or output() instead
+     */
+    forceRender() {
+        this.footer.render();
+        this.needsRender = false;
+    }
+}