rad-coder 1.0.1 → 1.0.3

package/bin/cli.js

@@ -13,66 +13,249 @@ function extractCreativeId(input) {
   return urlMatch ? urlMatch[1] : input;
 }
 
-// Get creative ID from command line argument
-const input = process.argv[2];
+/**
+ * Prompt user with a question and arrow-key selectable choices
+ * @param {string} question - The question to ask
+ * @param {string[]} choices - Array of choices
+ * @returns {Promise<number>} - The index of the selected choice (0-based)
+ */
+function promptUser(question, choices) {
+  return new Promise((resolve) => {
+    let selected = 0;
+
+    // Print question
+    console.log(`\n${question}\n`);
+
+    function draw() {
+      // Move cursor up to overwrite previous menu lines
+      if (selected !== -1) {
+        process.stdout.write(`\x1B[${choices.length}A`);
+      }
+      for (let i = 0; i < choices.length; i++) {
+        process.stdout.write('\x1B[2K'); // clear line
+        if (i === selected) {
+          process.stdout.write(`  \x1B[36m\x1B[1m❯ ${choices[i]}\x1B[0m\n`);
+        } else {
+          process.stdout.write(`    ${choices[i]}\n`);
+        }
+      }
+    }
+
+    // Initial draw (set selected to -1 so it doesn't move cursor up first time)
+    const initial = selected;
+    selected = -1;
+    // Print placeholder lines first
+    for (let i = 0; i < choices.length; i++) {
+      process.stdout.write('\n');
+    }
+    // Move back up and draw properly
+    process.stdout.write(`\x1B[${choices.length}A`);
+    selected = initial;
+    draw();
+
+    // Enable raw mode for keypress detection
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+
+    function onData(data) {
+      const key = data.toString();
+
+      // Ctrl+C
+      if (key === '\x03') {
+        cleanup();
+        process.exit(0);
+        return;
+      }
+
+      // Up arrow
+      if (key === '\x1B[A') {
+        selected = Math.max(0, selected - 1);
+        draw();
+        return;
+      }
+
+      // Down arrow
+      if (key === '\x1B[B') {
+        selected = Math.min(choices.length - 1, selected + 1);
+        draw();
+        return;
+      }
+
+      // Enter
+      if (key === '\r' || key === '\n') {
+        cleanup();
+        resolve(selected);
+        return;
+      }
+
+      // Number keys for quick select
+      const num = parseInt(key, 10);
+      if (num >= 1 && num <= choices.length) {
+        selected = num - 1;
+        draw();
+        cleanup();
+        resolve(selected);
+        return;
+      }
+    }
+
+    function cleanup() {
+      process.stdin.removeListener('data', onData);
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      process.stdin.pause();
+    }
+
+    process.stdin.on('data', onData);
+  });
+}
+
+// Get creative ID from command line argument (skip flags)
+const args = process.argv.slice(2);
+let input = null;
+let editorFlag = null;
+let noEditor = false;
+
+for (const arg of args) {
+  if (arg.startsWith('--editor=')) {
+    editorFlag = arg.split('=')[1];
+  } else if (arg === '--no-editor') {
+    noEditor = true;
+  } else if (!arg.startsWith('--')) {
+    input = arg;
+  }
+}
+
+// Pass editor preferences via environment variables
+if (editorFlag) {
+  process.env.RAD_CODER_EDITOR = editorFlag;
+}
+if (noEditor) {
+  process.env.RAD_CODER_NO_EDITOR = '1';
+}
+
 const creativeId = extractCreativeId(input);
 
 if (!creativeId) {
-  console.log('Usage: npx rad-coder <creativeId or previewUrl>');
+  console.log('Usage: npx rad-coder <creativeId or previewUrl> [options]');
+  console.log('');
+  console.log('Options:');
+  console.log('  --editor=<cmd>   Set code editor command (default: code)');
+  console.log('  --no-editor      Don\'t auto-open code editor');
   console.log('');
   console.log('Examples:');
   console.log('  npx rad-coder 697b80fcc6e904025f5147a0');
   console.log('  npx rad-coder https://studio.responsiveads.com/creatives/697b80fcc6e904025f5147a0/preview');
+  console.log('  npx rad-coder 697b80fcc6e904025f5147a0 --editor=cursor');
   process.exit(1);
 }
 
