qr-terminal 1.0.0

package/src/live-preview.js

@@ -0,0 +1,199 @@
+/**
+ * Live Preview Engine
+ *
+ * WYSIWYG terminal experience: QR code re-renders on every keystroke.
+ * Per-keystroke info badge shows QR version + char count in real-time.
+ * Placeholder frame holds the exact space so there's no layout jump.
+ */
+
+import chalk from 'chalk';
+import { createMatrix, renderHalfBlock, getQrVersion } from './engine.js';
+
+const ESC = {
+  up:         n  => `\x1b[${n}A`,
+  clearDown:  '\x1b[J',
+  hideCursor: '\x1b[?25l',
+  showCursor: '\x1b[?25h',
+  clearLine:  '\x1b[2K\r',
+};
+
+const strip = s => s.replace(/\x1b\[[0-9;]*m/g, '');
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/**
+ * Launch a live-updating QR preview input.
+ * Returns a Promise that resolves with the final string on Enter.
+ */
+export function liveInput({ label = 'Enter text', errorLevel = 'M', gradient = 'none' } = {}) {
+  return new Promise((resolve, reject) => {
+    let input        = '';
+    let lastHeight   = 0;
+    let debounce     = null;
+    let lastVersion  = 0;
+
+    // ── Frame builder ─────────────────────────────────────────────────────────
+
+    const buildLines = (text) => {
+      const lines    = [];
+      const termCols = Math.min(process.stdout.columns || 80, 100);
+
+      if (!text) {
+        // Ghost placeholder: exact dimensions of a version-3 QR
+        const boxW = 33;
+        const boxH = 17;
+        const pad  = 4;
+        const p    = ' '.repeat(pad);
+
+        lines.push('');
+        lines.push(p + chalk.rgb(30, 40, 60)('┌' + '─'.repeat(boxW + 2) + '┐'));
+        for (let i = 0; i < boxH; i++) {
+          if (i === Math.floor(boxH / 2) - 1) {
+            const msg  = '  Enter text to generate QR  ';
+            const side = Math.floor((boxW + 2 - msg.length) / 2);
+            lines.push(
+              p + chalk.rgb(30,40,60)('│') +
+              ' '.repeat(side) +
+              chalk.rgb(60, 80, 120).italic(msg) +
+              ' '.repeat(boxW + 2 - side - msg.length) +
+              chalk.rgb(30,40,60)('│')
+            );
+          } else if (i === Math.floor(boxH / 2) + 1) {
+            const hint  = '  ▀▄ half-block engine ready  ';
+            const hside = Math.floor((boxW + 2 - hint.length) / 2);
+            lines.push(
+              p + chalk.rgb(30,40,60)('│') +
+              ' '.repeat(hside) +
+              chalk.rgb(40, 60, 90).dim(hint) +
+              ' '.repeat(boxW + 2 - hside - hint.length) +
+              chalk.rgb(30,40,60)('│')
+            );
+          } else {
+            // Subtle scanline pattern
+            const dotRow = (i % 4 === 0)
+              ? chalk.rgb(20, 30, 50)('·'.repeat(boxW + 2))
+              : ' '.repeat(boxW + 2);
+            lines.push(p + chalk.rgb(30,40,60)('│') + dotRow + chalk.rgb(30,40,60)('│'));
+          }
+        }
+        lines.push(p + chalk.rgb(30, 40, 60)('└' + '─'.repeat(boxW + 2) + '┘'));
+        lines.push('');
+      } else {
+        try {
+          const modules = createMatrix(text, { errorLevel });
+          const qrLines = renderHalfBlock(modules, { gradient });
+          const qrWidth = strip(qrLines[0] ?? '').length;
+          const pad     = Math.max(4, Math.floor((termCols - qrWidth) / 2));
+          const p       = ' '.repeat(pad);
+          const v       = getQrVersion(modules.size);
+
+          // Version bump badge (flash when version increases)
+          const vChanged   = v !== lastVersion;
+          lastVersion      = v;
+
+          const vBadge = vChanged
+            ? chalk.bgCyan.bold.black(` QR v${v} `) + chalk.cyan(' ◄ upgraded')
+            : chalk.bgRgb(20,20,50).rgb(80,160,255)(` QR v${v} `);
+
+          const capBadge = chalk.dim(`${modules.size}×${modules.size}`);
+          const lenBadge = text.length > 0
+            ? chalk.dim(`${text.length} chars`)
+            : '';
+
+          lines.push('');
+          lines.push(
+            p + vBadge +
+            chalk.dim('  ·  ') + capBadge +
+            chalk.dim('  ·  ') + lenBadge
+          );
+          lines.push('');
+
+          for (const line of qrLines) lines.push(p + line);
+          lines.push('');
+        } catch (e) {
+          lines.push('');
+          lines.push(chalk.red('  ⚠  Input exceeds QR capacity — try shortening the text'));
+          lines.push('');
+        }
+      }
+
+      // Input field
+      const promptPrefix = chalk.bold.cyan('  › ') + chalk.bold.white(label + ':') + ' ';
+      const cursor       = chalk.bgCyan.black(' ');
+      lines.push(promptPrefix + chalk.white(text) + cursor);
+      lines.push('');
+
+      return lines;
+    };
+
+    // ── Draw / clear ──────────────────────────────────────────────────────────
+
+    const draw = (lines) => {
+      for (const line of lines) process.stdout.write(line + '\n');
+      lastHeight = lines.length;
+    };
+
+    const clear = () => {
+      if (lastHeight > 0) {
+        process.stdout.write(ESC.up(lastHeight) + ESC.clearDown);
+      }
+    };
+
+    const redraw = () => {
+      if (debounce) clearTimeout(debounce);
+      debounce = setTimeout(() => {
+        clear();
+        draw(buildLines(input));
+      }, 16);
+    };
+
+    // ── Keypress handler ──────────────────────────────────────────────────────
+
+    const onData = (key) => {
+      if (key === '\r' || key === '\n') {
+        if (debounce) clearTimeout(debounce);
+        clear();
+        process.stdout.write(
+          chalk.bold.cyan('  › ') +
+          chalk.bold.white(label + ':') + ' ' +
+          chalk.white(input) + '\n'
+        );
+        done(null, input);
+
+      } else if (key === '\u0003') {
+        done(new Error('Cancelled'));
+
+      } else if (key === '\u007f' || key === '\b') {
+        input = input.slice(0, -1);
+        redraw();
+
+      } else if (key === '\u001b') {
+        input = '';
+        redraw();
+
+      } else if (key.charCodeAt(0) >= 32 && !key.startsWith('\x1b')) {
+        input += key;
+        redraw();
+      }
+    };
+
+    const done = (err, result) => {
+      process.stdin.removeListener('data', onData);
+      try {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+      } catch {}
+      process.stdout.write(ESC.showCursor);
+      if (err) reject(err);
+      else resolve(result);
+    };
+
+    // ── Boot ──────────────────────────────────────────────────────────────────
+
+    process.stdout.write(ESC.hideCursor);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', onData);
+    draw(buildLines(input));
+  });
+}

package/src/luma.js

@@ -0,0 +1,58 @@
+/**
+ * Luma Detection via OSC 11
+ *
+ * Sends the OSC 11 escape sequence to query the terminal's actual background
+ * color, then computes its luminance. Returns { r, g, b, luminance, isLight }
+ * or null if the terminal doesn't support it (with a 400ms timeout).
+ */
+
+export async function detectTerminalBgColor() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
+
+  return new Promise((resolve) => {
+    let buffer = '';
+
+    const timeout = setTimeout(() => {
+      cleanup();
+      resolve(null);
+    }, 400);
+
+    const onData = (chunk) => {
+      buffer += chunk;
+      // OSC 11 response format: \x1b]11;rgb:RRRR/GGGG/BBBB\x07
+      // Some terminals send \x1b\\ as terminator instead of \x07
+      const match = buffer.match(/\x1b\]11;rgb:([0-9a-fA-F]+)\/([0-9a-fA-F]+)\/([0-9a-fA-F]+)/);
+      if (match) {
+        cleanup();
+        // Values are 16-bit (0000–FFFF); take the high byte for 0–255
+        const r = parseInt(match[1].slice(0, 2), 16);
+        const g = parseInt(match[2].slice(0, 2), 16);
+        const b = parseInt(match[3].slice(0, 2), 16);
+        // WCAG relative luminance
+        const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+        resolve({ r, g, b, luminance, isLight: luminance > 127 });
+      }
+    };
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      try {
+        process.stdin.removeListener('data', onData);
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+      } catch {}
+    };
+
+    try {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.setEncoding('latin1');
+      process.stdin.on('data', onData);
+      // Send OSC 11 query
+      process.stdout.write('\x1b]11;?\x07');
+    } catch {
+      cleanup();
+      resolve(null);
+    }
+  });
+}

