jeo-code 0.1.0 → 0.4.4

package/src/tui/components/welcome.ts

@@ -0,0 +1,162 @@
+import chalk from "chalk";
+import { renderDnaClaw, DNA_CLAW_ART_GRAND } from "./ascii-art";
+import { truncate, isTTY } from "../terminal";
+import { detectColorLevel, ColorLevel } from "./color";
+
+export interface WelcomeData {
+  version: string;
+  model: string;
+  provider?: string;
+  cwd?: string;            // absolute; render ~-shortened
+  thinking?: string;       // e.g. "medium"
+  sessionId?: string;      // render first 8 chars
+  contextFiles?: string[]; // project context file paths (render basenames)
+  recentSessions?: { name: string; timeAgo: string }[];
+  cols?: number;           // default 80
+  /** Gradient phase [0..1) for the DNA Claw symbol — drives the launch sweep animation. */
+  phase?: number;
+  /** Lit-edge painter (top border + left edge); theme accent. Default gray. */
+  accent?: (s: string) => string;
+  /** Shaded-edge painter (bottom border + right edge); dimmed accent. Default dim gray. */
+  accentShadow?: (s: string) => string;
+  unicode?: boolean;       // default true
+  color?: boolean;         // default true
+}
+
+function getVisibleWidth(s: string): number {
+  return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+function padLine(line: string, width: number, align: "left" | "center" | "right" = "left"): string {
+  const vis = getVisibleWidth(line);
+  if (width <= 0 || vis >= width) return line;
+  const total = width - vis;
+  if (align === "right") return " ".repeat(total) + line;
+  if (align === "center") {
+    const left = Math.floor(total / 2);
+    return " ".repeat(left) + line + " ".repeat(total - left);
+  }
+  return line + " ".repeat(total);
+}
+
+/**
+ * The gjc-style hero welcome box ("JEO forge"): one outer box with the version
+ * embedded in the top border and a SINGLE CENTERED column inside — brand line,
+ * tagline, the grand DNA Claw symbol (flowing gradient on capable terminals),
+ * and the model/provider pills. Workspace details and key hints intentionally
+ * live elsewhere (footer/status bar), matching the gjc forge banner.
+ */
+export function renderWelcome(d: WelcomeData): string[] {
+  const cols = d.cols ?? 80;
+  const unicode = d.unicode !== false;
+  const useColor = d.color !== false;
+
+  if (cols < 30) {
+    return [ `jeo v${d.version} · ${d.model}` ];
+  }
+
+  const W = Math.min(100, cols - 2);
+  const inner = W - 2;
+
+  const BOX_UNICODE = { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│" };
+  const BOX_ASCII = { tl: "+", tr: "+", bl: "+", br: "+", h: "-", v: "|" };
+  const g = unicode ? BOX_UNICODE : BOX_ASCII;
+
+  // Depth cue (two-tone borders): top border + left edge are "lit" with the
+  // accent; bottom border + right edge are "shaded" with the dimmed accent.
+  const lit = useColor ? (d.accent ?? chalk.gray) : (s: string) => s;
+  const shadow = useColor ? (d.accentShadow ?? ((s: string) => chalk.dim(chalk.gray(s)))) : (s: string) => s;
+
+  // Title text: ─── jeo v{version} · JEO forge ─── (bold for contrast against the border)
+  const dashStr = g.h.repeat(3);
+  const titleLabel = ` jeo v${d.version} · JEO forge `;
+  const titleHead = `${dashStr}${titleLabel}`;
+  let topBorderLine: string;
+  if (titleHead.length + 2 > inner) {
+    const clipped = titleHead.slice(0, inner);
+    topBorderLine = lit(g.tl + clipped + g.h.repeat(Math.max(0, inner - clipped.length)) + g.tr);
+  } else {
+    const fill = g.h.repeat(inner - titleHead.length);
+    topBorderLine = useColor
+      ? lit(g.tl + dashStr) + chalk.bold(lit(titleLabel)) + lit(fill) + lit(g.tr)
+      : g.tl + titleHead + fill + g.tr;
+  }
+
+  const bottomBorderPlain = g.bl + g.h.repeat(inner) + g.br;
+  const bottomBorderLine = shadow(bottomBorderPlain);
+
+  // Grand symbol when the box is wide enough; compact DNA Claw otherwise.
+  const colorLevel = useColor ? detectColorLevel(process.env, isTTY()) : ColorLevel.None;
+  const grandWidth = Math.max(...DNA_CLAW_ART_GRAND.map(l => l.length));
+  const grand = inner >= grandWidth;
+  const artLines = renderDnaClaw({
+    color: useColor,
+    phase: d.phase ?? 0,
+    unicode,
+    colorLevel,
+    grand,
+    cols: inner,
+  });
+
+  // Single centered hero column (gjc forge layout): breathing room, brand,
+  // tagline, the symbol, then the model/provider pills.
+  const content: string[] = [];
+  content.push("");
+  content.push(useColor ? chalk.bold.cyan("Jeo forge") : "Jeo forge");
+  content.push(useColor ? chalk.dim("evolve · act · prove") : "evolve · act · prove");
+  content.push("");
+  for (const line of artLines) content.push(line);
+  content.push("");
+
+  const modelIcon = unicode ? "◆" : "*";
+  const modelPill = truncate(`[ ${modelIcon} ${d.model} ]`, inner);
+  content.push(useColor ? chalk.cyan(modelPill) : modelPill);
+  if (d.provider) {
+    const providerIcon = unicode ? "◇" : "o";
+    const providerPill = truncate(`[ ${providerIcon} ${d.provider} ]`, inner);
+    content.push(useColor ? chalk.blue(providerPill) : providerPill);
+  }
+  content.push("");
+
+  const leftBorder = lit(g.v);
+  const rightBorder = shadow(g.v);
+  const finalContentLines = content.map(raw => {
+    const line = padLine(truncate(raw, inner), inner, "center");
+    return leftBorder + line + rightBorder;
+  });
+
+  return [topBorderLine, ...finalContentLines, bottomBorderLine];
+}
+
+/**
+ * Launch animation: sweep the DNA Claw's gradient through `cycles` FULL palette
+ * cycles by re-printing the welcome box in place (cursor-up rewrites, same row
+ * count every frame). The loop is SEAMLESS — the phase wraps exactly at each
+ * cycle boundary with a constant frame delay, so consecutive cycles join with
+ * no pause or color jump — and every repaint is wrapped in a DECSET 2026
+ * synchronized update so frames land atomically (no tearing/flicker on slow
+ * terminals). The FINAL frame is phase 0 — byte-identical to the static
+ * `renderWelcome` — so the resting banner matches non-animated output exactly.
+ * `write`/`sleep` are injectable for tests; callers gate on TTY + truecolor.
+ */
+export async function playWelcomeSweep(
+  d: WelcomeData,
+  opts: { write?: (s: string) => void; sleep?: (ms: number) => Promise<unknown>; frames?: number; delayMs?: number; cycles?: number } = {},
+): Promise<void> {
+  const write = opts.write ?? ((s: string) => process.stdout.write(s));
+  const sleep = opts.sleep ?? ((ms: number) => new Promise(r => setTimeout(r, ms)));
+  const frames = Math.max(1, Math.trunc(opts.frames ?? 10));
+  const cycles = Math.max(1, Math.trunc(opts.cycles ?? 2));
+  const delay = opts.delayMs ?? 50;
+  const total = frames * cycles;
+  let lineCount = 0;
+  for (let f = 0; f <= total; f++) {
+    const phase = (f % frames) / frames; // wraps each cycle; f === total → 0 (the static banner)
+    const lines = renderWelcome({ ...d, phase });
+    const rewind = f > 0 ? `\x1b[${lineCount}A` : "";
+    // BSU/ESU: the whole repaint (rewind + every row) applies atomically.
+    write(`\x1b[?2026h${rewind}${lines.map(l => `${l}\x1b[K`).join("\n")}\n\x1b[?2026l`);
+    lineCount = lines.length;
+    if (f < total && delay > 0) await sleep(delay);
+  }
+}

package/src/tui/components/width.ts

@@ -0,0 +1,163 @@
+/**
+ * ANSI + Unicode display-width helpers (consensus-seed P2.B9).
+ *
+ * Terminals render some code points two columns wide (CJK ideographs, Hangul,
+ * fullwidth forms, most emoji) and some zero (combining marks, ZWJ, variation
+ * selectors). Counting `string.length` — as the old ad-hoc `truncate` did —
+ * overflows or under-fills any line containing them. These helpers count by
+ * DISPLAY width, treat tabs as advancing to the next 8-col stop, and copy SGR
+ * color escapes verbatim (never counting them) so colored/CJK lines truncate and
+ * wrap without tearing an escape or miscounting a wide glyph.
+ */
+
+const TAB_STOP = 8;
+// Sticky SGR matcher: scan a heavily color-escaped line in O(n) without slicing.
+const SGR = /\x1b\[[0-9;]*m/y;
+
+/**
+ * Display columns for a single code point. 0 for combining/zero-width, 2 for
+ * East-Asian Wide/Fullwidth and emoji, 1 otherwise. Ranges follow the common
+ * wcwidth/East_Asian_Width tables (not exhaustive, but covers the cases a coding
+ * TUI actually shows: Hangul, CJK, kana, fullwidth ASCII, emoji blocks).
+ */
+export function charWidth(cp: number): number {
+  if (cp === 0) return 0;
+  // C0/C1 control characters have no width here (callers strip/By handle them).
+  if (cp < 32 || (cp >= 0x7f && cp < 0xa0)) return 0;
+  // Zero-width: combining marks, ZWSP/ZWNJ/ZWJ, variation selectors, BOM.
+  if (
+    (cp >= 0x0300 && cp <= 0x036f) || // combining diacritical marks
+    (cp >= 0x200b && cp <= 0x200f) || // zero-width space..RLM
+    (cp >= 0xfe00 && cp <= 0xfe0f) || // variation selectors
+    (cp >= 0x1ab0 && cp <= 0x1aff) || // combining diacritical marks extended
+    (cp >= 0x1dc0 && cp <= 0x1dff) || // combining diacritical marks supplement
+    (cp >= 0x20d0 && cp <= 0x20ff) || // combining marks for symbols
+    cp === 0xfeff
+  ) {
+    return 0;
+  }
+  // Wide (2 columns).
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals .. Kangxi
+    (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana, Katakana, CJK symbols
+    (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Ext A
+    (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified
+    (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+    (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compatibility forms
+    (cp >= 0xff00 && cp <= 0xff60) || // fullwidth forms
+    (cp >= 0xffe0 && cp <= 0xffe6) || // fullwidth signs
+    (cp >= 0x1f300 && cp <= 0x1faff) || // emoji & pictographs (incl. supplemental/symbols-extended)
+    (cp >= 0x1f000 && cp <= 0x1f0ff) || // mahjong/dominoes/playing cards
+    (cp >= 0x20000 && cp <= 0x3fffd) // CJK Ext B+ (supplementary ideographic planes)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+/**
+ * Visible display width of a string: SGR escapes count 0, tabs advance to the
+ * next 8-col stop, wide glyphs count 2. Iterates by code point (surrogate-safe).
+ */
+export function visibleWidth(s: string): number {
+  if (!s) return 0;
+  let w = 0;
+  let i = 0;
+  while (i < s.length) {
+    if (s[i] === "\x1b") {
+      SGR.lastIndex = i;
+      const m = SGR.exec(s);
+      if (m) {
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (s[i] === "\t") {
+      w += TAB_STOP - (w % TAB_STOP);
+      i += 1;
+      continue;
+    }
+    const cp = s.codePointAt(i)!;
+    w += charWidth(cp);
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return w;
+}
+
+/**
+ * Truncate a string to at most `cols` DISPLAY columns. SGR escapes are copied
+ * verbatim (free); a wide glyph that would straddle the boundary is dropped
+ * whole (never half-rendered). If a color was active at the cut, a reset is
+ * appended so trailing frame content is not tinted.
+ */
+export function truncateToWidth(s: string, cols: number): string {
+  const limit = Math.max(0, cols);
+  if (limit === 0) return "";
+  // Fast path: no escapes, no wide chars, no tabs → plain slice by length.
+  if (!s.includes("\x1b") && !/[\t\u0300-\uffff]/.test(s) && !/[\u{10000}-\u{10ffff}]/u.test(s)) {
+    return s.length <= limit ? s : s.slice(0, limit);
+  }
+  let out = "";
+  let w = 0;
+  let sawEscape = false;
+  let i = 0;
+  while (i < s.length) {
+    if (s[i] === "\x1b") {
+      SGR.lastIndex = i;
+      const m = SGR.exec(s);
+      if (m) {
+        out += m[0];
+        sawEscape = true;
+        i += m[0].length;
+        continue;
+      }
+    }
+    let cw: number;
+    let chunk: string;
+    if (s[i] === "\t") {
+      cw = TAB_STOP - (w % TAB_STOP);
+      chunk = "\t";
+    } else {
+      const cp = s.codePointAt(i)!;
+      cw = charWidth(cp);
+      chunk = cp > 0xffff ? s.slice(i, i + 2) : s[i]!;
+    }
+    if (w + cw > limit) break;
+    out += chunk;
+    w += cw;
+    i += chunk.length;
+  }
+  if (i < s.length && sawEscape && !out.endsWith("\x1b[0m")) out += "\x1b[0m";
+  return out;
+}
+
+/**
+ * Hard-wrap text to `cols` display columns, breaking long words and preserving
+ * existing newlines. SGR-aware (escapes don't consume width). Returns the wrapped
+ * lines. Used by markdown/table rendering where alignment must be column-correct.
+ */
+export function wrapTextWithAnsi(text: string, cols: number): string[] {
+  const width = Math.max(1, cols);
+  const out: string[] = [];
+  for (const rawLine of text.split("\n")) {
+    if (visibleWidth(rawLine) <= width) {
+      out.push(rawLine);
+      continue;
+    }
+    let rest = rawLine;
+    while (visibleWidth(rest) > width) {
+      const head = truncateToWidth(rest, width);
+      // Advance past exactly the consumed substring (head may carry a trailing reset).
+      const consumed = head.endsWith("\x1b[0m") && !rest.endsWith("\x1b[0m")
+        ? head.slice(0, -"\x1b[0m".length)
+        : head;
+      out.push(head);
+      rest = rest.slice(consumed.length);
+    }
+    if (rest.length > 0) out.push(rest);
+  }
+  return out;
+}

package/src/tui/monitoring/AGENTS.md

@@ -0,0 +1,31 @@
+<!-- Parent: ../../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# monitoring
+
+## Purpose
+Specialized HUD views and sovereign monitoring interfaces.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `hud-view.ts` | Real-time evolution tracking and self-analysis visibility |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Ensure compatibility with the differential renderer.
+
+### Testing Requirements
+- Unit tests with mock state.
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/tui/monitoring/hud-view.ts

@@ -0,0 +1,55 @@
+import chalk from "chalk";
+import { renderHud, type JeoPhase } from "../components/hud";
+import { 
+  evolutionTrack, 
+  stageIndexForStep, 
+  getEvolutionStatusMessage,
+  stageProgressRatio,
+  meterGlyphsFor,
+  EVOLUTION_STAGE_COLORS
+} from "../components/evolution";
+
+export interface MonitorState {
+  phase: JeoPhase;
+  step: number;
+  maxSteps: number;
+  tickCount: number;
+  analysisReport?: string;
+}
+
+export function renderMonitorView(state: MonitorState): string {
+  const unicode = true;
+  const stage = stageIndexForStep(state.step, state.maxSteps);
+  const hud = renderHud(state.phase, { unicode, color: true });
+  const evo = evolutionTrack(stage, { color: true, unicode, ratio: state.step / state.maxSteps });
+  const statusMsg = getEvolutionStatusMessage(state.step, state.maxSteps, state.tickCount);
+  
+  // Progress Bar / Meter
+  const ratio = Math.max(0, Math.min(1, state.step / state.maxSteps));
+  const barWidth = 30;
+  const filledWidth = Math.round(ratio * barWidth);
+  const glyphs = meterGlyphsFor(stage, unicode);
+  const bar = glyphs.color(glyphs.fill.repeat(filledWidth)) + chalk.dim(glyphs.empty.repeat(barWidth - filledWidth));
+  const percentage = (ratio * 100).toFixed(1) + "%";
+
+  let output = "";
+  output += chalk.bold.cyan("┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓") + "\n";
+  output += chalk.bold.cyan("┃") + " " + chalk.bold.yellow("ooo ralph") + chalk.bold(" Sovereign Monitoring HUD") + " ".repeat(25) + chalk.bold.cyan("┃") + "\n";
+  output += chalk.bold.cyan("┠──────────────────────────────────────────────────────────────┨") + "\n";
+  output += chalk.bold.cyan("┃") + " " + chalk.bold("PHASE:") + " " + hud.padEnd(50) + " ".repeat(4) + chalk.bold.cyan("┃") + "\n";
+  output += chalk.bold.cyan("┃") + " " + chalk.bold("EVO  :") + " " + evo.padEnd(50) + " ".repeat(4) + chalk.bold.cyan("┃") + "\n";
+  output += chalk.bold.cyan("┃") + " " + chalk.bold("PROG :") + " " + bar.padEnd(50) + " " + chalk.bold(percentage).padStart(6) + chalk.bold.cyan("┃") + "\n";
+  output += chalk.bold.cyan("┠──────────────────────────────────────────────────────────────┨") + "\n";
+  output += chalk.bold.cyan("┃") + " " + chalk.italic.dim("> " + statusMsg).padEnd(60) + " " + chalk.bold.cyan("┃") + "\n";
+  
+  if (state.analysisReport) {
+    output += chalk.bold.cyan("┠──────────────────────────────────────────────────────────────┨") + "\n";
+    const lines = state.analysisReport.split("\n").slice(0, 5);
+    for (const line of lines) {
+      output += chalk.bold.cyan("┃") + " " + chalk.yellow(line.substring(0, 58).padEnd(58)) + " " + chalk.bold.cyan("┃") + "\n";
+    }
+  }
+  output += chalk.bold.cyan("┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛") + "\n";
+  
+  return output;
+}

package/src/tui/renderer.ts

@@ -2,15 +2,45 @@ import { cursorDown, cursorUp, toColumn, clearLine, clearToEnd, size, truncate }
 
 export type Writer = (s: string) => void;
 
+export interface RendererOptions {
+  /** Inline (main-buffer) mode: before painting a frame TALLER than the previous one,
+   *  reserve the missing rows with real newlines. Cursor-down can't scroll past the
+   *  bottom margin, so without reservation a frame anchored near the bottom of the
+   *  viewport would collapse onto its last rows. The newlines DO scroll, pushing prior
+   *  content (the progress ledger) up into normal scrollback — which is exactly what
+   *  keeps tmux / terminal mouse-wheel history working mid-turn.
+   *  Caller invariant: frames must be sliced to the viewport height. A frame taller
+   *  than the viewport is NOT reserved (cursor-up would clamp at the top margin and
+   *  mis-anchor the repaint), so the diff degrades to in-place painting instead. */
+  reserve?: boolean;
+}
+
+// DECSET 2026 "synchronized update": the terminal buffers everything between BSU and
+// ESU and presents it atomically, so the insertAbove flow (EL-overwrite of the first
+// row(s) + full repaint below) never flashes an intermediate half-painted frame.
+// Unsupported terminals ignore the
+// sequences; supporting ones (incl. tmux ≥3.4) also time the update out (~150ms) if
+// ESU never arrives, so a crash mid-update cannot freeze the screen.
+const BEGIN_SYNC = "\x1b[?2026h";
+const END_SYNC = "\x1b[?2026l";
+
 export class Renderer {
   private write: Writer;
   private cols: () => number;
   private prev: string[] = [];
   private prevCols?: number;
+  private readonly reserve: boolean;
+  // Stale rows left on screen by the previous frame after insertAbove() dropped the
+  // baseline; the next render() must EL-clear any of them beyond the new frame.
+  private coverRows = 0;
+  // True between an insertAbove() (which opens a synchronized update) and the next
+  // render()/clear() (which closes it after the repaint is fully written).
+  private syncOpen = false;
 
-  constructor(write?: Writer, cols?: () => number) {
+  constructor(write?: Writer, cols?: () => number, opts?: RendererOptions) {
     this.write = write || ((s: string) => process.stdout.write(s));
     this.cols = cols || (() => size().cols);
+    this.reserve = opts?.reserve ?? false;
   }
 
   render(lines: string[]): void {
@@ -21,10 +51,20 @@ export class Renderer {
     this.prevCols = currentCols;
 
     const next = lines.map(line => truncate(line, currentCols));
-    const maxLen = Math.max(this.prev.length, next.length);
+    const maxLen = Math.max(this.prev.length, next.length, this.coverRows);
+    this.coverRows = 0;
     let cursorRow = 0;
     let out = "";
 
+    if (this.reserve && next.length > this.prev.length && next.length <= Math.max(1, size().rows)) {
+      // The cursor rests on the frame's first row (the anchor). Walk to the last
+      // currently-occupied row, emit one newline per missing row (scrolling the
+      // viewport when at the bottom margin), then hop back up to the — possibly
+      // shifted — anchor so the diff below paints at stable relative positions.
+      const have = Math.max(this.prev.length, 1);
+      out += cursorDown(have - 1) + "\n".repeat(next.length - have) + cursorUp(next.length - 1) + toColumn(1);
+    }
+
     for (let i = 0; i < maxLen; i++) {
       if (i < next.length) {
         if (next[i] !== this.prev[i]) {
@@ -52,6 +92,14 @@ export class Renderer {
     }
     out += toColumn(1);
 
+    // Close the synchronized update opened by insertAbove() now that the full
+    // repaint is in the same buffered stream — the terminal presents the overwritten
+    // first row(s), the flushed ledger line, and the repainted frame as ONE atomic update.
+    if (this.syncOpen) {
+      out += END_SYNC;
+      this.syncOpen = false;
+    }
+
     if (out.length > 0) {
       this.write(out);
     }
@@ -59,8 +107,69 @@ export class Renderer {
     this.prev = next;
   }
 
+  /** Flush static text into normal scrollback ABOVE the live frame: overwrite the
+   *  frame's first row(s) with the text (caller terminates it with "\n") and drop the
+   *  differential baseline so the next render() repaints the full frame below the
+   *  newly emitted line(s). The follow-up render's row reservation scrolls the text
+   *  up into history, where tmux / terminal mouse-wheel can reach it mid-turn.
+   *  Erases with per-line EL (\x1b[2K), NEVER clear-to-end: tmux pushes ED-erased
+   *  rows into scrollback, so an ED here would flood history with one full frame
+   *  copy per flush (the bug this replaced). Rows the new frame doesn't cover are
+   *  EL-cleared by the next render() via coverRows.
+   *  Opens a DECSET 2026 synchronized update that the next render()/clear() closes,
+   *  so the overwrite → flush → repaint triplet never flashes intermediate states.
+   *  Inline-mode only by convention — the alt screen has no scrollback to flush into. */
+  insertAbove(text: string): void {
+    this.syncOpen = true;
+    const rows = text.split("\n");
+    // Rows the body actually writes (the trailing "" from the final "\n" emits nothing).
+    const written = rows.length - (rows[rows.length - 1] === "" ? 1 : 0);
+    const body = rows
+      .map((line, i, arr) => (i === arr.length - 1 && line === "" ? "" : toColumn(1) + clearLine() + line))
+      .join("\n");
+    let out = BEGIN_SYNC + body;
+    // Eagerly EL-clear the old frame rows the inserted block did NOT cover, then hop
+    // back to the row right below the insert (where the next render() anchors).
+    // The geometry is provably safe HERE: when stale > 0 the body write never hit
+    // the bottom margin (the old frame fit on screen and the insert is shorter), so
+    // every stale row exists and cursor-down cannot clamp. Deferring this clear to
+    // the next render() via coverRows walked PAST the bottom margin, where the
+    // clamped cursor-down desynced the row bookkeeping — each subsequent frame then
+    // painted one row higher, devouring the flushed scrollback content above (the
+    // "truncated card" corruption).
+    const stale = this.prev.length - written;
+    if (stale > 0) {
+      for (let i = 0; i < stale; i++) {
+        out += toColumn(1) + clearLine() + (i < stale - 1 ? cursorDown(1) : "");
+      }
+      out += (stale > 1 ? cursorUp(stale - 1) : "") + toColumn(1);
+    }
+    this.write(out);
+    this.prev = [];
+  }
+
+  /** Clear the live frame. Inline (reserve) mode walks the known frame rows with
+   *  per-line EL — clear-to-end would make tmux push the erased frame into
+   *  scrollback (see insertAbove). Alt-screen/non-TTY renderers keep the cheaper
+   *  ED clear: the alt screen has no history and pipes have no screen. */
   clear(): void {
-    this.write(toColumn(1) + clearToEnd());
+    let out: string;
+    if (this.reserve) {
+      const rows = Math.max(this.prev.length, this.coverRows);
+      out = toColumn(1);
+      for (let i = 0; i < rows; i++) {
+        out += (i > 0 ? cursorDown(1) : "") + toColumn(1) + clearLine();
+      }
+      if (rows > 1) out += cursorUp(rows - 1) + toColumn(1);
+    } else {
+      out = toColumn(1) + clearToEnd();
+    }
+    if (this.syncOpen) {
+      out += END_SYNC;
+      this.syncOpen = false;
+    }
+    this.coverRows = 0;
+    this.write(out);
     this.prev = [];
   }
 

package/src/tui/terminal.ts

@@ -1,3 +1,5 @@
+import { truncateToWidth } from "./components/width";
+
 export const ESC = "\x1b[";
 
 export function cursorUp(n: number): string {
@@ -28,6 +30,37 @@ export function showCursor(): string {
   return `${ESC}?25h`;
 }
 
+/**
+ * Defensively DISABLE every xterm mouse-tracking mode + coordinate encoding.
+ * jeo never enables these itself, but a previous program that crashed (or a
+ * stale tmux pane) can leave them ON — the terminal then reports clicks/motion
+ * as escape sequences from the very first prompt, which reads as "the mouse
+ * starts out clicked/held" and sprays `[<0;…M`-style garbage into input.
+ * Emitting the `l` (reset) forms is harmless when the modes are already off.
+ *   ?9 X10 · ?1000 normal · ?1002 button-motion · ?1003 any-motion
+ *   ?1005 UTF-8 · ?1006 SGR · ?1015 urxvt · ?1016 SGR-pixel
+ */
+export function resetMouseTracking(): string {
+  return `${ESC}?9l${ESC}?1000l${ESC}?1002l${ESC}?1003l${ESC}?1005l${ESC}?1006l${ESC}?1015l${ESC}?1016l`;
+}
+
+/** Enter the alternate screen buffer (xterm `?1049h`): a separate, scrollback-free
+ *  screen. Used for the transient live-turn UI so terminal scroll (mouse wheel) can't
+ *  fight the in-place repaint — and the main buffer / scrollback is left untouched.
+ *  Also disables "alternate scroll" (`?1007l`): with it on, terminals (and tmux)
+ *  translate mouse-wheel motion in the alt screen into Up/Down arrow key sequences,
+ *  which would otherwise leak into readline's buffer and corrupt the next prompt. */
+export function enterAltScreen(): string {
+  return `${ESC}?1049h${ESC}?1007l`;
+}
+
+/** Leave the alternate screen buffer (`?1049l`), restoring the main buffer + scrollback.
+ *  Re-enables alternate scroll (`?1007h`, the common terminal default) so other
+ *  full-screen apps (vim/less) keep their wheel behavior after jeo exits the turn. */
+export function leaveAltScreen(): string {
+  return `${ESC}?1007h${ESC}?1049l`;
+}
+
 export function size(): { cols: number; rows: number } {
   return {
     cols: process.stdout.columns || 80,
@@ -40,39 +73,13 @@ export function isTTY(): boolean {
 }
 
 /**
- * Truncate a line to `cols` *visible* columns. SGR color escapes are copied
- * verbatim and do NOT count toward the width, so a colored line is never cut
- * mid-escape (which would spill raw `\x1b[…` bytes onto the screen). If the line
- * is cut while a color is active, a reset (`\x1b[0m`) is appended so trailing
- * frame content is not tinted by a dangling color.
+ * Truncate a line to `cols` *visible* DISPLAY columns. Delegates to the
+ * width-aware `truncateToWidth` (consensus-seed P2.B9): SGR escapes are copied
+ * verbatim (counted 0), CJK/emoji glyphs count 2 so a wide-char line no longer
+ * overflows the terminal width, tabs advance to the next stop, and a reset is
+ * appended if the cut lands mid-color. The plain-ASCII fast path is preserved
+ * inside `truncateToWidth`, so hot-path render cost is unchanged for ASCII frames.
  */
 export function truncate(line: string, cols: number): string {
-  const limit = Math.max(0, cols);
-  // Fast path: no escapes → plain slice by length.
-  if (!line.includes("\x1b")) {
-    return line.length <= limit ? line : line.slice(0, limit);
-  }
-  let out = "";
-  let visible = 0;
-  let sawEscape = false;
-  let i = 0;
-  while (i < line.length) {
-    if (line[i] === "\x1b") {
-      const m = /^\x1b\[[0-9;]*m/.exec(line.slice(i));
-      if (m) {
-        out += m[0];
-        sawEscape = true;
-        i += m[0].length;
-        continue;
-      }
-    }
-    if (visible >= limit) break;
-    out += line[i];
-    visible++;
-    i++;
-  }
-  if (i < line.length && sawEscape && !out.endsWith("\x1b[0m")) {
-    out += "\x1b[0m";
-  }
-  return out;
+  return truncateToWidth(line, cols);
 }