@lardexx/arenacode 0.0.0-stage → 2.5.2

package/src/tui/dialogs.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * Dialog look copied from opencode's `ui/dialog.tsx` + `ui/dialog-select.tsx`:
+ * a panel-background rectangle, centered horizontally, starting a quarter of the way
+ * down, title in bold on the left, `esc` on the right, a filter line, then the list
+ * with right-aligned shortcuts and the selected row painted in the primary colour.
+ */
+
+const R = require('./render');
+const { bgSeq, fgSeq, RESET } = require('./theme');
+const { bgWrap, spaces } = require('./widgets');
+
+const SIZES = { medium: 60, large: 88, xlarge: 116 };
+
+function frameWidth(size, W) {
+  return Math.max(24, Math.min(SIZES[size || 'medium'] || 60, W - 8));
+}
+
+/** one dialog row: full width, panel background, optional painters */
+function row(t, width, left, right = '') {
+  const bg = bgSeq(t.c.backgroundPanel);
+  const content = spaces(4) + left + spaces(Math.max(1, width - 8 - R.vlen(left) - R.vlen(right))) + right + spaces(4);
+  return bgWrap(bg, content, width);
+}
+
+function blankRow(t, width) {
+  return bgWrap(bgSeq(t.c.backgroundPanel), '', width);
+}
+
+/**
+ * Generic list dialog.
+ * items: [{ label, hint, group, active }]  — `group` starts a new section header
+ */
+function listDialog(t, opts) {
+  const { W, size = 'medium', title, filter, items, index = 0, empty = 'No results found', footer } = opts;
+  const width = frameWidth(size, W);
+  const lines = [];
+  const bg = bgSeq(t.c.backgroundPanel);
+
+  lines.push(row(t, width, `${fgSeq(t.c.text)}\x1b[1m${title}${RESET}`, `${fgSeq(t.c.textMuted)}esc${RESET}`));
+  lines.push(blankRow(t, width));
+  lines.push(row(t, width, filter ? `${fgSeq(t.c.text)}${filter}${RESET}` : `${fgSeq(t.c.textMuted)}Search${RESET}`));
+  lines.push(blankRow(t, width));
+
+  if (!items.length) {
+    lines.push(row(t, width, `${fgSeq(t.c.textMuted)}${empty}${RESET}`));
+  }
+
+  let index2 = 0;
+  for (const item of items) {
+    if (item.group) {
+      lines.push(row(t, width, `${fgSeq(t.c.textMuted)}\x1b[1m${item.group}${RESET}`));
+      continue;
+    }
+    const active = index2 === index;
+    const pad = active ? spaces(1) : spaces(3);
+    const hint = item.hint ? `${fgSeq(active ? t.c.background : t.c.textMuted)}${item.hint}${RESET}` : '';
+    const left = item.grouped ? pad : spaces(3);
+    const label = `${fgSeq(active ? t.c.background : item.dim ? t.c.textMuted : t.c.text)}${item.label}${RESET}`;
+    const content = left + label;
+    const full = spaces(4) + content + spaces(Math.max(1, width - 8 - R.vlen(content) - R.vlen(hint))) + hint + spaces(4);
+    if (active) {
+      lines.push(`${bgSeq(t.c.primary)}${full.replace(/\x1b\[0m/g, '\x1b[0m' + bgSeq(t.c.primary))}${RESET}`);
+    } else {
+      lines.push(bgWrap(bg, full, width));
+    }
+    index2++;
+  }
+
+  lines.push(blankRow(t, width));
+  const hints = footer || [];
+  const hintText = hints.map(([k, label]) => `${fgSeq(t.c.text)}${k}${RESET} ${fgSeq(t.c.textMuted)}${label}${RESET}`).join('  ');
+  lines.push(row(t, width, hintText));
+  lines.push(blankRow(t, width));
+  return { lines, width, x: Math.max(0, Math.floor((W - width) / 2)) };
+}
+
+/** the confirm card used for terminal / file / plan requests */
+function confirmDialog(t, opts) {
+  const { W, title, subject, note = '', options = [], index = 0, footer = [] } = opts;
+  const width = frameWidth('medium', W);
+  const lines = [];
+  const bg = bgSeq(t.c.backgroundPanel);
+
+  lines.push(row(t, width, `${fgSeq(t.c.text)}\x1b[1m${title}${RESET}`, `${fgSeq(t.c.textMuted)}esc${RESET}`));
+  lines.push(blankRow(t, width));
+  if (subject) {
+    const subjectLines = String(subject).split('\n').flatMap((line) => R.wrap(line, width - 10));
+    for (const line of subjectLines.slice(0, 12)) {
+      lines.push(row(t, width, `${fgSeq(t.c.text)}${line}${RESET}`));
+    }
+  }
+  if (note) {
+    for (const line of R.wrap(note, width - 10)) lines.push(row(t, width, `${fgSeq(t.c.textMuted)}${line}${RESET}`));
+  }
+  lines.push(blankRow(t, width));
+  options.forEach((opt, i) => {
+    const active = i === index;
+    const hint = opt.hint ? `${fgSeq(active ? t.c.background : t.c.textMuted)}${opt.hint}${RESET}` : '';
+    const content = (active ? spaces(1) : spaces(3)) + `${fgSeq(active ? t.c.background : t.c.text)}${opt.label}${RESET}`;
+    const full = spaces(4) + content + spaces(Math.max(1, width - 8 - R.vlen(content) - R.vlen(hint))) + hint + spaces(4);
+    lines.push(
+      active
+        ? `${bgSeq(t.c.primary)}${full.replace(/\x1b\[0m/g, '\x1b[0m' + bgSeq(t.c.primary))}${RESET}`
+        : bgWrap(bg, full, width),
+    );
+  });
+  lines.push(blankRow(t, width));
+  const hintText = footer.map(([k, label]) => `${fgSeq(t.c.text)}${k}${RESET} ${fgSeq(t.c.textMuted)}${label}${RESET}`).join('  ');
+  lines.push(row(t, width, hintText));
+  lines.push(blankRow(t, width));
+  return { lines, width, x: Math.max(0, Math.floor((W - width) / 2)) };
+}
+
+/** plain informational dialog (toasts, errors) */
+function alertDialog(t, opts) {
+  const { W, title, body = [], footer = [] } = opts;
+  const width = frameWidth('medium', W);
+  const lines = [];
+  lines.push(row(t, width, `${fgSeq(t.c.text)}\x1b[1m${title}${RESET}`, `${fgSeq(t.c.textMuted)}esc${RESET}`));
+  lines.push(blankRow(t, width));
+  for (const line of body) lines.push(row(t, width, `${fgSeq(t.c.textMuted)}${R.vclip(line, width - 10)}${RESET}`));
+  lines.push(blankRow(t, width));
+  const hintText = footer.map(([k, label]) => `${fgSeq(t.c.text)}${k}${RESET} ${fgSeq(t.c.textMuted)}${label}${RESET}`).join('  ');
+  if (hintText) lines.push(row(t, width, hintText));
+  lines.push(blankRow(t, width));
+  return { lines, width, x: Math.max(0, Math.floor((W - width) / 2)) };
+}
+
+function dialogY(H, height) {
+  const quarter = Math.floor(H / 4);
+  return Math.max(0, Math.min(quarter, H - height - 1));
+}
+
+module.exports = { listDialog, confirmDialog, alertDialog, frameWidth, dialogY, SIZES };

