qr-terminal 1.0.0

package/src/prompts.js

@@ -0,0 +1,449 @@
+/**
+ * Main interactive flow.
+ * Orchestrates inquirer prompts → live preview → QR generation → export.
+ */
+
+import { select, input, confirm, checkbox, password } from '@inquirer/prompts';
+import chalk from 'chalk';
+import ora from 'ora';
+import clipboard from 'clipboardy';
+
+import { createMatrix, renderHalfBlock, renderASCII } from './engine.js';
+import { liveInput } from './live-preview.js';
+import { formatWifi, formatVCard, ERROR_LEVELS, GRADIENT_OPTIONS } from './formatters.js';
+import { exportPNG, exportSVG, exportTXT } from './export.js';
+import { shortenUrl, isValidUrl, estimateSavings } from './shortlink.js';
+import { printQR, revealQR, printDivider, detectDarkMode, log } from './ui.js';
+import { animateParticleFlyIn } from './particle.js';
+import { matrixRainQR } from './matrix-rain.js';
+import { renderBraille } from './braille.js';
+import { startHandshakeServer } from './handshake.js';
+import { createDestructQR, showExplosion } from './destruct.js';
+
+export async function runMainFlow() {
+  // ──────────────────────────────────────────────
+  // STEP 1 — Input type selection
+  // ──────────────────────────────────────────────
+  const inputType = await select({
+    message: chalk.bold('What do you want to encode?'),
+    choices: [
+      {
+        name:        '  🔗  URL / Link',
+        value:       'url',
+        description: 'Website, app deep-link, or any HTTP address',
+      },
+      {
+        name:        '  📶  WiFi Credentials',
+        value:       'wifi',
+        description: 'Tap-to-join network QR (iOS 11+ / Android 10+)',
+      },
+      {
+        name:        '  👤  vCard Contact',
+        value:       'vcard',
+        description: 'Share your contact card — imports directly to address book',
+      },
+      {
+        name:        '  🔒  Secret Text',
+        value:       'secret',
+        description: 'Tokens, keys, passwords, or any sensitive payload',
+      },
+    ],
+  });
+
+  // ──────────────────────────────────────────────
+  // STEP 2 — Error correction level
+  // ──────────────────────────────────────────────
+  const errorLevel = await select({
+    message: chalk.bold('Error correction level?'),
+    choices: Object.entries(ERROR_LEVELS).map(([k, v]) => ({
+      name:        v.label,
+      value:       k,
+      description: v.desc,
+    })),
+    default: 'M',
+  });
+
+  // ──────────────────────────────────────────────
+  // STEP 3 — Visual gradient theme
+  // ──────────────────────────────────────────────
+  const gradient = await select({
+    message: chalk.bold('Color theme for the QR code?'),
+    choices: GRADIENT_OPTIONS,
+  });
+
+  // ── Render engine selection ─────────────────────────────────────────────
+  const renderMode = await select({
+    message: chalk.bold('Render engine?'),
+    choices: [
+      { name: '  ▀▄  Half-Block    — Standard high-density (default)',        value: 'halfblock' },
+      { name: '  ⣿   Braille       — 4× resolution "Retina" mode',           value: 'braille'  },
+      { name: '  ✦   Particle      — Fly-in "Transformer" animation',         value: 'particle' },
+      { name: '  ░   Matrix Rain   — Animated cascade → gradient settle',     value: 'matrix'   },
+      { name: '  📡  Device Link   — Scan to connect phone → terminal',       value: 'handshake'},
+    ],
+  });
+
+  // ──────────────────────────────────────────────
+  // STEP 4 — Collect type-specific data
+  // ──────────────────────────────────────────────
+  let qrData    = '';
+  let dataLabel = '';
+
+  switch (inputType) {
+
+    // ── URL ─────────────────────────────────────
+    case 'url': {
+      console.log(chalk.dim('\n  Live preview active — QR updates as you type\n'));
+
+      let rawUrl = await liveInput({ label: 'URL', errorLevel, gradient });
+
+      // Auto-prepend protocol if missing
+      if (rawUrl && !rawUrl.match(/^https?:\/\//i)) {
+        rawUrl = 'https://' + rawUrl;
+      }
+
+      if (!rawUrl) { log.error('No URL provided.'); return; }
+
+      qrData    = rawUrl;
+      dataLabel = 'URL';
+
+      // Optional URL shortening
+      if (isValidUrl(qrData) && qrData.length > 40) {
+        const shouldShorten = await confirm({
+          message: `Shorten via TinyURL? ${chalk.dim('(reduces QR complexity)')}`,
+          default: false,
+        });
+
+        if (shouldShorten) {
+          const spinner = ora({
+            text:    'Connecting to TinyURL…',
+            spinner: 'dots',
+          }).start();
+
+          try {
+            const short = await shortenUrl(qrData);
+            const savings = estimateSavings(qrData.length, short.length);
+            spinner.succeed(chalk.green('Shortened: ') + chalk.white(short) + chalk.dim(`  (${savings})`));
+            qrData = short;
+          } catch (e) {
+            spinner.fail(chalk.yellow('Could not reach TinyURL. Using original URL.'));
+          }
+        }
+      }
+      break;
+    }
+
+    // ── WiFi ────────────────────────────────────
+    case 'wifi': {
+      console.log();
+      const ssid = await input({
+        message: chalk.cyan('Network name (SSID):'),
+        validate: (v) => v.trim().length > 0 || 'SSID cannot be empty',
+      });
+
+      const security = await select({
+        message: chalk.cyan('Security protocol:'),
+        choices: [
+          { name: 'WPA / WPA2 / WPA3  (recommended)', value: 'WPA'    },
+          { name: 'WEP  (legacy)',                     value: 'WEP'    },
+          { name: 'Open / No password',                value: 'nopass' },
+        ],
+      });
+
+      let wifiPassword = '';
+      if (security !== 'nopass') {
+        wifiPassword = await password({
+          message: chalk.cyan('Password:'),
+          mask:    '●',
+          validate: (v) => v.length > 0 || 'Password cannot be empty',
+        });
+      }
+
+      const hidden = await confirm({
+        message: chalk.cyan('Is this a hidden network?'),
+        default: false,
+      });
+
+      qrData    = formatWifi({ ssid, password: wifiPassword, security, hidden });
+      dataLabel = `WiFi: ${ssid}`;
+      break;
+    }
+
+    // ── vCard ───────────────────────────────────
+    case 'vcard': {
+      console.log();
+      const firstName = await input({ message: chalk.cyan('First name:') });
+      const lastName  = await input({ message: chalk.cyan('Last name:'),  default: '' });
+      const phone     = await input({ message: chalk.cyan('Phone:'),      default: '' });
+      const email     = await input({ message: chalk.cyan('Email:'),      default: '' });
+      const org       = await input({ message: chalk.cyan('Organization:'), default: '' });
+      const url       = await input({ message: chalk.cyan('Website:'),    default: '' });
+
+      if (!firstName && !lastName) { log.error('Name is required.'); return; }
+
+      qrData    = formatVCard({ firstName, lastName, phone, email, org, url });
+      dataLabel = `vCard: ${[firstName, lastName].filter(Boolean).join(' ')}`;
+      break;
+    }
+
+    // ── Secret ──────────────────────────────────
+    case 'secret': {
+      console.log();
+      const secret = await password({
+        message: chalk.cyan('Secret payload:'),
+        mask:    '●',
+        validate: (v) => v.length > 0 || 'Cannot encode an empty secret',
+      });
+
+      qrData    = secret;
+      dataLabel = 'Secret Text';
+      log.warn('Secret encoded — share this QR only with intended recipients.');
+      break;
+    }
+  }
+
+  if (!qrData) return;
+
+  // ──────────────────────────────────────────────
+  // STEP 5 — Generate & render the QR code
+  // ──────────────────────────────────────────────
+  printDivider('Generating');
+
+  let modules;
+  const spinner = ora({ text: 'Building QR matrix…', spinner: 'arc' }).start();
+
+  try {
+    modules = createMatrix(qrData, { errorLevel });
+    spinner.succeed(chalk.green('QR matrix ready.'));
+  } catch (e) {
+    spinner.fail(chalk.red('QR generation failed: ' + e.message));
+    log.tip('Try a shorter input or increase error correction to H.');
+    return;
+  }
+
+  // ──────────────────────────────────────────────
+  // STEP 5b — Render with chosen engine
+  // ──────────────────────────────────────────────
+
+  // Special case: handshake mode
+  if (renderMode === 'handshake') {
+    const spinner2 = ora({ text: 'Starting device link server…', spinner: 'arc' }).start();
+    let server;
+    try {
+      server = await startHandshakeServer();
+      spinner2.succeed(`Server ready → ${chalk.underline(server.url)}`);
+    } catch (e) {
+      spinner2.fail('Could not start server: ' + e.message);
+      return;
+    }
+
+    // Generate QR for the server URL
+    const linkModules = createMatrix(server.url, { errorLevel: 'M' });
+    const linkLines   = renderHalfBlock(linkModules, { gradient: 'neon' });
+
+    console.log();
+    console.log(chalk.bold.cyanBright('  ┌─ Scan to Connect ──────────────────────────────────┐'));
+    await revealQR(linkLines, { speed: 10 });
+    console.log(chalk.dim('  Open on your phone: ') + chalk.white(server.url));
+    console.log();
+
+    const waitSpinner = ora({
+      text: chalk.dim('Waiting for device to connect…'),
+      spinner: 'dots',
+      color: 'cyan',
+    }).start();
+
+    await server.waitForDevice;
+    waitSpinner.succeed(chalk.bold.green('DEVICE CONNECTED ✓'));
+    console.log(chalk.cyan('\n  Phone is now linked. Messages will appear below.\n'));
+    console.log(chalk.dim('  Press Ctrl+C to close the connection.\n'));
+
+    // Stream phone messages to terminal
+    server.onMessage((text) => {
+      console.log(chalk.bold.cyanBright('\n  📱 From phone: ') + chalk.white(text) + '\n');
+    });
+
+    // Keep alive until Ctrl+C
+    await new Promise((_, reject) => {
+      process.on('SIGINT', () => {
+        server.close();
+        console.log(chalk.dim('\n  Connection closed.'));
+        reject(new Error('Cancelled'));
+      });
+    });
+    return;
+  }
+
+  const qrLines = renderMode === 'braille'
+    ? renderBraille(modules, { gradient })
+    : renderHalfBlock(modules, { gradient });
+
+  console.log();
+  if (dataLabel) {
+    const qrWidth = qrLines[0].replace(/\x1b\[[0-9;]*m/g, '').length;
+    console.log(
+      chalk.bold.cyanBright('  ┌─ ') +
+      chalk.bold.white(dataLabel) +
+      chalk.bold.cyanBright(' ' + '─'.repeat(Math.max(0, qrWidth - dataLabel.length - 3)) + '┐')
+    );
+  }
+
+  if (renderMode === 'particle') {
+    await animateParticleFlyIn(modules, { gradient, fps: 30, duration: 1100 });
+  } else if (renderMode === 'matrix') {
+    await matrixRainQR(modules, { gradient, duration: 2200, fps: 24 });
+  } else {
+    await revealQR(qrLines, { speed: 12 });
+  }
+
+  const version = Math.round((modules.size - 17) / 4);
+  const stats = [
+    chalk.bold.cyanBright(`v${version} QR`),
+    chalk.dim(`${modules.size}×${modules.size} modules`),
+    chalk.dim(`${qrLines.length * 2} → ${qrLines.length} rows`),
+    chalk.dim(`EC: ${errorLevel}`),
+    chalk.dim(renderMode),
+  ];
+  if (inputType !== 'secret') {
+    const prev = qrData.slice(0, 35) + (qrData.length > 35 ? '…' : '');
+    stats.push(chalk.dim.italic(`"${prev}"`));
+  }
+  console.log('  ' + stats.join(chalk.dim('  ·  ')));
+  console.log();
+
+  // ──────────────────────────────────────────────
+  // STEP 6 — Post-generation actions
+  // ──────────────────────────────────────────────
+  printDivider('Export');
+
+  const actions = await checkbox({
+    message: chalk.bold('What would you like to do with this QR code?'),
+    choices: [
+      {
+        name:    '  📋  Copy ASCII to clipboard  (paste into Slack, README, terminal)',
+        value:   'clipboard',
+        checked: true,
+      },
+      {
+        name:  '  🖼   Save as PNG  (high-res image)',
+        value: 'png',
+      },
+      {
+        name:  '  📐  Save as SVG  (scalable vector)',
+        value: 'svg',
+      },
+      {
+        name:  '  📄  Save as TXT  (plain Unicode half-blocks)',
+        value: 'txt',
+      },
+      {
+        name:  '  ☠   Self-destruct share  (host file via public QR, auto-destroy on download)',
+        value: 'destruct',
+      },
+    ],
+  });
+
+  console.log();
+
+  for (const action of actions) {
+    switch (action) {
+
+      case 'clipboard': {
+        const sp = ora({ text: 'Writing to clipboard…', spinner: 'dots' }).start();
+        try {
+          await clipboard.write(renderASCII(modules));
+          sp.succeed('ASCII QR code copied to clipboard!');
+        } catch (e) {
+          sp.fail('Clipboard unavailable: ' + e.message);
+          log.tip('Try running with elevated permissions, or use the TXT export instead.');
+        }
+        break;
+      }
+
+      case 'png': {
+        const fileName = await input({
+          message: 'PNG filename:',
+          default: sanitizeFilename(dataLabel) + '.png',
+        });
+        const sp = ora({ text: 'Rendering PNG…', spinner: 'arc' }).start();
+        try {
+          await exportPNG(qrData, fileName, { errorLevel });
+          sp.succeed(`PNG saved → ${chalk.underline(fileName)}`);
+        } catch (e) {
+          sp.fail('PNG export failed: ' + e.message);
+        }
+        break;
+      }
+
+      case 'svg': {
+        const fileName = await input({
+          message: 'SVG filename:',
+          default: sanitizeFilename(dataLabel) + '.svg',
+        });
+        const sp = ora({ text: 'Rendering SVG…', spinner: 'arc' }).start();
+        try {
+          await exportSVG(qrData, fileName, { errorLevel });
+          sp.succeed(`SVG saved → ${chalk.underline(fileName)}`);
+        } catch (e) {
+          sp.fail('SVG export failed: ' + e.message);
+        }
+        break;
+      }
+
+      case 'txt': {
+        const fileName = await input({
+          message: 'TXT filename:',
+          default: sanitizeFilename(dataLabel) + '.txt',
+        });
+        const sp = ora({ text: 'Writing text file…', spinner: 'dots' }).start();
+        try {
+          await exportTXT(qrData, fileName, { errorLevel });
+          sp.succeed(`TXT saved → ${chalk.underline(fileName)}`);
+        } catch (e) {
+          sp.fail('TXT export failed: ' + e.message);
+        }
+        break;
+      }
+
+      case 'destruct': {
+        const filePath = await input({ message: 'File to share (path):' });
+        const sp = ora({ text: 'Creating tunnel…', spinner: 'arc' }).start();
+        try {
+          const session = await createDestructQR(filePath);
+          sp.succeed(`Tunnel ready: ${chalk.underline(session.url)}`);
+
+          const destructModules = createMatrix(session.url, { errorLevel: 'M' });
+          const destructLines   = renderHalfBlock(destructModules, { gradient: 'fire' });
+          console.log();
+          for (const line of destructLines) console.log('  ' + line);
+          console.log();
+          log.warn('Scan to download. File will self-destruct after one download.');
+
+          const waitSp = ora({ text: 'Waiting for download…', spinner: 'dots', color: 'red' }).start();
+          await session.waitForDownload;
+          waitSp.succeed(chalk.red('FILE CONSUMED — TUNNEL CLOSED'));
+          await showExplosion();
+        } catch (e) {
+          sp.fail('Self-destruct failed: ' + e.message);
+        }
+        break;
+      }
+    }
+  }
+
+  console.log();
+  printDivider();
+  log.tip('Hold your phone camera over the QR code — no scanner app needed on iOS 11+ / Android 10+.');
+  log.info(`Encoded ${qrData.length} characters with ${errorLevel}-level error correction.`);
+  console.log();
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function sanitizeFilename(label) {
+  return label
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'qr-code';
+}

package/src/shortlink.js

@@ -0,0 +1,58 @@
+/**
+ * URL Shortener integration.
+ * Uses TinyURL's free API (no auth key required).
+ * Keeping the encoded text short → lower QR version → smaller, cleaner matrix.
+ */
+
+import axios from 'axios';
+
+/**
+ * Shorten a URL via TinyURL API.
+ * Falls back gracefully on network errors.
+ *
+ * @param {string} url - The long URL to shorten
+ * @returns {Promise<string>} - The shortened URL
+ */
+export async function shortenUrl(url) {
+  const response = await axios.get('https://tinyurl.com/api-create.php', {
+    params:  { url },
+    timeout: 7000,
+    headers: { 'User-Agent': 'qr-terminal/1.0.0' },
+  });
+
+  const result = response.data?.trim();
+  if (!result || !result.startsWith('http')) {
+    throw new Error('TinyURL returned an unexpected response');
+  }
+  return result;
+}
+
+/**
+ * Check if a string is a valid, parseable URL.
+ *
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function isValidUrl(str) {
+  try {
+    const u = new URL(str);
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Estimate how much "QR space" a URL will save after shortening.
+ * QR version increases roughly every ~17 chars of extra data.
+ *
+ * @param {number} originalLength
+ * @param {number} shortenedLength
+ * @returns {string} - Human-readable savings description
+ */
+export function estimateSavings(originalLength, shortenedLength) {
+  const saved   = originalLength - shortenedLength;
+  const percent = Math.round((saved / originalLength) * 100);
+  if (saved <= 0) return 'no change';
+  return `−${saved} chars (${percent}% smaller QR matrix)`;
+}

package/src/ui.js

@@ -0,0 +1,183 @@
+/**
+ * UI helpers: header, animated QR reveal, dark-mode detection
+ */
+
+import chalk from 'chalk';
+import figlet from 'figlet';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import { getQrVersion } from './engine.js';
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+const strip = s => s.replace(/\x1b\[[0-9;]*m/g, '');
+
+// ── Header ────────────────────────────────────────────────────────────────────
+
+export function printHeader() {
+  let art = '';
+  try {
+    art = figlet.textSync('QR  Terminal', { font: 'Slant', horizontalLayout: 'full' });
+  } catch {
+    art = figlet.textSync('QR Terminal');
+  }
+
+  const coloredArt  = gradient(['#FF416C', '#FF4B2B', '#F7971E', '#FFD200', '#4ECDC4', '#556270'])(art);
+  const subtitle    = chalk.dim('  High-Density Half-Block Rendering Engine  ·  v1.0.0');
+  const badges      = [
+    chalk.bgRgb(40,40,80).rgb(100,180,255)(' URL '),
+    chalk.bgRgb(40,40,80).rgb(100,255,160)(' WiFi '),
+    chalk.bgRgb(40,40,80).rgb(255,180,100)(' vCard '),
+    chalk.bgRgb(40,40,80).rgb(255,100,180)(' Secret '),
+  ].join(chalk.dim('  '));
+
+  const content = `${coloredArt}\n${subtitle}\n\n  ${badges}`;
+
+  console.log(
+    boxen(content, {
+      padding: { top: 1, bottom: 1, left: 2, right: 2 },
+      margin:  { top: 0, bottom: 1, left: 1, right: 0 },
+      borderStyle: 'round',
+      borderColor: 'cyan',
+    })
+  );
+}
+
+// ── Animated QR reveal ────────────────────────────────────────────────────────
+
+/**
+ * Scanline reveal animation.
+ *
+ * Phase 1 — Ghost scan: print each row as dim '░' blocks with a brief
+ *            bright cyan scanline flash before the real content settles.
+ * Phase 2 — Lock-on pulse: after all rows are revealed, sweep back up and
+ *            reprint every line 40 RGB units brighter, then settle to normal.
+ *            Simulates a camera locking focus on the QR code.
+ *
+ * @param {string[]} lines  - chalk-colored QR rows from renderHalfBlock()
+ * @param {object}   opts
+ * @param {number}   opts.speed  - ms per row (default 14)
+ */
+export async function revealQR(lines, { speed = 14 } = {}) {
+  process.stdout.write('\x1b[?25l'); // hide cursor
+
+  // Phase 1: row-by-row scanline reveal
+  for (const line of lines) {
+    const raw  = strip(line);
+    const w    = raw.length;
+
+    // Scanline flash — bright cyan bar
+    process.stdout.write('  ' + chalk.bgCyan.bold(' '.repeat(w)) + '\r');
+    await sleep(speed);
+
+    // Settle to the real colored line
+    process.stdout.write('  ' + line + '\n');
+  }
+
+  // Phase 2: brief full-QR lock-on pulse
+  await sleep(60);
+
+  // Move cursor back to the top of the QR block
+  process.stdout.write(`\x1b[${lines.length}A`);
+
+  // Print brightened version
+  for (const line of lines) {
+    const bright = brighten(line, 45);
+    process.stdout.write('  ' + bright + '\n');
+  }
+
+  await sleep(90);
+
+  // Restore normal
+  process.stdout.write(`\x1b[${lines.length}A`);
+  for (const line of lines) {
+    process.stdout.write('  ' + line + '\n');
+  }
+
+  process.stdout.write('\x1b[?25h'); // show cursor
+}
+
+/**
+ * Print QR code with a stats box underneath.
+ */
+export function printQR(qrLines, { label = '', size = 0, dataPreview = '', errorLevel = 'M' } = {}) {
+  const version  = getQrVersion(size);
+  const cols     = Math.min(process.stdout.columns || 80, 80);
+  const qrWidth  = strip(qrLines[0] ?? '').length + 2;
+
+  // Label bar
+  if (label) {
+    const bar = chalk.bold.cyanBright('  ┌─ ') +
+                chalk.bold.white(label) +
+                chalk.bold.cyanBright(' ' + '─'.repeat(Math.max(0, qrWidth - label.length - 4)) + '┐');
+    console.log(bar);
+  }
+
+  // QR rows (printed by caller via revealQR or directly)
+  for (const line of qrLines) {
+    console.log('  ' + line);
+  }
+
+  // Stats bar
+  const stats = [
+    chalk.bold.cyanBright(`v${version} QR`),
+    chalk.dim(`${size}×${size} modules`),
+    chalk.dim(`${qrLines.length * 2} → ${qrLines.length} rows`),
+    chalk.dim(`EC: ${errorLevel}`),
+  ];
+  if (dataPreview) {
+    const preview = dataPreview.slice(0, 35) + (dataPreview.length > 35 ? '…' : '');
+    stats.push(chalk.dim.italic(`"${preview}"`));
+  }
+
+  console.log('  ' + stats.join(chalk.dim('  ·  ')));
+  console.log();
+}
+
+// ── Utilities ─────────────────────────────────────────────────────────────────
+
+/**
+ * Detect if the user's terminal has a dark background.
+ * Uses COLORFGBG (set by iTerm2, xterm, etc.) and falls back to true.
+ */
+export function detectDarkMode() {
+  const colorfgbg = process.env.COLORFGBG;
+  if (colorfgbg) {
+    const parts = colorfgbg.split(';');
+    const bg    = parseInt(parts[parts.length - 1], 10);
+    if (!isNaN(bg)) return bg < 8;
+  }
+  const profile = (process.env.ITERM_PROFILE || process.env.TERM_PROFILE || '').toLowerCase();
+  if (profile.includes('light')) return false;
+  return true;
+}
+
+export function printDivider(label = '') {
+  const cols  = Math.min(process.stdout.columns || 72, 72);
+  const inner = label ? ` ${label} ` : '';
+  const line  = '─'.repeat(Math.max(0, cols - 4 - inner.length));
+  console.log(chalk.dim(`  ${inner}${line}`));
+}
+
+export const log = {
+  success: msg => console.log(chalk.green('  ✓  ') + chalk.white(msg)),
+  error:   msg => console.log(chalk.red('  ✗  ')   + chalk.white(msg)),
+  info:    msg => console.log(chalk.cyan('  ℹ  ')  + chalk.dim(msg)),
+  warn:    msg => console.log(chalk.yellow('  ⚠  ') + chalk.dim(msg)),
+  tip:     msg => console.log(chalk.magenta('  ★  ')+ chalk.white(msg)),
+};
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Increase all RGB values in ANSI-colored string by `amount`.
+ * Used for the lock-on pulse effect.
+ */
+function brighten(line, amount) {
+  return line.replace(
+    /\x1b\[38;2;(\d+);(\d+);(\d+)m/g,
+    (_, r, g, b) => {
+      const clamp = v => Math.min(255, parseInt(v) + amount);
+      return `\x1b[38;2;${clamp(r)};${clamp(g)};${clamp(b)}m`;
+    }
+  );
+}