@kikkimo/claude-launcher 2.5.0 → 3.1.0

package/lib/ui/prompts.js

@@ -4,6 +4,7 @@
 
 const readline = require('readline');
 const colors = require('./colors');
+const screen = require('./screen');
 const { getAllProviders } = require('../presets/providers');
 const { validateBaseUrl, validateAuthToken, validateModel } = require('../validators');
 const i18n = require('../i18n');
@@ -20,10 +21,14 @@ async function simpleInput(prompt) {
         });
 
         const rl = scope.createReadline();
+        screen.showCursor();
+        screen.setReadlineActive(true);
 
         rl.question(prompt, (answer) => {
             rl.close();
             scope.release();
+            screen.setReadlineActive(false);
+            screen.hideCursor();
             resolve(answer.trim());
         });
     });
@@ -35,7 +40,8 @@ async function simpleInput(prompt) {
 async function getProviderChoice(prompt) {
     return new Promise((resolve) => {
         if (process.stdin.isTTY) {
-            process.stdout.write(colors.green + prompt + colors.reset);
+            screen.showCursor();
+            screen.write(colors.green + prompt + colors.reset);
 
             let input = '';
             const scope = stdinManager.acquire('raw', {
@@ -53,7 +59,8 @@ async function getProviderChoice(prompt) {
                     // Resolve with null to indicate cancellation (same as ESC key).
                     const exited = stdinManager.handleCtrlC();
                     if (exited === false) {
-                        process.stdout.write('\n');
+                        screen.write('\n');
+                        screen.hideCursor();
                         resolve(null); // User cancelled with Ctrl+C
                     }
                     return;
@@ -68,13 +75,15 @@ async function getProviderChoice(prompt) {
                 switch (keyCode) {
                     case 27: // ESC key
                         scope.release();
-                        process.stdout.write('\n');
+                        screen.write('\n');
+                        screen.hideCursor();
                         resolve(null);
                         return;
 
                     case 13: // Enter key
                         scope.release();
-                        process.stdout.write('\n');
+                        screen.write('\n');
+                        screen.hideCursor();
                         resolve(input);
                         return;
 
@@ -82,7 +91,7 @@ async function getProviderChoice(prompt) {
                     case 8:   // Backspace (some terminals)
                         if (input.length > 0) {
                             input = input.slice(0, -1);
-                            process.stdout.write('\b \b');
+                            screen.write('\b \b');
                         }
                         return;
 
@@ -90,7 +99,7 @@ async function getProviderChoice(prompt) {
                         // Only accept printable ASCII characters
                         if (keyCode >= 32 && keyCode < 127) {
                             input += key;
-                            process.stdout.write(key);
+                            screen.write(key);
                         }
                         return;
                 }
@@ -117,7 +126,7 @@ async function getProviderChoice(prompt) {
  * Wait for any key press
  */
 async function waitForKey(message = 'Press any key to continue...') {
-    console.log(colors.gray + message + colors.reset);
+    screen.write(colors.gray + message + colors.reset + '\n');
 
     return new Promise((resolve) => {
         if (process.stdin.isTTY) {
@@ -173,119 +182,141 @@ async function waitForKey(message = 'Press any key to continue...') {
 }
 
 /**
- * Prompt for third-party API configuration with enhanced guidance
+ * Display provider selection list and return selected provider
+ * @param {Object} options - { title: string|null, showNote: boolean }
+ * @returns {Object|null} Selected provider { id, name, baseUrl, models, note } or null on cancel
  */
-async function promptForThirdPartyApi() {
-    try {
-        // Step 1: Show information and wait for acknowledgment
-        console.clear();
-        console.log('');
-        console.log(colors.bright + colors.orange + i18n.tSync('ui.general.add_new_api_title') + colors.reset);
-        console.log('');
-
-        // Security and privacy information
-        console.log(colors.yellow + i18n.tSync('ui.general.security_privacy_info') + colors.reset);
-        const securityItems = i18n.tSync('ui.general.security_items');
-        securityItems.forEach(item => {
-            console.log(colors.bright + colors.green + '  • ' + item + colors.reset);
-        });
-        console.log('');
+async function selectProvider({ title = null, showNote = true } = {}) {
+    const lines = [];
+    if (title) {
+        lines.push(colors.cyan + title + colors.reset);
+        lines.push('');
+    }
 
-        console.log(colors.yellow + i18n.tSync('ui.general.configuration_tips') + colors.reset);
-        const configTips = i18n.tSync('ui.general.config_tip_items');
-        configTips.forEach(tip => {
-            console.log(colors.gray + '  • ' + tip + colors.reset);
-        });
-        console.log(colors.gray + '  • ' + i18n.tSync('ui.general.type_exit_cancel') + colors.reset);
-        console.log('');
+    const providers = getAllProviders();
+    providers.forEach((provider, index) => {
+        const compatIcon = provider.compatibility === 'native' ? '🎯' : '✅';
+        lines.push(colors.gray + `  ${index + 1}. ${compatIcon} ${provider.name}` + colors.reset);
+        lines.push(colors.dim + `     ${provider.description}` + colors.reset);
+    });
+    lines.push('');
+    screen.render(lines);
 
-        console.log(colors.yellow + i18n.tSync('ui.general.all_providers_compatible') + colors.reset);
-        console.log('');
+    while (true) {
+        const selectPrompt = i18n.tSync('ui.general.select_provider_prompt').replace('{0}', providers.length);
+        const providerChoice = await getProviderChoice(selectPrompt);
 
-        await waitForKey(i18n.tSync('ui.general.press_continue_provider_selection'));
+        if (providerChoice === null) {
+            return null; // Esc cancel
+        }
 
-        // Step 2: Show provider selection menu
-        console.clear();
-        console.log('');
-        console.log(colors.bright + colors.orange + i18n.tSync('ui.general.add_new_api_title') + colors.reset);
-        console.log('');
-
-        // Show available providers
-        console.log(colors.cyan + i18n.tSync('ui.general.compatible_providers_title') + colors.reset);
-        console.log('');
-        const providers = getAllProviders();
-        providers.forEach((provider, index) => {
-            const compatIcon = provider.compatibility === 'native' ? '🎯' : '✅';
-            console.log(colors.gray + `  ${index + 1}. ${compatIcon} ${provider.name}` + colors.reset);
-            console.log(colors.dim + `     ${provider.description}` + colors.reset);
-        });
-        console.log('');
+        if (providerChoice.toLowerCase() === 'exit' || providerChoice.toLowerCase() === 'quit') {
+            return null; // exit/quit cancel
+        }
 
-        // Select provider or custom with validation
-        let selectedProvider = null;
-        let baseUrl = '';
-        let suggestedModels = [];
+        if (!providerChoice || providerChoice.trim() === '') {
+            screen.write(colors.red + i18n.tSync('ui.general.provider_selection_required', providers.length) + colors.reset + '\n');
+            continue;
+        }
 
-        while (true) {
-            const selectPrompt = i18n.tSync('ui.general.select_provider_prompt').replace('{0}', providers.length);
-            const providerChoice = await getProviderChoice(selectPrompt);
+        if (isNaN(providerChoice)) {
+            screen.write(colors.red + i18n.tSync('ui.general.invalid_provider_selection').replace('{0}', providers.length) + colors.reset + '\n');
+            continue;
+        }
 
-            if (providerChoice === null) {
-                // User cancelled with ESC
-                throw new Error(i18n.tSync('errors.general.cancelled_by_user'));
-            }
+        const index = parseInt(providerChoice) - 1;
+        if (index < 0 || index >= providers.length) {
+            screen.write(colors.red + i18n.tSync('ui.general.invalid_provider_number').replace('{0}', providers.length) + colors.reset + '\n');
+            continue;
+        }
 
-            if (providerChoice.toLowerCase() === 'exit' || providerChoice.toLowerCase() === 'quit') {
-                throw new Error(i18n.tSync('errors.general.cancelled_by_user'));
-            }
+        const selectedProvider = providers[index];
 
-            // Require non-empty input
-            if (!providerChoice || providerChoice.trim() === '') {
-                console.log(colors.red + i18n.tSync('ui.general.provider_selection_required', providers.length) + colors.reset);
-                continue;
+        screen.write('\n');
+        screen.write(colors.green + i18n.tSync('ui.general.selected_provider', selectedProvider.name) + colors.reset + '\n');
+        if (showNote && selectedProvider.note) {
+            if (selectedProvider.id === 'custom') {
+                screen.write(colors.yellow + '  ' + i18n.tSync('ui.general.replace_url_model_note') + colors.reset + '\n');
+            } else {
+                const noteKey = `provider.notes.${selectedProvider.id}`;
+                const noteText = i18n.tSync(noteKey);
+                const displayNote = noteText === noteKey ? selectedProvider.note : noteText;
+                const notePrefix = i18n.tSync('provider.note_prefix');
+                screen.write(colors.yellow + `  ${notePrefix}: ${displayNote}` + colors.reset + '\n');
             }
+        }
+        screen.write('\n');
 
-            // Validate numeric input
-            if (isNaN(providerChoice)) {
-                console.log(colors.red + i18n.tSync('ui.general.invalid_provider_selection').replace('{0}', providers.length) + colors.reset);
-                continue;
-            }
+        return {
+            id: selectedProvider.id,
+            name: selectedProvider.name,
+            baseUrl: selectedProvider.baseUrl,
+            models: selectedProvider.models || [],
+            note: selectedProvider.note || null
+        };
+    }
+}
 
-            const index = parseInt(providerChoice) - 1;
-            if (index < 0 || index >= providers.length) {
-                console.log(colors.red + i18n.tSync('ui.general.invalid_provider_number').replace('{0}', providers.length) + colors.reset);
-                continue;
-            }
+/**
+ * Prompt for third-party API configuration with enhanced guidance
+ */
+async function promptForThirdPartyApi() {
+    try {
+        // Step 1: Show information and wait for acknowledgment
+        {
+            const lines = [];
+            lines.push('');
+            lines.push(colors.bright + colors.orange + i18n.tSync('ui.general.add_new_api_title') + colors.reset);
+            lines.push('');
+
+            // Security and privacy information
+            lines.push(colors.yellow + i18n.tSync('ui.general.security_privacy_info') + colors.reset);
+            const securityItems = i18n.tSync('ui.general.security_items');
+            securityItems.forEach(item => {
+                lines.push(colors.bright + colors.green + '  • ' + item + colors.reset);
+            });
+            lines.push('');
 
-            // Valid selection
-            selectedProvider = providers[index];
-            baseUrl = selectedProvider.baseUrl;
-            suggestedModels = selectedProvider.models || [];
-
-            console.log('');
-            console.log(colors.green + i18n.tSync('ui.general.selected_provider', selectedProvider.name) + colors.reset);
-            if (selectedProvider.note) {
-                if (selectedProvider.id === 'custom') {
-                    console.log(colors.yellow + '  ' + i18n.tSync('ui.general.replace_url_model_note') + colors.reset);
-                } else {
-                    // Try to get note from i18n, fallback to provider.note if not found
-                    const noteKey = `provider.notes.${selectedProvider.id}`;
-                    const noteText = i18n.tSync(noteKey);
-                    // If i18n returns the key itself, it means translation not found, use original note
-                    const displayNote = noteText === noteKey ? selectedProvider.note : noteText;
-                    const notePrefix = i18n.tSync('provider.note_prefix');
-                    console.log(colors.yellow + `  ${notePrefix}: ${displayNote}` + colors.reset);
-                }
-            }
-            console.log('');
-            break;
+            lines.push(colors.yellow + i18n.tSync('ui.general.configuration_tips') + colors.reset);
+            const configTips = i18n.tSync('ui.general.config_tip_items');
+            configTips.forEach(tip => {
+                lines.push(colors.gray + '  • ' + tip + colors.reset);
+            });
+            lines.push(colors.gray + '  • ' + i18n.tSync('ui.general.type_exit_cancel') + colors.reset);
+            lines.push('');
+
+            lines.push(colors.yellow + i18n.tSync('ui.general.all_providers_compatible') + colors.reset);
+            lines.push('');
+            screen.render(lines);
+        }
+
+        await waitForKey(i18n.tSync('ui.general.press_continue_provider_selection'));
+
+        // Step 2: Show provider selection menu
+        screen.render([
+            '',
+            colors.bright + colors.orange + i18n.tSync('ui.general.add_new_api_title') + colors.reset,
+            ''
+        ]);
+
+        const selectedProviderResult = await selectProvider({
+            title: i18n.tSync('ui.general.compatible_providers_title'),
+            showNote: true
+        });
+
+        if (!selectedProviderResult) {
+            throw new Error(i18n.tSync('errors.general.cancelled_by_user'));
         }
 
+        const selectedProvider = selectedProviderResult;
+        let baseUrl = selectedProvider.baseUrl;
+        let suggestedModels = selectedProvider.models;
+
         // Input base URL - different handling for custom vs specific providers
         if (selectedProvider && selectedProvider.id === 'custom') {
             // Custom provider - show reference URL and require manual input
-            console.log(colors.gray + `  ` + i18n.tSync('ui.general.reference_base_url', baseUrl) + colors.reset);
-            console.log('');
+            screen.write(colors.gray + `  ` + i18n.tSync('ui.general.reference_base_url', baseUrl) + colors.reset + '\n');
+            screen.write('\n');
 
             while (true) {
                 const inputUrl = await simpleInput(colors.green + i18n.tSync('ui.general.api_base_url_prompt') + colors.reset);
@@ -295,13 +326,13 @@ async function promptForThirdPartyApi() {
                 }
 
                 if (!inputUrl || inputUrl.trim() === '') {
-                    console.log(colors.red + i18n.tSync('ui.general.base_url_required') + colors.reset);
+                    screen.write(colors.red + i18n.tSync('ui.general.base_url_required') + colors.reset + '\n');
                     continue;
                 }
 
                 const validation = validateBaseUrl(inputUrl);
                 if (!validation.valid) {
-                    console.log(colors.red + `❌ ${validation.error}` + colors.reset);
+                    screen.write(colors.red + `❌ ${validation.error}` + colors.reset + '\n');
                     continue;
                 }
                 baseUrl = validation.value;
@@ -309,14 +340,14 @@ async function promptForThirdPartyApi() {
             }
         } else if (selectedProvider && !baseUrl.includes('{')) {
             // Specific providers - show recommended URL with option to use default
-            console.log(colors.gray + `  ` + i18n.tSync('ui.general.recommended_base_url', baseUrl) + colors.reset);
+            screen.write(colors.gray + `  ` + i18n.tSync('ui.general.recommended_base_url', baseUrl) + colors.reset + '\n');
 
             // For all known providers, show the recommended URL in the prompt
             let prompt;
             if (selectedProvider.id === 'anthropic' || selectedProvider.id === 'deepseek' ||
                 selectedProvider.id === 'moonshot' || selectedProvider.id === 'kimi_for_coding' || selectedProvider.id === 'zhipu' || selectedProvider.id === 'zai') {
                 prompt = colors.green + i18n.tSync('ui.general.press_enter_default_url') + `${colors.yellow}${baseUrl}${colors.green}` + colors.reset;
-                console.log(colors.gray + '    ' + i18n.tSync('ui.general.edit_url_hint') + colors.reset);
+                screen.write(colors.gray + '    ' + i18n.tSync('ui.general.edit_url_hint') + colors.reset + '\n');
             } else {
                 prompt = colors.green + i18n.tSync('ui.general.press_enter_default_url') + colors.reset;
             }
@@ -339,7 +370,7 @@ async function promptForThirdPartyApi() {
 
                 const validation = validateBaseUrl(inputUrl);
                 if (!validation.valid) {
-                    console.log(colors.red + `❌ ${validation.error}` + colors.reset);
+                    screen.write(colors.red + `❌ ${validation.error}` + colors.reset + '\n');
                     continue;
                 }
                 baseUrl = validation.value;
@@ -349,14 +380,14 @@ async function promptForThirdPartyApi() {
 
         // Input auth token
         let authToken;
-        console.log('');
+        screen.write('\n');
 
         // Simplified API token input
         if (selectedProvider) {
-            console.log(colors.gray + `  ` + i18n.tSync('ui.general.expected_format', selectedProvider.authTokenFormat) + colors.reset);
+            screen.write(colors.gray + `  ` + i18n.tSync('ui.general.expected_format', selectedProvider.authTokenFormat) + colors.reset + '\n');
         }
-        console.log(colors.gray + '  ' + i18n.tSync('ui.general.type_exit_cancel_setup') + colors.reset);
-        console.log('');
+        screen.write(colors.gray + '  ' + i18n.tSync('ui.general.type_exit_cancel_setup') + colors.reset + '\n');
+        screen.write('\n');
 
         while (true) {
             const token = await simpleInput(colors.green + i18n.tSync('ui.general.auth_token_prompt') + colors.reset);
@@ -367,7 +398,7 @@ async function promptForThirdPartyApi() {
 
             const validation = validateAuthToken(token);
             if (!validation.valid) {
-                console.log(colors.red + `❌ ${validation.error}` + colors.reset);
+                screen.write(colors.red + `❌ ${validation.error}` + colors.reset + '\n');
                 continue;
             }
             authToken = validation.value;
@@ -376,7 +407,7 @@ async function promptForThirdPartyApi() {
 
         // Input model - different handling for custom vs specific providers
         let model;
-        console.log('');
+        screen.write('\n');
 
         if (selectedProvider && selectedProvider.id === 'custom') {
             // Custom provider - always require manual input, no suggested models
@@ -389,7 +420,7 @@ async function promptForThirdPartyApi() {
 
                 const validation = validateModel(inputModel);
                 if (!validation.valid) {
-                    console.log(colors.red + `❌ ${validation.error}` + colors.reset);
+                    screen.write(colors.red + `❌ ${validation.error}` + colors.reset + '\n');
                     continue;
                 }
                 model = validation.value;
@@ -397,11 +428,11 @@ async function promptForThirdPartyApi() {
             }
         } else if (suggestedModels.length > 0) {
             // Specific providers - show suggested models
-            console.log(colors.cyan + '  ' + i18n.tSync('ui.general.suggested_models') + colors.reset);
+            screen.write(colors.cyan + '  ' + i18n.tSync('ui.general.suggested_models') + colors.reset + '\n');
             suggestedModels.forEach((m, i) => {
-                console.log(colors.gray + `    ${i + 1}. ${m}` + colors.reset);
+                screen.write(colors.gray + `    ${i + 1}. ${m}` + colors.reset + '\n');
             });
-            console.log('');
+            screen.write('\n');
 
             while (true) {
                 const modelPrompt = i18n.tSync('ui.general.select_model_prompt').replace('{0}', suggestedModels.length);
@@ -418,7 +449,7 @@ async function promptForThirdPartyApi() {
                         model = suggestedModels[index];
                         break;
                     } else {
-                        console.log(colors.red + i18n.tSync('ui.general.invalid_model_selection').replace('{0}', suggestedModels.length) + colors.reset);
+                        screen.write(colors.red + i18n.tSync('ui.general.invalid_model_selection').replace('{0}', suggestedModels.length) + colors.reset + '\n');
                         continue;
                     }
                 }
@@ -426,7 +457,7 @@ async function promptForThirdPartyApi() {
                 // If not a number, validate as custom model name
                 const validation = validateModel(modelChoice);
                 if (!validation.valid) {
-                    console.log(colors.red + `❌ ${validation.error}` + colors.reset);
+                    screen.write(colors.red + `❌ ${validation.error}` + colors.reset + '\n');
                     continue;
                 }
                 model = validation.value;
@@ -443,7 +474,7 @@ async function promptForThirdPartyApi() {
 
                 const validation = validateModel(inputModel);
                 if (!validation.valid) {
-                    console.log(colors.red + `❌ ${validation.error}` + colors.reset);
+                    screen.write(colors.red + `❌ ${validation.error}` + colors.reset + '\n');
                     continue;
                 }
                 model = validation.value;
@@ -475,8 +506,8 @@ async function promptForThirdPartyApi() {
  * Confirm action prompt
  */
 async function confirmAction(message) {
-    console.log(colors.yellow + message + colors.reset);
-    console.log(colors.gray + i18n.tSync('ui.general.press_y_confirm') + colors.reset);
+    screen.write(colors.yellow + message + colors.reset + '\n');
+    screen.write(colors.gray + i18n.tSync('ui.general.press_y_confirm') + colors.reset + '\n');
 
     return new Promise((resolve) => {
         if (process.stdin.isTTY) {
@@ -527,36 +558,33 @@ async function confirmAction(message) {
  * Display success message
  */
 function showSuccess(title, details = []) {
-    console.log('');
-    console.log(colors.bright + colors.green + `✓ ${title}` + colors.reset);
-    details.forEach(detail => {
-        console.log(colors.gray + `  ${detail}` + colors.reset);
-    });
-    console.log('');
+    const lines = [''];
+    lines.push(colors.bright + colors.green + `✓ ${title}` + colors.reset);
+    details.forEach(detail => lines.push(colors.gray + `  ${detail}` + colors.reset));
+    lines.push('');
+    screen.render(lines);
 }
 
 /**
  * Display error message
  */
 function showError(title, details = []) {
-    console.log('');
-    console.log(colors.bright + colors.red + `❌ ${title}` + colors.reset);
-    details.forEach(detail => {
-        console.log(colors.gray + `  ${detail}` + colors.reset);
-    });
-    console.log('');
+    const lines = [''];
+    lines.push(colors.bright + colors.red + `❌ ${title}` + colors.reset);
+    details.forEach(detail => lines.push(colors.gray + `  ${detail}` + colors.reset));
+    lines.push('');
+    screen.render(lines);
 }
 
 /**
  * Display info message
  */
 function showInfo(title, details = []) {
-    console.log('');
-    console.log(colors.bright + colors.cyan + `ℹ️  ${title}` + colors.reset);
-    details.forEach(detail => {
-        console.log(colors.gray + `  ${detail}` + colors.reset);
-    });
-    console.log('');
+    const lines = [''];
+    lines.push(colors.bright + colors.cyan + `ℹ️  ${title}` + colors.reset);
+    details.forEach(detail => lines.push(colors.gray + `  ${detail}` + colors.reset));
+    lines.push('');
+    screen.render(lines);
 }
 
 
@@ -564,6 +592,7 @@ module.exports = {
     simpleInput,
     waitForKey,
     promptForThirdPartyApi,
+    selectProvider,
     confirmAction,
     showSuccess,
     showError,

package/lib/ui/screen.js

@@ -0,0 +1,125 @@
+/**
+ * Screen Singleton - ANSI terminal rendering layer
+ *
+ * All UI output goes through this module. Eliminates position drift
+ * by using absolute cursor positioning (cursorHome + clearScreen)
+ * and alternate screen buffer for isolation.
+ */
+
+const ANSI = {
+    enterAltScreen: '\x1b[?1049h',
+    exitAltScreen: '\x1b[?1049l',
+    cursorHome: '\x1b[H',
+    clearScreen: '\x1b[2J',
+    cursorHide: '\x1b[?25l',
+    cursorShow: '\x1b[?25h',
+    reset: '\x1b[0m',
+};
+
+class Screen {
+    constructor() {
+        this.inAltScreen = false;
+        this.isTTY = process.stdout.isTTY || false;
+        this.noAlt = process.env.SCREEN_NO_ALT === '1';
+        this.testMode = process.env.SCREEN_TEST === '1';
+        this.readlineActive = false;
+        this.currentTag = null;
+        this._log = [];
+    }
+
+    enter() {
+        if (!this.isTTY) return;
+        if (this.inAltScreen) return;
+        if (!this.noAlt) {
+            this._rawWrite(ANSI.enterAltScreen);
+        }
+        this._rawWrite(ANSI.cursorHide);
+        this.inAltScreen = true;
+    }
+
+    exit() {
+        if (!this.inAltScreen) return;
+        this._rawWrite(ANSI.cursorShow);
+        if (!this.noAlt) {
+            this._rawWrite(ANSI.exitAltScreen);
+        }
+        this.inAltScreen = false;
+    }
+
+    exitForHandoff() {
+        if (!this.inAltScreen) return;
+        this._rawWrite(ANSI.cursorShow);
+        this._rawWrite(ANSI.reset);
+        if (!this.noAlt) {
+            this._rawWrite(ANSI.exitAltScreen);
+        }
+        if (this.isTTY && process.stdin.isTTY) {
+            try { process.stdin.setRawMode(false); } catch (_) {}
+        }
+        this.inAltScreen = false;
+    }
+
+    render(lines) {
+        this.currentTag = 'render';
+        if (this.isTTY) {
+            this._rawWrite(ANSI.cursorHome + ANSI.clearScreen);
+        }
+        for (const line of lines) {
+            this._rawWrite(line + '\n');
+        }
+        this.currentTag = null;
+    }
+
+    write(text) {
+        this.currentTag = 'write';
+        this._rawWrite(text);
+        this.currentTag = null;
+    }
+
+    showCursor() {
+        if (this.isTTY) {
+            this._rawWrite(ANSI.cursorShow);
+        }
+    }
+
+    hideCursor() {
+        if (this.isTTY) {
+            this._rawWrite(ANSI.cursorHide);
+        }
+    }
+
+    isActive() {
+        return this.inAltScreen;
+    }
+
+    debug(message) {
+        if (this.inAltScreen) return; // Suppress during alt-screen
+        this._rawStderr(message + '\n');
+    }
+
+    setReadlineActive(active) {
+        this.readlineActive = active;
+        this.currentTag = active ? 'readline' : null;
+    }
+
+    getLog() {
+        return this._log;
+    }
+
+    _rawWrite(data) {
+        if (this.testMode) {
+            const tag = this.readlineActive ? 'readline' : (this.currentTag || 'untagged');
+            this._log.push({ channel: 'stdout', tag, data: data.substring(0, 80), time: Date.now() });
+        }
+        process.stdout.write(data);
+    }
+
+    _rawStderr(data) {
+        if (this.testMode) {
+            this._log.push({ channel: 'stderr', tag: 'debug', data: data.substring(0, 80), time: Date.now() });
+        }
+        process.stderr.write(data);
+    }
+}
+
+module.exports = new Screen();