package/src/tui/keys.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * Key parser: raw stdin chunks -> key events.
+ *
+ *   { name: 'a', ctrl: false, alt: false, shift: false, seq: 'a' }
+ *   { name: 'enter' | 'tab' | 'backspace' | 'escape' | 'up' | 'down' | ... }
+ *
+ * A lone ESC is only reported after a short timeout, so escape sequences
+ * (arrows, function keys) are not mistaken for the Esc key.
+ */
+const CSI_KEYS = {
+  A: 'up',
+  B: 'down',
+  C: 'right',
+  D: 'left',
+  H: 'home',
+  F: 'end',
+  Z: 'shift+tab',
+  '1~': 'home',
+  '2~': 'insert',
+  '3~': 'delete',
+  '4~': 'end',
+  '5~': 'pageup',
+  '6~': 'pagedown',
+  '7~': 'home',
+  '8~': 'end',
+  '11~': 'f1',
+  '12~': 'f2',
+  '13~': 'f3',
+  '14~': 'f4',
+};
+
+class KeyParser {
+  constructor(onKey) {
+    this.onKey = onKey;
+    this.buffer = '';
+    this.escTimer = null;
+  }
+
+  feed(chunk) {
+    this.buffer += chunk;
+    this._drain();
+  }
+
+  _emit(key) {
+    if (this.escTimer) {
+      clearTimeout(this.escTimer);
+      this.escTimer = null;
+    }
+    this.onKey(key);
+  }
+
+  _drain() {
+    while (this.buffer.length) {
+      const seq = this._next();
+      if (seq === null || seq === '') {
+        // incomplete escape sequence: wait for more bytes
+        if (this.escTimer) clearTimeout(this.escTimer);
+        this.escTimer = setTimeout(() => {
+          if (this.buffer === '\x1b') {
+            this.buffer = '';
+            this._emit({ name: 'escape', ctrl: false, alt: false, shift: false, seq: '\x1b' });
+          }
+        }, 40);
+        return;
+      }
+      this.buffer = this.buffer.slice(seq.length);
+      const key = this._decode(seq);
+      if (key) this._emit(key);
+    }
+  }
+
+  _next() {
+    const b = this.buffer;
+    if (b[0] !== '\x1b') return b[0];
+    if (b.length === 1) return null;
+    if (b[1] === '[') {
+      // CSI: ESC [ params final
+      let i = 2;
+      while (i < b.length && !/[A-Za-z~]/.test(b[i])) i += 1;
+      if (i >= b.length) return null;
+      return b.slice(0, i + 1);
+    }
+    if (b[1] === 'O') {
+      if (b.length < 3) return null;
+      return b.slice(0, 3);
+    }
+    // Alt + char
+    return b.slice(0, 2);
+  }
+
+  _decode(seq) {
+    const mk = (name, extra = {}) => ({ name, ctrl: false, alt: false, shift: false, seq, ...extra });
+
+    if (seq.length === 1) {
+      const code = seq.charCodeAt(0);
+      if (code === 13) return mk('enter');
+      if (code === 10) return mk('enter');
+      if (code === 9) return mk('tab');
+      if (code === 127) return mk('backspace');
+      if (code === 27) return mk('escape');
+      if (code === 3) return mk('c', { ctrl: true });
+      if (code === 4) return mk('d', { ctrl: true });
+      if (code < 27) return mk(String.fromCharCode(code + 96), { ctrl: true });
+      return mk(seq);
+    }
+
+    if (seq[0] === '\x1b' && seq[1] === '[') {
+      const body = seq.slice(2, -1);
+      const final = seq[seq.length - 1];
+      if (final === '~') {
+        const name = CSI_KEYS[`${body}~`];
+        return name ? mk(name) : null;
+      }
+      if (final === 'Z') return mk('tab', { shift: true });
+      const name = CSI_KEYS[final];
+      if (name) return mk(name, { shift: /;2$/.test(body) });
+      return null;
+    }
+
+    if (seq[0] === '\x1b' && seq[1] === 'O') {
+      const name = CSI_KEYS[seq[2]];
+      return name ? mk(name) : null;
+    }
+
+    // ESC + char = alt+char
+    const ch = seq.slice(1);
+    if (ch === '\r') return mk('enter', { alt: true });
+    return mk(ch, { alt: true });
+  }
+}
+
+module.exports = { KeyParser };

