claude-cup 0.2.0

package/src/tui.js

@@ -0,0 +1,845 @@
+// Terminal UI - drawn in Claude Code's own terminal design language:
+// foreground glyphs only (no painted backgrounds, adapts to any theme),
+// rounded hairline borders, dim/bold hierarchy, mono uppercase eyebrows,
+// the ✻ spark, dot separators, and the clay accent spent sparingly.
+// Works in any terminal, including the desktop app's pane (Ctrl+`).
+
+const CLAY = [217, 119, 87];
+const EMBER = [198, 97, 63];
+const KRAFT = [212, 162, 127];
+const BURNT = [157, 60, 40];
+const IVORY = [250, 249, 245];
+const CLOUD = [135, 134, 127];
+
+export const TOKEN_COLORS = {
+  read: [106, 155, 204], // sky
+  edit: [120, 140, 93], // olive
+  terminal: [212, 162, 127], // kraft
+  web: [196, 102, 134], // fig
+  agent: [203, 202, 219], // heather
+  ai: [217, 119, 87], // clay
+  other: [176, 174, 165], // cloud medium
+};
+
+const SPARK_FRAMES = ['\u2722', '\u2733', '\u2736', '\u273b']; // ✢ ✳ ✶ ✻ - Claude Code's spinner
+const SPARK_IDLE = '\u273b'; // ✻
+
+export function liquidColorFor(pct) {
+  const stops = [
+    { p: 0, c: KRAFT },
+    { p: 55, c: CLAY },
+    { p: 85, c: EMBER },
+    { p: 100, c: BURNT },
+  ];
+  const p = Math.max(0, Math.min(100, pct));
+  for (let i = 1; i < stops.length; i++) {
+    if (p <= stops[i].p) {
+      const a = stops[i - 1];
+      const b = stops[i];
+      const t = (p - a.p) / (b.p - a.p || 1);
+      return a.c.map((v, k) => Math.round(v + (b.c[k] - v) * t));
+    }
+  }
+  return BURNT;
+}
+
+const mix = (a, b, t) => a.map((v, i) => Math.round(v + (b[i] - v) * t));
+const fmt = (n) => (n >= 1e6 ? (n / 1e6).toFixed(2) + 'M' : n >= 1e3 ? (n / 1e3).toFixed(1) + 'k' : String(n ?? 0));
+
+function countdown(resetsAt) {
+  if (!resetsAt) return '';
+  const ms = Date.parse(resetsAt) - Date.now();
+  if (!Number.isFinite(ms) || ms <= 0) return 'resetting';
+  const h = Math.floor(ms / 3600000);
+  const m = Math.floor((ms % 3600000) / 60000);
+  if (h >= 48) return `${Math.floor(h / 24)}d ${h % 24}h`;
+  return h > 0 ? `${h}h ${m}m` : `${m}m`;
+}
+
+// ---- color emission with 256-color fallback ----
+function colorSeq(plane, c, mode) {
+  if (mode === 24) return `${plane};2;${c[0]};${c[1]};${c[2]}`;
+  if (c[0] === c[1] && c[1] === c[2]) {
+    const g = 232 + Math.max(0, Math.min(23, Math.round(((c[0] - 8) / 247) * 23)));
+    return `${plane};5;${g}`;
+  }
+  const q = (v) => Math.round((v / 255) * 5);
+  return `${plane};5;${16 + 36 * q(c[0]) + 6 * q(c[1]) + q(c[2])}`;
+}
+const fgSeq = (c, mode) => colorSeq(38, c, mode);
+const bgSeq = (c, mode) => colorSeq(48, c, mode);
+
+class Grid {
+  constructor(cols, rows, colorMode = 24) {
+    this.cols = cols;
+    this.rows = rows;
+    this.mode = colorMode;
+    this.cells = Array.from({ length: rows }, () => Array.from({ length: cols }, () => ({ ch: ' ' })));
+  }
+
+  put(x, y, ch, attr = {}) {
+    if (x < 0 || y < 0 || x >= this.cols || y >= this.rows) return;
+    this.cells[y][x] = { ch, ...attr };
+  }
+
+  text(x, y, str, attr = {}) {
+    for (let i = 0; i < str.length; i++) this.put(x + i, y, str[i], attr);
+  }
+
+  textRight(y, str, attr = {}) {
+    this.text(this.cols - 1 - str.length, y, str, attr);
+  }
+
+  toString() {
+    const out = [];
+    for (const row of this.cells) {
+      let line = '';
+      let prev = null;
+      for (const c of row) {
+        const key = `${c.fg ? c.fg.join() : ''}|${c.bg ? c.bg.join() : ''}|${c.bold ? 1 : 0}|${c.dim ? 1 : 0}`;
+        if (key !== prev) {
+          line += '\x1b[0m';
+          if (c.bold) line += '\x1b[1m';
+          if (c.dim) line += '\x1b[2m';
+          if (c.fg) line += `\x1b[${fgSeq(c.fg, this.mode)}m`;
+          if (c.bg) line += `\x1b[${bgSeq(c.bg, this.mode)}m`;
+          prev = key;
+        }
+        line += c.ch;
+      }
+      out.push(line.replace(/ +$/, '') + '\x1b[0m');
+    }
+    return out.join('\n');
+  }
+}
+
+// ---- trophy geometry (character cells) ----
+// The vessel is the World Cup trophy: a big round globe (about 40% of the
+// height, like the real one), two figures tapering into a short stem, and a
+// two-step pedestal. Interior columns are 0..19; each row has its own
+// interior span because the trophy's width varies with height.
+// Total height H = bodyH + 5 rows:
+//   rel 0            globe cap (arc)
+//   rel 1..G-1       globe (bulges to 16 cols at its equator)
+//   rel G..G+1       figures tapering under the globe
+//   rel G+2..H-5     stem
+//   rel H-4          pedestal step (glass, not fillable)
+//   rel H-3          pedestal tier 1
+//   rel H-2          pedestal tier 2 (engraved)
+//   rel H-1          floor
+const INNER_W = 20;
+
+export function bodyHeightFor(rows) {
+  return Math.max(8, Math.min(16, rows - 10));
+}
+
+function profileFor(bodyH) {
+  const H = bodyH + 5;
+  const G = Math.max(4, Math.round(H * 0.38)); // cap + globe rows
+  return { H, G, slabRel: H - 4, baseA: H - 3, baseB: H - 2 };
+}
+
+function globeWidth(rel, G) {
+  const f = rel / (G - 1);
+  return 8 + 2 * Math.round(4 * Math.sin(Math.PI * Math.min(1, f)));
+}
+
+export function spanFor(rel, bodyH) {
+  const { H, G } = profileFor(bodyH);
+  if (rel >= 1 && rel <= G - 1) {
+    const w = globeWidth(rel, G);
+    const lo = (INNER_W - w) / 2;
+    return { lo, hi: lo + w - 1 };
+  }
+  if (rel >= G && rel <= H - 4) return { lo: 7, hi: 12 }; // figures + stem (+ step pass-through)
+  if (rel === H - 3) return { lo: 4, hi: 15 }; // pedestal tier 1
+  if (rel === H - 2) return { lo: 3, hi: 16 }; // pedestal tier 2
+  return { lo: 7, hi: 12 };
+}
+
+/** Fillable rows (rel indices, top to bottom). The slab row H-4 is glass. */
+export function interiorRowsFor(bodyH) {
+  const H = bodyH + 5;
+  const rows = [1, 2, 3];
+  for (let r = 4; r <= H - 5; r++) rows.push(r);
+  rows.push(H - 3, H - 2);
+  return rows;
+}
+
+/** Rows flooded for a fill % - any real usage shows at least a puddle. */
+export function fillRowsFor(bodyH, fill) {
+  const n = interiorRowsFor(bodyH).length;
+  const pct = Math.max(0, Math.min(100, fill));
+  return Math.max(pct >= 0.5 ? 1 : 0, Math.round((pct / 100) * n));
+}
+
+/** Top flooded row (rel index) for a fill %, or null when empty. */
+export function surfaceRelFor(bodyH, fill) {
+  const interior = interiorRowsFor(bodyH);
+  const fillRows = fillRowsFor(bodyH, fill);
+  return fillRows > 0 ? interior[interior.length - fillRows] : null;
+}
+
+// Clawd, Claude Code's mascot - pixel replica of the welcome-screen art.
+// Painted with cell BACKGROUNDS (like Claude Code does) so the body is one
+// seamless clay shape with no gaps between rows, and the eyes are true black.
+const INK = [20, 20, 19];
+
+// pose = {} draws Clawd exactly as the static art. Optional fields animate
+// limbs within the mascot's own 5 rows only (never the legend row above, so
+// nothing in the UI is disturbed). The two eyes are always kept.
+//   shiftX    horizontal body sway / lean (dribble, header, goal wiggle)
+//   legPhase  0|1 alternate leg columns (tippy-tap)
+//   kick      1 = extend the right foot toward the ball
+//   armTwitch raise the side arms a row (juggle)
+//   armsUp    raise both arms up-and-out (goal celebration)
+function drawMascot(g, x, y, pose = {}) {
+  const body = { bg: CLAY };
+  const eye = { bg: INK };
+  const px = x + (pose.shiftX || 0);
+  const cell = (cx, cy, attr = body) => g.put(px + cx, y + cy, ' ', attr);
+
+  cell(3, 0); // nubs
+  cell(9, 0);
+  for (let i = 1; i <= 11; i++) cell(i, 1); // body top
+  for (let i = 1; i <= 11; i++) cell(i, 2, i === 3 || i === 8 ? eye : body); // eyes row
+  for (let i = 0; i <= 12; i++) cell(i, 3); // body bottom + side arms
+  const legs = pose.legPhase === 1 ? [3, 5, 9, 11] : [2, 5, 8, 11];
+  for (const lx of legs) cell(lx, 4);
+
+  if (pose.armsUp) {
+    cell(0, 2);
+    cell(0, 1);
+    cell(12, 2);
+    cell(12, 1);
+  }
+  if (pose.armTwitch) {
+    cell(0, 2);
+    cell(12, 2);
+  }
+  if (pose.kick) {
+    cell(13, 3);
+    cell(13, 4);
+  }
+}
+
+// ---- football animations for the mascot ----
+export const MASCOT_ANIMS = ['kick', 'juggle', 'header', 'dribble', 'goal'];
+export const ANIM_FRAMES = { kick: 16, juggle: 20, header: 16, dribble: 20, goal: 18 };
+const CONFETTI = [
+  [106, 155, 204], // sky
+  [120, 140, 93], // olive
+  [196, 102, 134], // fig
+  [203, 202, 219], // heather
+  [217, 119, 87], // clay
+];
+
+const lerp = (a, b, t) => Math.round(a + (b - a) * t);
+
+/** Pick a random animation that isn't the one we just played. */
+export function pickAnimation(last, rng = Math.random) {
+  const choices = MASCOT_ANIMS.filter((a) => a !== last);
+  return choices[Math.floor(rng() * choices.length)] || MASCOT_ANIMS[0];
+}
+
+/** Idle gap before the next animation: 5-15 seconds. */
+export function nextAnimDelay(rng = Math.random) {
+  return 5000 + Math.floor(rng() * 10000);
+}
+
+/**
+ * Deterministic per-frame plan for an animation. Pure: only depends on the
+ * animation name/frame and the mascot anchor. Returns the mascot pose plus
+ * the ball, trail, confetti and goal flag for drawFootball to render.
+ * Everything stays inside the mascot's own rows (my..my+4) so the legend
+ * row above and the footer below are never touched.
+ * mx,my = mascot top-left; cols = grid width (for right-edge exits).
+ */
+export function footballScene(anim, mx, my, cols) {
+  const f = anim.frame;
+  const out = { pose: {}, ball: null, trail: [], confetti: [], goal: false };
+  const right = cols - 3;
+
+  if (anim.name === 'kick') {
+    // ball rolls in along the ground, mascot strikes it, it rockets out right
+    if (f <= 7) {
+      out.ball = { x: lerp(right, mx + 14, f / 7), y: my + 3 };
+    } else if (f === 8) {
+      out.ball = { x: mx + 14, y: my + 3 };
+      out.pose = { kick: 1 };
+    } else {
+      const t = (f - 9) / 6;
+      const bx = lerp(mx + 15, cols + 8, t);
+      const by = my + 3 - Math.min(2, Math.round(t * 2)); // lofts from my+3 up to my+1
+      out.ball = { x: bx, y: by };
+      out.trail = [{ x: bx - 2, y: by + 1 }, { x: bx - 4, y: by + 1 }];
+      out.pose = { kick: f <= 10 ? 1 : 0 };
+    }
+  } else if (anim.name === 'juggle') {
+    // keepie-uppies: ball hops foot -> belly -> forehead -> belly (skips the
+    // eyes row and stays in the gap between the nubs, so the face stays clear)
+    const heights = [my + 4, my + 3, my + 1, my + 3];
+    const by = heights[f % 4];
+    out.ball = { x: mx + 6, y: by };
+    out.pose = { armTwitch: by <= my + 1 ? 1 : 0, legPhase: f % 2 };
+  } else if (anim.name === 'header') {
+    // ball flies in at head height, mascot leans into it, it bounces out right
+    if (f <= 7) {
+      out.ball = { x: lerp(cols + 4, mx + 7, f / 7), y: my };
+      out.pose = { shiftX: f >= 5 ? 1 : 0 };
+    } else if (f === 8) {
+      out.ball = { x: mx + 6, y: my };
+    } else {
+      const t = (f - 9) / 6;
+      const bx = lerp(mx + 7, cols + 6, t);
+      out.ball = { x: bx, y: my };
+      out.trail = [{ x: bx - 2, y: my + 1 }];
+    }
+  } else if (anim.name === 'dribble') {
+    // close control: ball weaves at the feet while the body sways and steps
+    const u = Math.sin((f / 20) * Math.PI * 4) * 0.5 + 0.5;
+    out.ball = { x: mx + 1 + Math.round(u * 10), y: my + 4 };
+    out.pose = { shiftX: Math.round(Math.sin((f / 20) * Math.PI * 2)), legPhase: Math.floor(f / 2) % 2 };
+  } else if (anim.name === 'goal') {
+    // arms up, a wiggle of joy, GOAL! and confetti raining beside the mascot
+    const beat = Math.floor(f / 3) % 2 === 0;
+    out.pose = { armsUp: true, shiftX: beat ? 0 : 1 };
+    out.ball = { x: mx + 6, y: my + 4 };
+    out.goal = beat;
+    const seeds = [
+      [15, 0],
+      [18, 2],
+      [21, 1],
+      [24, 4],
+      [17, 3],
+      [22, 0],
+    ];
+    out.confetti = seeds.map(([dx, dy0], i) => ({
+      x: mx + dx,
+      y: my + ((dy0 + Math.floor(f / 2)) % 5), // rows my..my+4
+      color: CONFETTI[(i + f) % CONFETTI.length],
+    }));
+  }
+  return out;
+}
+
+/** Renders the ball/trail/confetti/GOAL, clamped to the mascot's own rows. */
+function drawFootball(g, mx, my, scene, cols) {
+  const paint = (cx, cy, ch, attr) => {
+    if (cy < my || cy > my + 4) return; // never touch the legend above / footer below
+    if (cx < mx || cx > cols - 2) return; // never touch the right border
+    g.put(cx, cy, ch, attr);
+  };
+  for (const c of scene.confetti) paint(c.x, c.y, '\u00b7', { fg: c.color, bold: true });
+  for (const t of scene.trail) paint(t.x, t.y, '\u00b7', { fg: CLOUD, dim: true });
+  if (scene.ball) paint(scene.ball.x, scene.ball.y, '\u25cf', { fg: IVORY, bold: true });
+  if (scene.goal) {
+    const text = 'GOAL!';
+    for (let i = 0; i < text.length; i++) paint(mx + 15 + i, my + 1, text[i], { fg: KRAFT, bold: true });
+  }
+}
+
+/**
+ * Pure frame renderer (exported for tests).
+ * state: { cols, rows, fill, estimated, stats, usage, falling,
+ *          bubbles, disturb, spills, frame, active, eco, url, colorMode,
+ *          mascot } where mascot = { name, frame, frames } | null
+ */
+export function composeFrame(state) {
+  const cols = Math.min(state.cols || 80, 110);
+  const rows = Math.min(state.rows || 24, 32);
+  const mode = state.colorMode || 24;
+  const frame = state.frame || 0;
+  const { fill, stats, usage } = state;
+  const liquid = liquidColorFor(fill);
+  const spark = state.active ? SPARK_FRAMES[Math.floor(frame / 2) % SPARK_FRAMES.length] : SPARK_IDLE;
+
+  // ---- tiny terminals: a single statusline-style row ----
+  if (cols < 46 || rows < 17) {
+    const slots = 10;
+    const filled = Math.round((fill / 100) * slots);
+    const barColor = fgSeq(fill >= 95 ? EMBER : CLAY, mode);
+    let line = `\x1b[${barColor}m${spark} ${'\u2588'.repeat(filled)}\x1b[0m\x1b[2m${'\u2591'.repeat(slots - filled)}\x1b[0m`;
+    line += ` \x1b[1m${Math.round(fill)}%\x1b[0m`;
+    if (cols >= 44) line += ` \x1b[2m\u00b7 ${fmt(stats.totalTokens)} tok\x1b[0m`;
+    if (cols >= 58) line += ` \x1b[2m\u00b7 ${stats.toolCalls} tools\x1b[0m`;
+    return line;
+  }
+
+  const g = new Grid(cols, rows, mode);
+  const bx = 2; // trophy left edge
+  const jarTop = 2;
+  const bodyH = bodyHeightFor(rows);
+  const H = bodyH + 5;
+  const slabRel = H - 4;
+  const floorY = jarTop + H - 1;
+  const rowAt = (rel) => jarTop + rel;
+  const ix = (i) => bx + 1 + i; // interior column -> grid x
+
+  const glass = { fg: CLOUD, dim: true };
+  const eyebrow = { fg: CLOUD, dim: true };
+  const panel = { fg: CLAY, dim: true }; // Claude Code's welcome-box border
+
+  // ---- panel: rounded border with the title in it, like Claude Code's box ----
+  g.put(0, 0, '\u256d', panel);
+  g.text(1, 0, '\u2500'.repeat(cols - 2), panel);
+  g.put(cols - 1, 0, '\u256e', panel);
+  for (let y = 1; y < rows - 1; y++) {
+    g.put(0, y, '\u2502', panel);
+    g.put(cols - 1, y, '\u2502', panel);
+  }
+  g.put(0, rows - 1, '\u2570', panel);
+  g.text(1, rows - 1, '\u2500'.repeat(cols - 2), panel);
+  g.put(cols - 1, rows - 1, '\u256f', panel);
+
+  g.text(2, 0, ` ${spark} claude cup `, { fg: CLAY, bold: true });
+  const now = new Date();
+  const dateLabel = ` ${now.toLocaleDateString('en-US', { weekday: 'long' })} \u00b7 ${now
+    .toLocaleDateString('en-US', { month: 'short', day: 'numeric' })} `.toLowerCase();
+  g.text(cols - 3 - dateLabel.length, 0, dateLabel, eyebrow);
+
+  // ---- the golden trophy ----
+  const { G } = profileFor(bodyH);
+  const gold = { fg: KRAFT };
+  const goldBold = { fg: KRAFT, bold: true };
+  const goldDim = { fg: KRAFT, dim: true };
+
+  // globe cap arc
+  g.put(ix(6), rowAt(0), '\u256d', goldBold);
+  g.text(ix(7), rowAt(0), '\u2500'.repeat(6), goldBold);
+  g.put(ix(13), rowAt(0), '\u256e', goldBold);
+  // globe: curved sides that bulge to the equator, with meridian detail
+  for (let rel = 1; rel <= G - 1; rel++) {
+    const sp = spanFor(rel, bodyH);
+    const prev = rel === 1 ? { lo: 7, hi: 12 } : spanFor(rel - 1, bodyH);
+    const widening = sp.lo < prev.lo;
+    g.put(ix(sp.lo) - 1, rowAt(rel), widening ? '(' : '\\', gold);
+    g.put(ix(sp.hi) + 1, rowAt(rel), widening ? ')' : '/', gold);
+    if (sp.hi - sp.lo + 1 >= 12) {
+      g.put(ix(sp.lo + 2), rowAt(rel), '(', goldDim);
+      g.put(ix(sp.hi - 2), rowAt(rel), ')', goldDim);
+    }
+  }
+  // figures tapering under the globe, then the solid double-struck stem
+  g.put(ix(6), rowAt(G), '\\', gold);
+  g.put(ix(13), rowAt(G), '/', gold);
+  for (let rel = G + 1; rel <= H - 5; rel++) {
+    g.put(ix(6), rowAt(rel), '\u2551', gold);
+    g.put(ix(13), rowAt(rel), '\u2551', gold);
+  }
+  // pedestal step (stem stands on it)
+  g.put(ix(3), rowAt(slabRel), '\u256d', goldBold);
+  g.text(ix(4), rowAt(slabRel), '\u2500'.repeat(2), goldBold);
+  g.put(ix(6), rowAt(slabRel), '\u256f', goldBold);
+  g.put(ix(13), rowAt(slabRel), '\u2570', goldBold);
+  g.text(ix(14), rowAt(slabRel), '\u2500'.repeat(2), goldBold);
+  g.put(ix(16), rowAt(slabRel), '\u256e', goldBold);
+  // pedestal tiers (each wider than the one above)
+  g.put(ix(3), rowAt(H - 3), '\u2502', gold);
+  g.put(ix(16), rowAt(H - 3), '\u2502', gold);
+  g.put(ix(2), rowAt(H - 2), '\u2502', gold);
+  g.put(ix(17), rowAt(H - 2), '\u2502', gold);
+  g.put(ix(2), floorY, '\u2570', goldBold);
+  g.text(ix(3), floorY, '\u2500'.repeat(14), goldBold);
+  g.put(ix(17), floorY, '\u256f', goldBold);
+
+  // ---- liquid: one solid clay fill following the trophy's silhouette ----
+  const interior = interiorRowsFor(bodyH);
+  const fillRows = fillRowsFor(bodyH, fill);
+  const flooded = new Set(interior.slice(interior.length - fillRows));
+  const surfaceRel = fillRows > 0 ? interior[interior.length - fillRows] : null;
+  const surfaceY = surfaceRel !== null ? rowAt(surfaceRel) : floorY;
+  const surfaceColor = mix(liquid, IVORY, 0.55);
+  const floodedList = interior.slice(interior.length - fillRows);
+  const shadeAt = (rel) => {
+    const idx = Math.max(0, floodedList.indexOf(rel));
+    return mix(liquid, BURNT, (idx / Math.max(1, fillRows)) * 0.3);
+  };
+
+  for (const rel of floodedList) {
+    const sp = spanFor(rel, bodyH);
+    const shade = shadeAt(rel);
+    for (let i = sp.lo; i <= sp.hi; i++) {
+      if (rel === surfaceRel) {
+        const disturbed = (state.disturb?.[i] || 0) > 0;
+        const ch = disturbed ? '\u2248' : (i + Math.floor(frame * 0.6)) % 3 === 1 ? '\u2248' : '~';
+        g.put(ix(i), rowAt(rel), ch, { fg: surfaceColor, bg: liquid, bold: disturbed });
+      } else {
+        g.put(ix(i), rowAt(rel), ' ', { bg: shade });
+      }
+    }
+  }
+
+  // ---- bubbles (pale glints inside the fill) ----
+  for (const b of state.bubbles || []) {
+    const y = Math.round(b.y);
+    const rel = y - jarTop;
+    if (y > surfaceY && y < floorY && flooded.has(rel)) {
+      const sp = spanFor(rel, bodyH);
+      const x = Math.max(sp.lo, Math.min(sp.hi, Math.round(b.x)));
+      g.put(ix(x), y, '\u00b0', { fg: surfaceColor, bg: shadeAt(rel) });
+    }
+  }
+
+  // ---- falling activity: clay droplets (or gold when elevated/high_agency) ----
+  const GOLD = [244, 211, 94];
+  const dropColor = (state.powerLevel === 'high_agency' || state.powerLevel === 'elevated') ? GOLD : CLAY;
+  for (const f of state.falling || []) {
+    const gy = Math.round(jarTop + 1 + f.y);
+    if (gy >= floorY || gy >= surfaceY) continue;
+    const sp = spanFor(gy - jarTop, bodyH);
+    const x = Math.max(sp.lo, Math.min(sp.hi, f.fx));
+    g.put(ix(x), gy, '\u00b7', { fg: dropColor, bold: true });
+  }
+
+  // ---- splash droplets above a disturbed surface ----
+  if (surfaceRel !== null && surfaceRel > 1) {
+    const above = spanFor(surfaceRel - 1, bodyH);
+    for (let i = above.lo; i <= above.hi; i++) {
+      if ((state.disturb?.[i] || 0) > 2) g.put(ix(i), surfaceY - 1, '\u00b7', { fg: surfaceColor });
+    }
+  }
+
+  // ---- overflow droplets dripping off the globe onto the base ----
+  for (const s of state.spills || []) {
+    const y = Math.round(s.y);
+    const rel = y - jarTop;
+    if (rel < 1 || rel > H - 5) continue;
+    g.put(s.side < 0 ? ix(0) : ix(19), y, '\u00b7', { fg: liquid });
+  }
+
+  // ---- the % sits at the globe's equator ----
+  {
+    const gm = Math.round((G - 1) / 2);
+    const label = `${Math.round(fill)}%`;
+    const sp = spanFor(gm, bodyH);
+    const lx = ix(sp.lo + Math.floor((sp.hi - sp.lo + 1 - label.length) / 2));
+    const inLiquid = flooded.has(gm);
+    g.text(lx, rowAt(gm), label, inLiquid ? { fg: IVORY, bg: shadeAt(gm), bold: true } : { bold: true });
+  }
+
+  // ---- "CLAUDE CUP" engraved on the pedestal ----
+  {
+    const text = 'CLAUDE CUP';
+    const rel = H - 2;
+    const sp = spanFor(rel, bodyH);
+    const lx = ix(sp.lo + Math.floor((sp.hi - sp.lo + 1 - text.length) / 2));
+    const inLiquid = flooded.has(rel);
+    g.text(lx, rowAt(rel), text, inLiquid ? { fg: mix(liquid, IVORY, 0.75), bg: shadeAt(rel) } : { fg: CLOUD, dim: true });
+  }
+
+  // ---- right column ----
+  const sx = bx + INNER_W + 6;
+  if (cols >= sx + 26) {
+    const colW = Math.min(36, cols - sx - 3);
+    let y = jarTop;
+
+    // hero: percentage + bar + eyebrow
+    const heroColor = fill >= 95 ? EMBER : CLAY;
+    g.text(sx, y, `${Math.round(fill)}%`, { fg: heroColor, bold: true });
+    y++;
+    const barW = Math.min(24, colW - 2);
+    const filled = Math.round((fill / 100) * barW);
+    g.text(sx, y, '\u2588'.repeat(filled), { fg: heroColor });
+    g.text(sx + filled, y, '\u2591'.repeat(barW - filled), { fg: CLOUD, dim: true });
+    y++;
+    const fiveH = usage?.fiveHour;
+    const eyebrowText = state.estimated
+      ? 'EST. ACTIVITY (NO LIMIT DATA)'
+      : `OF 5H LIMIT USED${fiveH?.resetsAt ? ` \u00b7 RESETS IN ${countdown(fiveH.resetsAt).toUpperCase()}` : ''}`;
+    g.text(sx, y, eyebrowText.slice(0, colW), eyebrow);
+    y++;
+    if (fill >= 95) {
+      g.text(sx, y, '! OVERFLOWING \u2014 LIMIT NEARLY FULL'.slice(0, colW), { fg: EMBER, bold: true });
+      y++;
+    }
+
+    // hairline + stats
+    g.text(sx, y, '\u2500'.repeat(colW), { fg: CLOUD, dim: true });
+    y++;
+    const statRow = (label, value, vAttr = { bold: true }) => {
+      if (y >= rows - 2) return;
+      g.text(sx, y, label.padEnd(15), eyebrow);
+      g.text(sx + 15, y, String(value).slice(0, colW - 15), vAttr);
+      y++;
+    };
+    statRow('TOKENS TODAY', fmt(stats.totalTokens));
+    const eff = stats.assistantMessages > 0 ? `${fmt(Math.round(stats.totalTokens / stats.assistantMessages))} tok/reply` : '\u2014';
+    statRow('EFFICIENCY', eff);
+    statRow('REPLIES', fmt(stats.assistantMessages));
+    statRow('EST. COST', `$${(stats.cost ?? 0).toFixed(2)}`);
+    statRow('BURN RATE', `${fmt(stats.burnRate)} tok/min`);
+    if (usage?.fiveHour) {
+      const tl = usage.timeLeft;
+      if (!tl) statRow('TIME LEFT', 'measuring pace...', { fg: CLOUD, dim: true });
+      else if (tl.outlasts) statRow('TIME LEFT', 'lasts past reset', { bold: true });
+      else {
+        const h = Math.floor(tl.minutes / 60);
+        const m = Math.round(tl.minutes % 60);
+        const dur = h > 0 ? `${h}h ${m}m` : `${m}m`;
+        statRow('TIME LEFT', `~${dur} at this pace`, tl.minutes < 30 ? { fg: EMBER, bold: true } : { bold: true });
+      }
+    }
+    if (usage?.sevenDay) {
+      const sd = usage.sevenDay;
+      const mini = 8;
+      const mf = Math.round((sd.pct / 100) * mini);
+      if (y < rows - 2) {
+        g.text(sx, y, 'WEEKLY'.padEnd(15), eyebrow);
+        g.text(sx + 15, y, '\u2588'.repeat(mf), { fg: sd.pct > 85 ? EMBER : KRAFT });
+        g.text(sx + 15 + mf, y, '\u2591'.repeat(mini - mf), { fg: CLOUD, dim: true });
+        g.text(sx + 15 + mini + 1, y, `${Math.round(sd.pct)}%`, { bold: true });
+        const cd = countdown(sd.resetsAt);
+        if (cd) g.text(sx + 15 + mini + 1 + `${Math.round(sd.pct)}%`.length + 1, y, `\u00b7 \u21bb ${cd}`, eyebrow);
+        y++;
+      }
+    }
+    // power level badge (from the calibrator) — only shown when explicitly set
+    if (y < rows - 2 && state.powerLevel) {
+      const pl = state.powerLevel;
+      const GOLD_BADGE = [244, 211, 94];
+      g.text(sx, y, 'POWER'.padEnd(15), eyebrow);
+      if (pl === 'high_agency') {
+        g.text(sx + 15, y, '\u2605 HIGH-AGENCY', { fg: GOLD_BADGE, bold: true });
+      } else if (pl === 'elevated') {
+        g.text(sx + 15, y, '\u25b2 ELEVATED', { fg: KRAFT, bold: true });
+      } else {
+        g.text(sx + 15, y, '\u00b7 standard', { fg: CLOUD, dim: true });
+      }
+      y++;
+    }
+    if (y < rows - 2) {
+      const OLIVE = TOKEN_COLORS.edit;
+      g.text(sx, y, 'ECO MODE'.padEnd(15), eyebrow);
+      if (state.eco) {
+        g.put(sx + 15, y, '\u25c9', { fg: OLIVE });
+        g.text(sx + 17, y, 'ON \u00b7 token saver', { fg: OLIVE, bold: true });
+      } else {
+        g.put(sx + 15, y, '\u25cb', { fg: CLOUD, dim: true });
+        g.text(sx + 17, y, 'OFF', { fg: CLOUD, dim: true });
+      }
+      y++;
+    }
+
+    // category legend
+    if (y < rows - 2) {
+      g.text(sx, y, '\u2500'.repeat(colW), { fg: CLOUD, dim: true });
+      y++;
+      const cats = [
+        ['read', 'read', stats.toolsByCategory?.read || 0],
+        ['edit', 'edit', stats.toolsByCategory?.edit || 0],
+        ['terminal', 'term', stats.toolsByCategory?.terminal || 0],
+        ['web', 'web', stats.toolsByCategory?.web || 0],
+        ['agent', 'agent', stats.toolsByCategory?.agent || 0],
+        ['ai', 'replies', stats.assistantMessages || 0],
+      ];
+      let cx = sx;
+      for (const [key, lbl, n] of cats) {
+        const seg = `${lbl} ${n}`;
+        if (cx + seg.length + 2 > sx + colW) {
+          cx = sx;
+          y++;
+          if (y >= rows - 2) break;
+        }
+        g.put(cx, y, '\u25cf', { fg: TOKEN_COLORS[key] });
+        g.text(cx + 2, y, seg, { fg: CLOUD });
+        cx += seg.length + 5;
+      }
+    }
+
+    // Clawd keeps you company when there's room - and plays a little football
+    y += 1;
+    if (y + 4 <= rows - 3) {
+      const scene = state.mascot ? footballScene(state.mascot, sx, y, cols) : null;
+      drawMascot(g, sx, y, scene ? scene.pose : {});
+      if (scene) drawFootball(g, sx, y, scene, cols);
+    }
+  }
+
+  // ---- footer ----
+  const shortUrl = String(state.url || '').replace(/^https?:\/\//, '');
+  g.text(bx, rows - 2, `(e: eco mode \u00b7 ctrl+c to quit \u00b7 web ui at ${shortUrl})`.slice(0, cols - bx - 2), eyebrow);
+
+  return g.toString();
+}
+
+// startTui uses surfaceRelFor + bodyHeightFor for the droplet/bubble physics.
+export function startTui({ aggregator, poller, watcher, eco, url, getPower, out = process.stdout }) {
+  let colorMode = 24;
+  try {
+    if (out.hasColors && !out.hasColors(16777216)) colorMode = 256;
+  } catch {
+    /* keep truecolor */
+  }
+
+  const falling = [];
+  const bubbles = [];
+  const spills = [];
+  const disturb = new Array(INNER_W).fill(0);
+  let frame = 0;
+  let lastActivity = 0;
+  let ecoOn = eco ? eco.status().on : false; // real eco mode, toggled with "e"
+
+  // football: idle for a 5-15s gap, then play one ~2s animation
+  let mascotAnim = null; // { name, frame, frames } | null
+  let lastAnim = null;
+  let nextAnimAt = Date.now() + nextAnimDelay();
+
+  const spawn = () => {
+    if (falling.length > 26) return;
+    falling.push({
+      fx: 1 + Math.floor(Math.random() * (INNER_W - 2)),
+      y: 0,
+      vy: 0.6 + Math.random() * 0.2,
+    });
+    lastActivity = Date.now();
+  };
+
+  const onEvent = (evt, { live }) => {
+    if (!live || evt.kind !== 'assistant') return;
+    spawn();
+    for (let i = 0; i < evt.tools.length; i++) spawn();
+  };
+  watcher.on('event', onEvent);
+
+  // seed a gentle drizzle of today's earlier activity
+  const snap = aggregator.snapshot();
+  const seedCount = Math.min(24, snap.toolCalls + snap.assistantMessages);
+  for (let i = 0; i < seedCount; i++) setTimeout(() => spawn(), 300 + i * 170);
+
+  out.write('\x1b[?1049h\x1b[?25l'); // alt screen, hide cursor
+
+  const render = () => {
+    frame++;
+    const stats = aggregator.snapshot();
+    const usage = poller.state;
+    const hasLimit = usage && usage.fiveHour && (usage.status === 'ok' || usage.status === 'stale');
+    const fill = hasLimit
+      ? usage.fiveHour.pct
+      : Math.min(92, Math.max(stats.totalTokens > 0 ? 4 : 0, (stats.totalTokens / 150000) * 100));
+
+    const rows = Math.min(out.rows || 24, 32);
+    const bodyH = bodyHeightFor(rows);
+    const H = bodyH + 5;
+    const surfaceRel = surfaceRelFor(bodyH, fill); // top flooded row, or null
+    const restRel = surfaceRel !== null ? surfaceRel : H - 2; // land on liquid or base floor
+
+    // falling droplets: accelerate, then merge into the liquid with a splash
+    for (let i = falling.length - 1; i >= 0; i--) {
+      const f = falling[i];
+      f.vy = Math.min(1.6, f.vy + 0.12);
+      f.y += f.vy;
+      if (f.y >= restRel - 0.2) {
+        if (surfaceRel !== null) {
+          disturb[f.fx] = 4;
+          bubbles.push({ x: f.fx, y: 0, born: frame });
+        }
+        falling.splice(i, 1);
+      }
+    }
+
+    // bubbles rise from the base toward the surface
+    const fillRows = surfaceRel !== null ? H - 2 - surfaceRel : 0;
+    if (fillRows >= 3 && Math.random() < 0.12 + (falling.length ? 0.1 : 0)) {
+      bubbles.push({ x: 1 + Math.random() * (INNER_W - 2), y: 0, born: frame });
+    }
+    for (let i = bubbles.length - 1; i >= 0; i--) {
+      const b = bubbles[i];
+      b.y = b.y || H - 2.5;
+      b.y -= 0.3;
+      b.x += Math.sin((frame + i) * 0.4) * 0.15;
+      if (surfaceRel === null || b.y <= surfaceRel + 0.5) bubbles.splice(i, 1);
+    }
+    // bubble rows are jar-relative; compose expects grid rows (jarTop = 2)
+    const bubblesGrid = bubbles.map((b) => ({ x: Math.max(0, Math.min(INNER_W - 1, b.x)), y: 2 + b.y }));
+
+    // overflow: droplets drip off the globe, down past the stem, onto the base
+    if (fill >= 95 && Math.random() < 0.25 && spills.length < 8) {
+      spills.push({ side: Math.random() < 0.5 ? -1 : 1, y: 1 });
+    }
+    for (let i = spills.length - 1; i >= 0; i--) {
+      spills[i].y += 0.7;
+      if (spills[i].y > H - 5) spills.splice(i, 1);
+    }
+
+    for (let i = 0; i < INNER_W; i++) if (disturb[i] > 0) disturb[i]--;
+
+    // football scheduler: start a new animation once the idle gap elapses
+    if (!mascotAnim && Date.now() >= nextAnimAt) {
+      const name = pickAnimation(lastAnim);
+      mascotAnim = { name, frame: 0, frames: ANIM_FRAMES[name] };
+    }
+
+    const power = typeof getPower === 'function' ? getPower() : { powerLevel: 'standard', richness: 0 };
+    const frameStr = composeFrame({
+      cols: out.columns || 80,
+      rows,
+      fill,
+      estimated: !hasLimit,
+      stats,
+      usage,
+      falling,
+      bubbles: bubblesGrid,
+      disturb,
+      spills,
+      frame,
+      active: falling.length > 0 || Date.now() - lastActivity < 3000,
+      eco: ecoOn,
+      url,
+      colorMode,
+      mascot: mascotAnim,
+      powerLevel: power.powerLevel,
+      richness: power.richness,
+    });
+    out.write('\x1b[H' + frameStr + '\x1b[J');
+
+    // advance the animation for the next tick; reschedule when it finishes
+    if (mascotAnim) {
+      mascotAnim.frame++;
+      if (mascotAnim.frame >= mascotAnim.frames) {
+        lastAnim = mascotAnim.name;
+        mascotAnim = null;
+        nextAnimAt = Date.now() + nextAnimDelay();
+      }
+    }
+  };
+
+  const timer = setInterval(render, 140);
+  render();
+
+  // keyboard: "e" toggles eco mode for real; raw mode swallows ctrl+c, so re-emit it
+  const onKey = (buf) => {
+    const k = buf.toString();
+    if (k === '\u0003') {
+      process.emit('SIGINT');
+      return;
+    }
+    if (k === 'e' || k === 'E') {
+      if (eco) {
+        const r = ecoOn ? eco.disable() : eco.enable();
+        if (r.ok) ecoOn = r.status.on;
+      } else {
+        ecoOn = !ecoOn;
+      }
+      render();
+    }
+  };
+  const keysActive = process.stdin.isTTY === true;
+  if (keysActive) {
+    process.stdin.setRawMode?.(true);
+    process.stdin.resume();
+    process.stdin.on('data', onKey);
+  }
+
+  const stop = () => {
+    clearInterval(timer);
+    watcher.off('event', onEvent);
+    if (keysActive) {
+      process.stdin.off('data', onKey);
+      process.stdin.setRawMode?.(false);
+      process.stdin.pause();
+    }
+    out.write('\x1b[?25h\x1b[?1049l'); // restore cursor, leave alt screen
+  };
+  return stop;
+}