package/src/matrix-rain.js

@@ -0,0 +1,115 @@
+/**
+ * Matrix Rain Animation
+ *
+ * After the QR appears, cascading green "rain droplets" sweep down each
+ * column before the code settles to its final gradient.
+ * Contrast is preserved: each droplet is bright (#00FF41), which has
+ * sufficient luminance against dark terminal backgrounds.
+ */
+
+import { buildParticleData } from './engine.js';
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/**
+ * @param {object} modules     - QR modules from createMatrix()
+ * @param {object} options
+ * @param {string} options.gradient   - Final color gradient
+ * @param {number} options.duration   - Rain duration in ms (default 2000)
+ * @param {number} options.fps        - Frames per second (default 24)
+ */
+export async function matrixRainQR(modules, { gradient = 'none', duration = 2000, fps = 24 } = {}) {
+  const { particles, displayRows, totalCols } = buildParticleData(modules, { gradient });
+  const frameMs    = Math.floor(1000 / fps);
+  const frameCount = Math.floor(duration / frameMs);
+
+  // Per-column rain phase offset (0–1, cycles continuously)
+  const phases = Array.from({ length: totalCols }, () => Math.random());
+
+  // Build a lookup for quick per-cell access: fb[row][col] = particle data
+  const lookup = Array.from({ length: displayRows }, () => new Array(totalCols).fill(null));
+  for (const p of particles) lookup[p.targetRow][p.targetCol] = p;
+
+  process.stdout.write('\x1b[?25l');
+
+  // Print initial static frame first (so there's no blank before rain starts)
+  renderStatic(lookup, displayRows, totalCols, phases, 0);
+
+  for (let f = 0; f < frameCount; f++) {
+    const progress = f / frameCount; // 0 → 1
+
+    // Advance rain phases
+    for (let c = 0; c < totalCols; c++) {
+      phases[c] = (phases[c] + 0.04) % 1;
+    }
+
+    process.stdout.write(`\x1b[${displayRows}A`);
+
+    for (let row = 0; row < displayRows; row++) {
+      let line = '', curColor = null;
+      const ty = displayRows > 1 ? row / (displayRows - 1) : 0;
+
+      for (let col = 0; col < totalCols; col++) {
+        const cell = lookup[row][col];
+        if (!cell) {
+          if (curColor) { line += '\x1b[0m'; curColor = null; }
+          line += ' ';
+          continue;
+        }
+
+        // Rain droplet: bright where phase matches row position
+        const phase    = phases[col];
+        const relRow   = ty;
+        const dist     = Math.abs(((phase - relRow + 1.5) % 1) - 0.5); // wrapped distance
+        const droplet  = Math.max(0, 1 - dist * 8);
+
+        // Fade rain out as progress → 1, revealing final gradient
+        const rainStr  = droplet * (1 - progress);
+
+        const base  = cell.color;
+        const rain  = [0, 255, 65]; // matrix green
+        const r = Math.round(base[0] * (1 - rainStr) + rain[0] * rainStr);
+        const g = Math.round(base[1] * (1 - rainStr) + rain[1] * rainStr);
+        const b = Math.round(base[2] * (1 - rainStr) + rain[2] * rainStr);
+
+        const key = `${r},${g},${b}`;
+        if (key !== curColor) {
+          line += `\x1b[38;2;${r};${g};${b}m`;
+          curColor = key;
+        }
+        line += cell.char;
+      }
+
+      if (curColor) line += '\x1b[0m';
+      process.stdout.write('  ' + line + '\n');
+    }
+
+    await sleep(frameMs);
+  }
+
+  // Final settle: reprint without rain
+  process.stdout.write(`\x1b[${displayRows}A`);
+  renderStatic(lookup, displayRows, totalCols, phases, 1);
+
+  process.stdout.write('\x1b[?25h');
+}
+
+function renderStatic(lookup, displayRows, totalCols, phases, _progress) {
+  for (let row = 0; row < displayRows; row++) {
+    let line = '', curColor = null;
+    for (let col = 0; col < totalCols; col++) {
+      const cell = lookup[row][col];
+      if (!cell) {
+        if (curColor) { line += '\x1b[0m'; curColor = null; }
+        line += ' ';
+      } else {
+        const [r, g, b] = cell.color;
+        const key = `${r},${g},${b}`;
+        if (key !== curColor) { line += `\x1b[38;2;${r};${g};${b}m`; curColor = key; }
+        line += cell.char;
+      }
+    }
+    if (curColor) line += '\x1b[0m';
+    process.stdout.write('  ' + line + '\n');
+  }
+}