package/src/tui/logo.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * arenacode wordmark, drawn the way opencode draws its own (packages/tui/src/logo.tsx):
+ * two-tone block letters where `_` is a shadow-filled cell, `^` a half block on the
+ * shadow background, `~`/`,` half blocks drawn in the shadow colour.
+ *
+ * Left half is muted and regular, right half bold — the same trick opencode uses for
+ * "open" + "code".
+ */
+
+const { fgSeq, bgSeq, RESET, tint } = require('./theme');
+
+const LOGO = {
+  left: ['                        ', '█▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀█', '█▀▀█ █▀▀▄ █^^^ █__█ █▀▀█', '▀▀▀▀ ▀~~▀ ▀▀▀▀ ▀~~▀ ▀▀▀▀'],
+  right: ['             ▄     ', '█▀▀▀ █▀▀█ █▀▀█ █▀▀█', '█___ █__█ █__█ █^^^', '▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀'],
+};
+
+const LOGO_WIDTH = LOGO.left[1].length + 1 + LOGO.right[1].length;
+
+function fgPaint(color, text, bold) {
+  return `${fgSeq(color)}${bold ? '\x1b[1m' : ''}${text}${RESET}`;
+}
+
+function bgFill(bgColor, text, fgColor, bold) {
+  return `${fgSeq(fgColor)}${bgSeq(bgColor)}${bold ? '\x1b[1m' : ''}${text}${RESET}`;
+}
+
+function paintLine(line, color, shadow, bold) {
+  let out = '';
+  for (const ch of line) {
+    if (ch === '_') out += bgFill(shadow, ' ', color, bold);
+    else if (ch === '^') out += bgFill(shadow, '▀', color, bold);
+    else if (ch === '~') out += fgPaint(shadow, '▀', bold);
+    else if (ch === ',') out += fgPaint(shadow, '▄', bold);
+    else out += fgPaint(color, ch, bold);
+  }
+  return out;
+}
+
+/** Four styled lines, in opencode's two-tone style. */
+function logoLines(t) {
+  const shadowLeft = tint(t.c.background, t.c.textMuted, 0.22);
+  const shadowRight = tint(t.c.background, t.c.text, 0.22);
+  const lines = [];
+  for (let i = 0; i < LOGO.left.length; i++) {
+    // opencode keeps the left half muted; at this size a slightly brighter grey reads better
+    const leftColor = tint(t.c.background, t.c.textMuted, 1.6);
+    lines.push(paintLine(LOGO.left[i], leftColor, shadowLeft, true) + ' ' + paintLine(LOGO.right[i], t.c.text, shadowRight, true));
+  }
+  return lines;
+}
+
+module.exports = { LOGO, LOGO_WIDTH, logoLines };