-// Determine the target directory
-const cwd = process.cwd();
-const currentDirName = path.basename(cwd);
-let userDir;
-
-if (currentDirName === creativeId) {
-  // Already in the correct folder
-  userDir = cwd;
-  console.log(`Using existing folder: ./${creativeId}`);
-} else {
-  // Create or use a folder with the creative ID
-  userDir = path.join(cwd, creativeId);
-  if (!fs.existsSync(userDir)) {
-    fs.mkdirSync(userDir);
-    console.log(`Created folder: ./${creativeId}`);
-  } else {
+async function main() {
+  // Determine the target directory
+  const cwd = process.cwd();
+  const currentDirName = path.basename(cwd);
+  let userDir;
+
+  if (currentDirName === creativeId) {
+    // Already in the correct folder
+    userDir = cwd;
     console.log(`Using existing folder: ./${creativeId}`);
+  } else {
+    // Create or use a folder with the creative ID
+    userDir = path.join(cwd, creativeId);
+    if (!fs.existsSync(userDir)) {
+      fs.mkdirSync(userDir);
+      console.log(`Created folder: ./${creativeId}`);
+    } else {
+      console.log(`Using existing folder: ./${creativeId}`);
+    }
   }
-}
 
-// Files to copy to user's directory on first run
-const filesToCopy = [
-  { template: 'custom.js', target: 'custom.js' },
-  { template: 'AGENTS.md', target: 'AGENTS.md' }
-];
-
-// Copy template files if they don't exist
-let filesCreated = false;
-filesToCopy.forEach(({ template, target }) => {
-  const targetPath = path.join(userDir, target);
-  if (!fs.existsSync(targetPath)) {
-    const templatePath = path.join(packageRoot, 'templates', template);
+  // Set environment variables for the server
+  process.env.RAD_CODER_USER_DIR = userDir;
+  process.env.RAD_CODER_PACKAGE_DIR = packageRoot;
+
+  // Import server module to fetch creative config
+  const { fetchCreativeConfig, startServer } = require('../server/index.js');
+
+  // Fetch creative config first to check for customjs
+  const config = await fetchCreativeConfig(creativeId);
+
+  const customJsPath = path.join(userDir, 'custom.js');
+  const customJsExists = fs.existsSync(customJsPath);
+  const hasCreativeCustomJs = config.customjs && config.customjs.trim().length > 0;
+
+  // Handle custom.js file creation/update
+  if (hasCreativeCustomJs) {
+    if (!customJsExists) {
+      // custom.js doesn't exist - ask user what to use
+      const choice = await promptUser(
+        'Found customJS in this creative. What would you like to use?',
+        [
+          'Use customJS from the creative (recommended)',
+          'Start with blank template'
+        ]
+      );
+
+      if (choice === 0) {
+        // Use customjs from creative
+        fs.writeFileSync(customJsPath, config.customjs, 'utf-8');
+        console.log('  Created custom.js (from creative)');
+      } else {
+        // Use template
+        const templatePath = path.join(packageRoot, 'templates', 'custom.js');
+        if (fs.existsSync(templatePath)) {
+          fs.copyFileSync(templatePath, customJsPath);
+          console.log('  Created custom.js (from template)');
+        }
+      }
+    } else {
+      // custom.js exists - ask user if they want to overwrite
+      const choice = await promptUser(
+        'Found customJS in this creative. Your custom.js already exists.',
+        [
+          'Keep existing custom.js',
+          'Overwrite with customJS from creative'
+        ]
+      );
+
+      if (choice === 1) {
+        // Overwrite with creative's customjs
+        fs.writeFileSync(customJsPath, config.customjs, 'utf-8');
+        console.log('  Overwrote custom.js with creative\'s customJS');
+      } else {
+        console.log('  Keeping existing custom.js');
+      }
+    }
+  } else {
+    // No customjs in creative - use template if custom.js doesn't exist
+    if (!customJsExists) {
+      const templatePath = path.join(packageRoot, 'templates', 'custom.js');
+      if (fs.existsSync(templatePath)) {
+        fs.copyFileSync(templatePath, customJsPath);
+        console.log('  Created custom.js (from template)');
+      }
+    }
+  }
+
+  // Copy AGENTS.md if it doesn't exist
+  const agentsMdPath = path.join(userDir, 'AGENTS.md');
+  if (!fs.existsSync(agentsMdPath)) {
+    const templatePath = path.join(packageRoot, 'templates', 'AGENTS.md');
     if (fs.existsSync(templatePath)) {
-      fs.copyFileSync(templatePath, targetPath);
-      console.log(`  Created ${target}`);
-      filesCreated = true;
+      fs.copyFileSync(templatePath, agentsMdPath);
+      console.log('  Created AGENTS.md');
     }
   }
-});
 
-if (filesCreated) {
-  console.log('');
+  // Start the server with pre-fetched config
+  await startServer(config);
 }
 
-// Set environment variables for the server
-process.env.RAD_CODER_USER_DIR = userDir;
-process.env.RAD_CODER_PACKAGE_DIR = packageRoot;
-
-// Run the server
-require('../server/index.js');
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rad-coder",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Development environment for testing ResponsiveAds creative custom JS with hot-reload",
   "bin": {
     "rad-coder": "./bin/cli.js"

package/server/index.js

@@ -5,6 +5,50 @@ const chokidar = require('chokidar');
 const path = require('path');
 const fs = require('fs');
 const http = require('http');
+const { spawn } = require('child_process');
+const TUI = require('./tui');
+
+// ============================================================
+// TUI Instance & Logging
+// ============================================================
+
+let tui = null;
+
+/**
+ * Log a message — routes to TUI scroll area when active, otherwise console.log
+ */
+function log(message) {
+  if (tui && !tui.destroyed) {
+    tui.log(message);
+  } else {
+    console.log(message);
+  }
+}
+
+/**
+ * Open the user's code editor
+ */
+function openEditor() {
+  const editorCmd = process.env.RAD_CODER_EDITOR
+    || process.env.VISUAL
+    || process.env.EDITOR
+    || 'code';
+
+  try {
+    const child = spawn(editorCmd, [userDir], {
+      detached: true,
+      stdio: 'ignore',
+      shell: process.platform === 'win32'
+    });
+    child.unref();
+    child.on('error', (err) => {
+      log(` ✗ Could not open editor "${editorCmd}": ${err.message}`);
+    });
+    log(` Editor (${editorCmd}) opened`);
+  } catch (err) {
+    log(` ✗ Could not open editor "${editorCmd}": ${err.message}`);
+  }
+}
 
 // ============================================================
 // Directory Configuration
@@ -19,26 +63,33 @@ const packageDir = process.env.RAD_CODER_PACKAGE_DIR || path.join(__dirname, '..
 // CLI Argument Parsing
 // ============================================================
 
-const input = process.argv[2];
+// Check if we're being required as a module (from cli.js) or run directly
+const isModule = require.main !== module;
 
-if (!input) {
-  console.error('\n Usage: npx rad-coder <creativeId or previewUrl>\n');
-  console.error(' Examples:');
-  console.error('   npx rad-coder 697b80fcc6e904025f5147a0');
-  console.error('   npx rad-coder https://studio.responsiveads.com/creatives/697b80fcc6e904025f5147a0/preview\n');
-  process.exit(1);
-}
+let creativeId = null;
 
-/**
- * Extract creative ID from URL or use directly
- */
-function extractCreativeId(input) {
-  // If it's a URL, extract the ID
-  const urlMatch = input.match(/creatives\/([a-f0-9]+)/i);
-  return urlMatch ? urlMatch[1] : input;
-}
+if (!isModule) {
+  const input = process.argv[2];
 
-const creativeId = extractCreativeId(input);
+  if (!input) {
+    console.error('\n Usage: npx rad-coder <creativeId or previewUrl>\n');
+    console.error(' Examples:');
+    console.error('   npx rad-coder 697b80fcc6e904025f5147a0');
+    console.error('   npx rad-coder https://studio.responsiveads.com/creatives/697b80fcc6e904025f5147a0/preview\n');
+    process.exit(1);
+  }
+
+  /**
+   * Extract creative ID from URL or use directly
+   */
+  function extractCreativeIdLocal(input) {
+    // If it's a URL, extract the ID
+    const urlMatch = input.match(/creatives\/([a-f0-9]+)/i);
+    return urlMatch ? urlMatch[1] : input;
+  }
+
+  creativeId = extractCreativeIdLocal(input);
+}
 
 // ============================================================
 // Fetch Creative Config from Studio Preview Page
@@ -46,14 +97,68 @@ const creativeId = extractCreativeId(input);
 
 let creativeConfig = null;
 
+/**
+ * Extract a JSON object from HTML using balanced bracket parsing
+ * @param {string} html - The HTML content
+ * @param {string} startMarker - The marker to find (e.g., 'window.creative = ')
+ * @returns {object|null} - Parsed JSON object or null
+ */
+function extractJsonObject(html, startMarker) {
+  const startIdx = html.indexOf(startMarker);
+  if (startIdx === -1) return null;
+  
+  const jsonStart = startIdx + startMarker.length;
+  let braceCount = 0;
+  let inString = false;
+  let escapeNext = false;
+  let endIdx = jsonStart;
+  
+  for (let i = jsonStart; i < html.length; i++) {
+    const char = html[i];
+    
+    if (escapeNext) {
+      escapeNext = false;
+      continue;
+    }
+    
+    if (char === '\\') {
+      escapeNext = true;
+      continue;
+    }
+    
+    if (char === '"' && !inString) {
+      inString = true;
+    } else if (char === '"' && inString) {
+      inString = false;
+    }
+    
+    if (!inString) {
+      if (char === '{') braceCount++;
+      if (char === '}') braceCount--;
+      
+      if (braceCount === 0 && char === '}') {
+        endIdx = i + 1;
+        break;
+      }
+    }
+  }
+  
+  try {
+    const jsonStr = html.substring(jsonStart, endIdx);
+    return JSON.parse(jsonStr);
+  } catch (err) {
+    return null;
+  }
+}
+
 /**
  * Fetch and parse creative configuration from studio preview page
  */
 async function fetchCreativeConfig(creativeId) {
   const previewUrl = `https://studio.responsiveads.com/creatives/${creativeId}/preview`;
   
-  console.log(` Fetching creative config from studio...`);
-  console.log(` URL: ${previewUrl}\n`);
+  log(` Fetching creative config from studio...`);
+  log(` URL: ${previewUrl}\n`);
   
   try {
     const response = await fetch(previewUrl);
@@ -67,6 +172,13 @@ async function fetchCreativeConfig(creativeId) {
     const creativeIdMatch = html.match(/window\.creativeId\s*=\s*['"]([^'"]+)['"]/);
     const extractedCreativeId = creativeIdMatch ? creativeIdMatch[1] : creativeId;
     
+    // Extract window.creative object to get customjs
+    let customjs = null;
+    const creativeObj = extractJsonObject(html, 'window.creative = ');
+    if (creativeObj && creativeObj.config && creativeObj.config.customjs) {
+      customjs = creativeObj.config.customjs;
+    }
+    
     // Extract flowlines - try multiple patterns
     let flowlines;
     
@@ -187,11 +299,13 @@ async function fetchCreativeConfig(creativeId) {
         name: f.name,
         sizes: f.flowline?.sizes || [],
         isFluid: f.fullyFluid
-      }))
+      })),
+      // Custom JS from the creative (if available)
+      customjs: customjs
     };
     
   } catch (error) {
-    console.error(`\n Failed to fetch creative config: ${error.message}\n`);
+    log(`\n ✗ Failed to fetch creative config: ${error.message}\n`);
     process.exit(1);
   }
 }