package/src/particle.js

@@ -0,0 +1,91 @@
+/**
+ * Particle Fly-In Animation — "The Transformer Effect"
+ *
+ * Each dark QR module becomes a particle that starts at a random scatter
+ * position and flies into its correct place with cubic ease-out.
+ * A stagger delay (0–30% of duration) makes the arrival feel organic.
+ */
+
+import { buildParticleData } from './engine.js';
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/**
+ * Animate QR code appearing via particle fly-in.
+ *
+ * @param {object} modules   - QR modules from createMatrix()
+ * @param {object} options
+ * @param {string} options.gradient  - Gradient preset name
+ * @param {number} options.fps       - Frames per second (default 30)
+ * @param {number} options.duration  - Total animation ms (default 1100)
+ */
+export async function animateParticleFlyIn(modules, options = {}) {
+  const { gradient = 'none', fps = 30, duration = 1100 } = options;
+  const frameCount = Math.floor(duration / (1000 / fps));
+  const frameMs    = Math.floor(1000 / fps);
+
+  const { particles, displayRows, totalCols } = buildParticleData(modules, { gradient });
+
+  // Assign each particle a random starting position + stagger delay
+  const rng = () => Math.random();
+  const seeded = particles.map(p => ({
+    ...p,
+    startRow:  rng() * displayRows,
+    startCol:  (rng() - 0.5) * totalCols * 2 + totalCols / 2, // wider scatter on X
+    delay:     rng() * 0.30,   // 0–30% stagger
+  }));
+
+  // Print blank placeholder
+  process.stdout.write('\x1b[?25l');
+  const blank = ' '.repeat(totalCols);
+  for (let i = 0; i < displayRows; i++) process.stdout.write('  ' + blank + '\n');
+
+  for (let f = 0; f <= frameCount; f++) {
+    const globalT = f / frameCount;
+
+    // Build framebuffer: 2D array of { char, color } | null
+    const fb = Array.from({ length: displayRows }, () => new Array(totalCols).fill(null));
+
+    for (const p of seeded) {
+      // Apply per-particle stagger
+      const localT = Math.max(0, (globalT - p.delay) / (1 - p.delay));
+      // Cubic ease-out
+      const e = 1 - Math.pow(1 - localT, 3);
+
+      const row = Math.round(p.startRow + (p.targetRow - p.startRow) * e);
+      const col = Math.round(p.startCol + (p.targetCol - p.startCol) * e);
+
+      if (row >= 0 && row < displayRows && col >= 0 && col < totalCols) {
+        fb[row][col] = { char: p.char, color: p.color };
+      }
+    }
+
+    // Move cursor back to top of animation area
+    process.stdout.write(`\x1b[${displayRows}A`);
+
+    // Render framebuffer
+    for (const row of fb) {
+      let line = '', curColor = null;
+      for (const cell of row) {
+        if (!cell) {
+          if (curColor) { line += '\x1b[0m'; curColor = null; }
+          line += ' ';
+        } else {
+          const [r, g, b] = cell.color;
+          const key = `${r},${g},${b}`;
+          if (key !== curColor) {
+            line += `\x1b[38;2;${r};${g};${b}m`;
+            curColor = key;
+          }
+          line += cell.char;
+        }
+      }
+      if (curColor) line += '\x1b[0m';
+      process.stdout.write('  ' + line + '\n');
+    }
+
+    await sleep(frameMs);
+  }
+
+  process.stdout.write('\x1b[?25h');
+}