package/src/tui/render.js

@@ -0,0 +1,256 @@
+'use strict';
+
+/** ANSI-aware text helpers: everything measures and clips by *visible* width. */
+
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/g;
+
+function strip(s) {
+  return String(s).replace(ANSI_RE, '');
+}
+
+function charWidth(ch) {
+  const cp = ch.codePointAt(0);
+  if (cp === 0x200d) return 0;
+  if (cp >= 0x0300 && cp <= 0x036f) return 0;
+  if (
+    cp > 0x1100 &&
+    (cp <= 0x115f ||
+      (cp >= 0x2e80 && cp <= 0xa4cf) ||
+      (cp >= 0xac00 && cp <= 0xd7a3) ||
+      (cp >= 0xf900 && cp <= 0xfaff) ||
+      (cp >= 0xfe30 && cp <= 0xfe6f) ||
+      (cp >= 0xff00 && cp <= 0xff60) ||
+      (cp >= 0xffe0 && cp <= 0xffe6) ||
+      (cp >= 0x1f300 && cp <= 0x1faff))
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+function vlen(s) {
+  let w = 0;
+  for (const ch of strip(s)) w += charWidth(ch);
+  return w;
+}
+
+/** Clips to `max` visible cells, keeping escape sequences and closing styles. */
+function vclip(s, max) {
+  const text = String(s);
+  if (vlen(text) <= max) return text;
+  let out = '';
+  let w = 0;
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === '\x1b') {
+      const match = /^\x1b\[[0-9;?]*[A-Za-z]/.exec(text.slice(i));
+      if (match) {
+        out += match[0];
+        i += match[0].length;
+        continue;
+      }
+    }
+    const ch = String.fromCodePoint(text.codePointAt(i));
+    const cw = charWidth(ch);
+    if (w + cw > max - 1) {
+      out += '…';
+      break;
+    }
+    out += ch;
+    w += cw;
+    i += ch.length;
+  }
+  return out + '\x1b[0m';
+}
+
+function vpad(s, width) {
+  const diff = width - vlen(s);
+  return diff > 0 ? String(s) + ' '.repeat(diff) : String(s);
+}
+
+/** Word wrap without breaking ANSI codes (styles are expected per line). */
+function wrap(text, width) {
+  const out = [];
+  if (width <= 0) return [''];
+  for (const rawLine of String(text).split('\n')) {
+    if (rawLine === '') {
+      out.push('');
+      continue;
+    }
+    const words = rawLine.split(/(\s+)/);
+    let line = '';
+    for (const word of words) {
+      if (vlen(line) + vlen(word) <= width) {
+        line += word;
+        continue;
+      }
+      if (vlen(word) > width) {
+        // long token: hard break
+        let rest = word;
+        while (vlen(rest) > width) {
+          out.push(vclip(line + rest, width));
+          const consumed = strip(vclip(rest, width)).length;
+          rest = rest.slice(consumed);
+          line = '';
+        }
+        line += rest;
+        continue;
+      }
+      if (line.trim() !== '') out.push(line.replace(/\s+$/, ''));
+      line = word.replace(/^\s+/, '');
+    }
+    out.push(line.replace(/\s+$/, ''));
+  }
+  return out;
+}
+
+const BOX = {
+  tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│',
+  ltee: '├', rtee: '┤', cross: '┼',
+};
+
+/**
+ * A bordered panel. `lines` are already coloured; they are clipped and padded to
+ * the inner width. Returns exactly `height` lines, each `width` cells wide.
+ */
+function box({ width, height, title = '', lines = [], theme, active = false, footer = '' }) {
+  if (width < 4 || height < 3) return [];
+  const innerW = width - 2;
+  const borderColor = active ? theme.borderActive : theme.border;
+  const b = (s) => borderColor(s);
+  const out = [];
+
+  const head = title ? ` ${title} ` : '';
+  const headW = vlen(head);
+  const fill = Math.max(0, innerW - headW - 1);
+  out.push(b(BOX.tl) + (title ? b(BOX.h) + theme.title(head) + b(BOX.h.repeat(fill)) : b(BOX.h.repeat(innerW))) + b(BOX.tr));
+
+  const bodyRows = height - 2;
+  for (let i = 0; i < bodyRows; i += 1) {
+    let content = lines[i] === undefined ? '' : lines[i];
+    let suffix = '';
+    if (i === bodyRows - 1 && footer) {
+      content = footer;
+      suffix = '';
+    }
+    out.push(b(BOX.v) + vpad(vclip(content, innerW), innerW) + b(BOX.v) + suffix);
+  }
+  out.push(b(BOX.bl) + b(BOX.h.repeat(innerW)) + b(BOX.br));
+  return out;
+}
+
+/** Side-by-side composition: every column is a list of equal-height lines. */
+function columns(parts, gap = 1, theme = null) {
+  const height = Math.max(...parts.map((p) => p.lines.length), 0);
+  const out = [];
+  const sep = theme ? theme.border(BOX.v) : '│';
+  for (let row = 0; row < height; row += 1) {
+    out.push(
+      parts
+        .map((part) => {
+          const line = part.lines[row] === undefined ? ' '.repeat(part.width) : part.lines[row];
+          return vpad(vclip(line, part.width), part.width);
+        })
+        .join(' '.repeat(gap) + sep + ' '.repeat(gap)),
+    );
+  }
+  return out;
+}
+
+function hline(width, theme, label = '') {
+  const color = theme ? theme.border : (s) => s;
+  if (!label) return color(BOX.h.repeat(Math.max(0, width)));
+  const head = ` ${label} `;
+  const rest = Math.max(0, width - vlen(head) - 2);
+  return color(BOX.h.repeat(2)) + (theme ? theme.dim(head) : head) + color(BOX.h.repeat(rest));
+}
+
+
+/** Visible-cell slice [start, end): keeps the escape sequences that fall inside. */
+function vslice(s, start, end) {
+  const text = String(s);
+  let out = '';
+  let cell = 0;
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === '\x1b') {
+      const match = /^\x1b\[[0-9;?]*[A-Za-z]/.exec(text.slice(i));
+      if (match) {
+        if (cell >= start && cell < end) out += match[0];
+        i += match[0].length;
+        continue;
+      }
+    }
+    const ch = String.fromCodePoint(text.codePointAt(i));
+    const cw = charWidth(ch);
+    if (cell >= start && cell < end) out += ch;
+    cell += cw;
+    i += ch.length;
+    if (cell >= end) break;
+  }
+  return out;
+}
+
+/** Draws overlay lines onto a base frame at (x, y). */
+function overlay(base, boxLines, x, y) {
+  const out = base.slice();
+  for (let i = 0; i < boxLines.length; i += 1) {
+    const row = y + i;
+    if (row < 0 || row >= out.length) continue;
+    const line = out[row] || '';
+    const w = boxLines[i].length ? vlen(boxLines[i]) : 0;
+    const left = vpad(vslice(line, 0, x), x);
+    const right = vpad(vslice(line, x + w, vlen(line)), vlen(line) - x - w);
+    out[row] = left + boxLines[i] + right;
+  }
+  return out;
+}
+
+/**
+ * opencode puts rgba(0,0,0,150) over everything behind a dialog. A terminal has no alpha,
+ * so every colour inside the string is scaled towards black instead — the same 40% look,
+ * and the structure of what is behind the dialog stays readable.
+ */
+function dimAnsi(s, factor = 0.4) {
+  const text = String(s);
+  return text.replace(/\x1b\[([0-9;]*)m/g, (whole, codes) => {
+    const parts = codes.split(';').map(Number);
+    const out = [];
+    for (let i = 0; i < parts.length; i += 1) {
+      const c = parts[i];
+      if (c === 1 || c === 2 || c === 4 || c === 7) {
+        out.push(0);
+        continue;
+      }
+      if ((c === 38 || c === 48) && parts[i + 1] === 2) {
+        const [r, g, b] = [parts[i + 2], parts[i + 3], parts[i + 4]].map((v) => Math.round(v * factor));
+        out.push(c, 2, r, g, b);
+        i += 4;
+        continue;
+      }
+      out.push(c);
+    }
+    return `\x1b[${out.join(';')}m`;
+  });
+}
+
+/** overlay + dimmed backdrop */
+function overlayDim(base, boxLines, x, y, paint) {
+  const out = base.slice();
+  for (let i = 0; i < boxLines.length; i += 1) {
+    const row = y + i;
+    if (row < 0 || row >= out.length) continue;
+    const line = out[row] || '';
+    const w = vlen(boxLines[i]);
+    const left = vpad(vslice(line, 0, x), x);
+    const right = vpad(vslice(line, x + w, vlen(line)), vlen(line) - x - w);
+    out[row] = (paint ? paint(left) : dimAnsi(left)) + boxLines[i] + (paint ? paint(right) : dimAnsi(right));
+  }
+  return out;
+}
+
+function spaces(n) {
+  return ' '.repeat(Math.max(0, n));
+}
+
+module.exports = { strip, vlen, vclip, vpad, wrap, box, columns, hline, vslice, overlay, overlayDim, dimAnsi, BOX, charWidth, spaces };

package/src/tui/term.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { stdin, stdout } = require('node:process');
+
+const ENTER_ALT = '\x1b[?1049h';
+const EXIT_ALT = '\x1b[?1049l';
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const SYNC_ON = '\x1b[?2026h';
+const SYNC_OFF = '\x1b[?2026l';
+const CLEAR = '\x1b[2J\x1b[H';
+
+/**
+ * Thin wrapper over the tty: alternate screen, raw mode, resize events and
+ * flicker-free frame writes (synchronised output where the terminal supports it).
+ */
+class Term {
+  constructor({ altScreen = true } = {}) {
+    this.altScreen = altScreen;
+    this.entered = false;
+    this.listeners = { resize: [], key: [], paste: [] };
+    this._onData = this._onData.bind(this);
+    this._onResize = this._onResize.bind(this);
+  }
+
+  get width() {
+    return stdout.columns || 80;
+  }
+
+  get height() {
+    return stdout.rows || 24;
+  }
+
+  enter() {
+    if (this.entered) return;
+    this.entered = true;
+    if (this.altScreen) stdout.write(ENTER_ALT);
+    stdout.write(CLEAR + HIDE_CURSOR);
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    stdin.on('data', this._onData);
+    stdout.on('resize', this._onResize);
+    process.on('exit', () => this.exit());
+  }
+
+  exit() {
+    if (!this.entered) return;
+    this.entered = false;
+    stdin.removeListener('data', this._onData);
+    stdout.removeListener('resize', this._onResize);
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdin.pause();
+    stdout.write(SHOW_CURSOR + (this.altScreen ? EXIT_ALT : '\n'));
+  }
+
+  on(event, fn) {
+    this.listeners[event].push(fn);
+  }
+
+  _onResize() {
+    for (const fn of this.listeners.resize) fn(this.width, this.height);
+  }
+
+  _onData(chunk) {
+    for (const fn of this.listeners.key) fn(chunk);
+  }
+
+  /** Writes a full frame: home the cursor and overwrite every line. */
+  draw(lines) {
+    const height = this.height;
+    const out = [SYNC_ON];
+    out.push('\x1b[H');
+    for (let i = 0; i < height; i += 1) {
+      out.push('\x1b[0m');
+      out.push(lines[i] || '');
+      out.push('\x1b[0m');
+      if (i < height - 1) out.push('\r\n');
+    }
+    out.push(SYNC_OFF);
+    stdout.write(out.join(''));
+  }
+
+  placeCursor(row, col) {
+    stdout.write(`\x1b[${Math.max(1, row)};${Math.max(1, col)}H${SHOW_CURSOR}`);
+  }
+
+  hideCursor() {
+    stdout.write(HIDE_CURSOR);
+  }
+}
+
+module.exports = { Term };