@@ -211,11 +325,11 @@ const clients = new Set();
 
 wss.on('connection', (ws) => {
   clients.add(ws);
-  console.log('Browser connected for hot-reload');
+  log(' Browser connected for hot-reload');
   
   ws.on('close', () => {
     clients.delete(ws);
-    console.log('Browser disconnected');
+    log(' Browser disconnected');
   });
 });
 
@@ -271,27 +385,31 @@ const watcher = chokidar.watch(customJsWatchPath, {
   ignoreInitial: true
 });
 
-watcher.on('change', (filePath) => {
-  console.log(`\n File changed: ${path.basename(filePath)}`);
-  console.log(' Reloading browsers...\n');
+watcher.on('change', (changedPath) => {
+  log(` File changed: ${path.basename(changedPath)}`);
+  log(' Reloading browsers...');
   broadcastReload();
 });
 
 watcher.on('error', (error) => {
-  console.error('Watcher error:', error);
+  log(` Watcher error: ${error.message}`);
 });
 
 // ============================================================
 // Start Server
 // ============================================================
 
-async function start() {
+async function start(prefetchedConfig = null) {
   console.log('\n========================================');
   console.log(' RAD Coder - ResponsiveAds Creative Tester');
   console.log('========================================\n');
   
-  // Fetch creative config from studio
-  creativeConfig = await fetchCreativeConfig(creativeId);
+  // Use pre-fetched config if provided, otherwise fetch it
+  if (prefetchedConfig) {
+    creativeConfig = prefetchedConfig;
+  } else {
+    creativeConfig = await fetchCreativeConfig(creativeId);
+  }
   
   console.log(' Creative Config:');
   console.log(` - Creative ID: ${creativeConfig.creativeId}`);
@@ -299,6 +417,7 @@ async function start() {
   console.log(` - Flowline ID: ${creativeConfig.flowlineId}`);
   console.log(` - Sizes: ${creativeConfig.sizes.join(', ')}`);
   console.log(` - Is Fluid: ${creativeConfig.isFluid}`);
+  console.log(` - Has CustomJS: ${creativeConfig.customjs ? 'Yes' : 'No'}`);
   
   if (creativeConfig.allFlowlines.length > 1) {
     console.log(`\n Available Flowlines (${creativeConfig.allFlowlines.length}):`);
@@ -315,7 +434,6 @@ async function start() {
     console.log(` Test page: http://${host}:${port}/test.html`);
     console.log(`\n Working directory: ${userDir}`);
     console.log(' Edit custom.js and save to hot-reload\n');
-    console.log(' Press Ctrl+C to stop\n');
     
     // Small delay to ensure server is fully ready before opening browser
     await new Promise(resolve => setTimeout(resolve, 500));
@@ -324,18 +442,175 @@ async function start() {
     try {
       const open = (await import('open')).default;
       await open(`http://${host}:${port}/test.html`);
-      console.log(' Browser opened automatically\n');
+      console.log(' Browser opened automatically');
     } catch (err) {
-      console.log(' Could not auto-open browser:', err.message);
-      console.log(` Please open http://${host}:${port}/test.html manually\n`);
+      console.log(` Could not auto-open browser: ${err.message}`);
+      console.log(` Please open http://${host}:${port}/test.html manually`);
+    }
+
+    // Auto-open editor (unless --no-editor)
+    if (!process.env.RAD_CODER_NO_EDITOR) {
+      openEditor();
+    }
+
+    // Start interactive TUI (only if stdin is a TTY)
+    if (process.stdin.isTTY) {
+      await new Promise(resolve => setTimeout(resolve, 300));
+      startInteractiveMenu();
+    } else {
+      console.log(' Press Ctrl+C to stop\n');
     }
   });
 }
 
-start();
+// ============================================================
+// Interactive Menu
+// ============================================================
+
+function getMainMenuItems() {
+  const items = [
+    { label: 'Open Browser', id: 'open-browser' },
+    { label: 'Open Editor', id: 'open-editor' },
+  ];
+
+  if (creativeConfig && creativeConfig.allFlowlines.length > 1) {
+    items.push({ label: 'Switch Flowline', id: 'switch-flowline', description: `(${creativeConfig.flowlineName})` });
+  }
+
+  items.push(
+    { label: 'Server Status', id: 'status' },
+    { label: 'Clear Logs', id: 'clear' },
+    { label: 'Restart Server', id: 'restart' },
+    { label: 'Stop Server', id: 'stop' },
+  );
+
+  return items;
+}
+
+function getFlowlineMenuItems() {
+  const items = [{ label: '← Back', id: 'back' }];
+  creativeConfig.allFlowlines.forEach((fl, i) => {
+    const marker = fl.id === creativeConfig.flowlineId ? ' ✓' : '';
+    items.push({ label: `${fl.name}${marker}`, id: `flowline-${i}`, flowlineIndex: i });
+  });
+  return items;
+}
+
+function startInteractiveMenu() {
+  tui = new TUI();
+
+  let inSubMenu = false;
+
+  function handleSelect(item) {
+    // Sub-menu: flowline selection
+    if (inSubMenu) {
+      if (item.id === 'back') {
+        inSubMenu = false;
+        tui.updateMenu(getMainMenuItems());
+        return;
+      }
+      // Switch flowline
+      const fl = creativeConfig.allFlowlines[item.flowlineIndex];
+      if (fl) {
+        creativeConfig.flowlineId = fl.id;
+        creativeConfig.flowlineName = fl.name;
+        creativeConfig.sizes = fl.sizes || [];
+        creativeConfig.isFluid = fl.isFluid || false;
+        log(` Switched to flowline: ${fl.name}`);
+        broadcastReload();
+      }
+      inSubMenu = false;
+      tui.updateMenu(getMainMenuItems());
+      return;
+    }
+
+    // Main menu actions
+    switch (item.id) {
+      case 'open-browser': {
+        const { port, host } = creativeConfig.server;
+        import('open').then(mod => {
+          mod.default(`http://${host}:${port}/test.html`);
+          log(' Browser opened');
+        }).catch(err => {
+          log(` Could not open browser: ${err.message}`);
+        });
+        break;
+      }
+
+      case 'open-editor':
+        openEditor();
+        break;
+
+      case 'switch-flowline':
+        inSubMenu = true;
+        tui.updateMenu(getFlowlineMenuItems());
+        break;
+
+      case 'status': {
+        const { port, host } = creativeConfig.server;
+        log('');
+        log(' ── Server Status ──────────────────');
+        log(` Creative ID : ${creativeConfig.creativeId}`);
+        log(` Flowline    : ${creativeConfig.flowlineName}`);
+        log(` Flowline ID : ${creativeConfig.flowlineId}`);
+        log(` Sizes       : ${creativeConfig.sizes.join(', ') || 'N/A'}`);
+        log(` Is Fluid    : ${creativeConfig.isFluid}`);
+        log(` Server      : http://${host}:${port}`);
+        log(` Directory   : ${userDir}`);
+        log(` Browsers    : ${clients.size} connected`);
+        log(' ───────────────────────────────────');
+        log('');
+        break;
+      }
+
+      case 'clear':
+        tui.clearLogs();
+        break;
+
+      case 'restart': {
+        log(' Restarting server...');
+        const { port, host } = creativeConfig.server;
+        server.close(() => {
+          server.listen(port, host, () => {
+            log(` Server restarted on http://${host}:${port}`);
+            broadcastReload();
+          });
+        });
+        break;
+      }
+
+      case 'stop':
+        gracefulShutdown();
+        break;
+    }
+  }
+
+  tui.init({
+    menuItems: getMainMenuItems(),
+    onSelect: handleSelect,
+  });
+}
+
+// ============================================================
+// Module Exports & Startup
+// ============================================================
+
+// Export functions for use by cli.js
+module.exports = {
+  fetchCreativeConfig,
+  startServer: start
+};
+
+// Only auto-start if run directly (not required as module)
+if (!isModule) {
+  start();
+}
 
 // Graceful shutdown
-process.on('SIGINT', () => {
+function gracefulShutdown() {
+  if (tui) {
+    tui.destroy();
+  }
   console.log('\n Shutting down...');
   watcher.close();
   wss.close();
@@ -343,4 +618,6 @@ process.on('SIGINT', () => {
     console.log(' Server stopped\n');
     process.exit(0);
   });
-});
+}
+
+process.on('SIGINT', gracefulShutdown);

package/server/tui.js

@@ -0,0 +1,282 @@
+/**
+ * Terminal UI Module
+ * 
+ * Provides an interactive arrow-key menu pinned at the bottom of the terminal
+ * with a scrolling log area above it. Uses raw ANSI escape codes — zero dependencies.
+ */
+
+const readline = require('readline');
+
+// ANSI escape helpers
+const ESC = '\x1B';
+const CSI = `${ESC}[`;
+
+const ansi = {
+  clearScreen: `${CSI}2J`,
+  clearLine: `${CSI}2K`,
+  cursorTo: (row, col) => `${CSI}${row};${col}H`,
+  cursorSave: `${ESC}7`,
+  cursorRestore: `${ESC}8`,
+  scrollRegion: (top, bottom) => `${CSI}${top};${bottom}r`,
+  resetScrollRegion: `${CSI}r`,
+  showCursor: `${CSI}?25h`,
+  hideCursor: `${CSI}?25l`,
+  bold: `${CSI}1m`,
+  dim: `${CSI}2m`,
+  cyan: `${CSI}36m`,
+  green: `${CSI}32m`,
+  yellow: `${CSI}33m`,
+  inverse: `${CSI}7m`,
+  reset: `${CSI}0m`,
+};
+
+class TUI {
+  constructor() {
+    this.menuItems = [];
+    this.selectedIndex = 0;
+    this.onSelect = null;
+    this.destroyed = false;
+    this.menuHeight = 0; // computed from items + header + border lines
+    this._boundKeyHandler = this._handleKeypress.bind(this);
+    this._boundResize = this._handleResize.bind(this);
+  }
+
+  /**
+   * Initialize the TUI
+   * @param {Object} options
+   * @param {Array<{label: string, description?: string}>} options.menuItems
+   * @param {Function} options.onSelect - callback(item, index)
+   */
+  init(options) {
+    this.menuItems = options.menuItems || [];
+    this.onSelect = options.onSelect || (() => {});
+    this.selectedIndex = 0;
+    this.menuHeight = this.menuItems.length + 3; // items + header + top/bottom borders
+
+    // Set raw mode for keypress detection
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.on('data', this._boundKeyHandler);
+    }
+
+    // Handle terminal resize
+    process.stdout.on('resize', this._boundResize);
+
+    // Initial draw
+    this._setupScreen();
+    this._drawMenu();
+  }
+
+  /**
+   * Set up ANSI scrolling region (log area = top, menu = bottom)
+   */
+  _setupScreen() {
+    const rows = process.stdout.rows || 24;
+    const logBottom = rows - this.menuHeight;
+
+    // Set scrolling region to the top portion only
+    process.stdout.write(ansi.scrollRegion(1, logBottom));
+
+    // Position cursor in the log area
+    process.stdout.write(ansi.cursorTo(logBottom, 1));
+  }
+
+  /**
+   * Handle terminal resize
+   */
+  _handleResize() {
+    if (this.destroyed) return;
+    this._setupScreen();
+    this._drawMenu();
+  }
+
+  /**
+   * Handle raw keypress data
+   */
+  _handleKeypress(data) {
+    if (this.destroyed) return;
+
+    const key = data.toString();
+
+    // Ctrl+C
+    if (key === '\x03') {
+      this.destroy();
+      process.emit('SIGINT');
+      return;
+    }
+
+    // Up arrow
+    if (key === `${CSI}A`) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      this._drawMenu();
+      return;
+    }
+
+    // Down arrow
+    if (key === `${CSI}B`) {
+      this.selectedIndex = Math.min(this.menuItems.length - 1, this.selectedIndex + 1);
+      this._drawMenu();
+      return;
+    }
+
+    // Enter
+    if (key === '\r' || key === '\n') {
+      const item = this.menuItems[this.selectedIndex];
+      if (item && this.onSelect) {
+        this.onSelect(item, this.selectedIndex);
+      }
+      return;
+    }
+
+    // Number keys 1-9 for quick select
+    const num = parseInt(key, 10);
+    if (num >= 1 && num <= this.menuItems.length) {
+      this.selectedIndex = num - 1;
+      this._drawMenu();
+      const item = this.menuItems[this.selectedIndex];
+      if (item && this.onSelect) {
+        this.onSelect(item, this.selectedIndex);
+      }
+      return;
+    }
+  }
+
+  /**
+   * Draw the menu at the bottom of the terminal
+   */
+  _drawMenu() {
+    if (this.destroyed) return;
+
+    const rows = process.stdout.rows || 24;
+    const cols = process.stdout.cols || 80;
+    const menuStartRow = rows - this.menuHeight + 1;
+
+    // Save cursor position (in log area)
+    let output = ansi.cursorSave;
+    output += ansi.hideCursor;
+
+    // Draw top border
+    output += ansi.cursorTo(menuStartRow, 1);
+    output += ansi.clearLine;
+    output += `${ansi.dim}${'─'.repeat(Math.min(cols, 60))}${ansi.reset}`;
+
+    // Draw header
+    output += ansi.cursorTo(menuStartRow + 1, 1);
+    output += ansi.clearLine;
+    output += `${ansi.bold} ↑↓ Navigate  Enter Select  1-${this.menuItems.length} Quick Select${ansi.reset}`;
+
+    // Draw menu items
+    for (let i = 0; i < this.menuItems.length; i++) {
+      const row = menuStartRow + 2 + i;
+      const item = this.menuItems[i];
+      const isSelected = i === this.selectedIndex;
+
+      output += ansi.cursorTo(row, 1);
+      output += ansi.clearLine;
+
+      if (isSelected) {
+        output += `${ansi.cyan}${ansi.bold} ❯ ${item.label}${ansi.reset}`;
+        if (item.description) {
+          output += `${ansi.dim}  ${item.description}${ansi.reset}`;
+        }
+      } else {
+        output += `   ${item.label}`;
+        if (item.description) {
+          output += `${ansi.dim}  ${item.description}${ansi.reset}`;
+        }
+      }
+    }
+
+    // Restore cursor position (back to log area)
+    output += ansi.cursorRestore;
+    output += ansi.showCursor;
+
+    process.stdout.write(output);
+  }
+
+  /**
+   * Update menu items (e.g., for sub-menus)
+   */
+  updateMenu(items) {
+    const oldHeight = this.menuHeight;
+    this.menuItems = items;
+    this.selectedIndex = 0;
+    this.menuHeight = items.length + 3;
+
+    if (this.menuHeight !== oldHeight) {
+      // Clear old menu area
+      const rows = process.stdout.rows || 24;
+      const oldMenuStart = rows - oldHeight + 1;
+      let clear = '';
+      for (let i = oldMenuStart; i <= rows; i++) {
+        clear += ansi.cursorTo(i, 1) + ansi.clearLine;
+      }
+      process.stdout.write(clear);
+
+      // Reconfigure scroll region
+      this._setupScreen();
+    }
+
+    this._drawMenu();
+  }
+
+  /**
+   * Add a log message to the scrolling log area
+   */
+  log(message) {
+    if (this.destroyed) {
+      console.log(message);
+      return;
+    }
+
+    const rows = process.stdout.rows || 24;
+    const logBottom = rows - this.menuHeight;
+
+    // Save cursor, move to bottom of log area, print message (scrolls within region)
+    let output = ansi.cursorSave;
+    output += ansi.cursorTo(logBottom, 1);
+    output += '\n' + message;
+    output += ansi.cursorRestore;
+
+    process.stdout.write(output);
+  }
+
+  /**
+   * Clear the log area
+   */
+  clearLogs() {
+    const rows = process.stdout.rows || 24;
+    const logBottom = rows - this.menuHeight;
+
+    let output = '';
+    for (let i = 1; i <= logBottom; i++) {
+      output += ansi.cursorTo(i, 1) + ansi.clearLine;
+    }
+    output += ansi.cursorTo(1, 1);
+    process.stdout.write(output);
+  }
+
+  /**
+   * Destroy the TUI and restore terminal state
+   */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+
+    // Remove listeners
+    process.stdin.removeListener('data', this._boundKeyHandler);
+    process.stdout.removeListener('resize', this._boundResize);
+
+    // Restore terminal
+    process.stdout.write(ansi.resetScrollRegion);
+    process.stdout.write(ansi.showCursor);
+
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(false);
+    }
+    process.stdin.pause();
+  }
+}
+
+module.exports = TUI;