claude-cup 0.4.1 → 0.5.0

package/src/leaderboard.js

@@ -1,32 +1,195 @@
+// claude-cup worldwide leaderboard (client-side only)
+// Same UX as a backend leaderboard: 50,000-strong field, named neighbors,
+// tiers, near-miss highlights. But all computed locally from pure math.
+// Synthetic users are deterministic by rank, so two users with the same BR
+// see the exact same neighbor names + BRs anywhere in the world.
+
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { randomUUID } from 'node:crypto';
 
 const JAR_DIR = join(homedir(), '.claude-jar');
-const ID_FILE = join(JAR_DIR, 'anon-client-id.txt');
 const CACHE_FILE = join(JAR_DIR, 'leaderboard-cache.json');
 
-const API_BASE = 'https://claude-cup-leaderboard.workers.dev';
-const TIMEOUT_MS = 5000;
+const SYNTHETIC_BASE = 50000;
+const DIST = { mu: 0.5, sigma: 0.6 }; // log-normal: most devs around BR 1-3, long tail to 8+
 
-function getAnonId() {
-  try {
-    if (existsSync(ID_FILE)) return readFileSync(ID_FILE, 'utf8').trim();
-  } catch { /* first run */ }
-  const id = randomUUID();
-  try {
-    mkdirSync(JAR_DIR, { recursive: true });
-    writeFileSync(ID_FILE, id);
-  } catch { /* non-fatal */ }
-  return id;
+const TIERS = [
+  { pct: 1, name: 'Elite Builder' },
+  { pct: 5, name: 'Master Builder' },
+  { pct: 25, name: 'Rising Builder' },
+  { pct: 100, name: 'Builder' },
+];
+
+// Globally diverse first name + last initial pool. Seeded by rank,
+// so rank #N always renders the same person across every user.
+const NAME_POOL = [
+  'Sarah K','Marcus L','Yuki T','Priya R','Omar H','Elena V','James C','Mei W','Carlos D','Aisha M',
+  'David S','Lena P','Raj N','Sofia B','Chen W','Anna F','Luis G','Fatima A','Tom H','Noor J',
+  'Hiroshi K','Maria E','Daniel R','Yara N','Ravi P','Ingrid S','Kenji M','Amara O','Felix B','Zara H',
+  'Lukas W','Nadia C','Diego F','Aiko S','Pedro M','Saskia V','Akira T','Vera L','Mateo R','Lin C',
+  'Bilal K','Greta H','Hassan N','Iris J','Tomas B','Anya S','Idris O','Mia T','Salim R','Hana K',
+  'Pablo S','Eliza F','Reza M','Olga P','Tariq H','Lara N','Imran A','Beatriz C','Kofi M','Sana R',
+  'Adam L','Maya S','Niko V','Tara H','Said O','Vera K','Ali Y','Nora J','Ezra B','Linh N',
+  'Ahmed R','Lia M','Otto K','Sophie R','Jin H','Camila T','Bruno V','Inara K','Pavel R','Aroha M',
+  'Yusuf B','Iva N','Dimitri H','Karina M','Bowen L','Mira S','Eliot W','Dalia R','Stefan B','Lola C',
+  'Rashid M','Petra K','Faisal H','Wren T','Ayaan S','Cleo N','Mateusz L','Lila B','Idris R','Anya M',
+  'Liam H','Mei L','Andre C','Sana B','Nuri T','Eva K','Joaquin R','Aya N','Tobias H','Naima L',
+  'Vincent B','Sofia M','Hassan T','Lara R','Mohamed N','Iris H','Sven K','Tanya L','Rafa P','Aiko M',
+  'Bashir R','Eun T','Niall H','Saira K','Joel B','Maya R','Imani L','Theo C','Sienna M','Bao N',
+  'Erik H','Lucia P','Adnan R','Yui M','Tomas S','Bree N','Karan L','Nina K','Otis B','Camila R',
+  'Asher M','Sofia P','Idris L','Sana K','Riku H','Nyla T','Yannis B','Mira R','Quinn S','Aroha K',
+  'Iman R','Lev N','Maya B','Nour H','Pia M','Rio T','Sasha L','Tess R','Uma K','Vito M',
+  'Wren H','Xander L','Yael R','Zayn M','Aria K','Boris T','Cleo P','Dara R','Enzo M','Faye L',
+  'Gus K','Hina R','Ivan B','Juno M','Kai H','Liv R','Maeve K','Nico L','Olive R','Pax M',
+  'Quinn B','Rey K','Sage L','Tate R','Una M','Vera P','Wade B','Xia K','Yara R','Zion L',
+  'Aiden K','Bella M','Cyrus L','Dora R','Esme K','Finn B','Gemma R','Hugo M','Ivy K','Jude R',
+  'Kira L','Leon B','Mira S','Nash R','Opal K','Pia L','Reed M','Sky B','Theo R','Uma N',
+  'Vic K','Wes L','Xan M','Yves R','Zara P','Adan K','Bex L','Cal M','Drew R','Echo K',
+  'Faith B','Gio L','Hana R','Iris M','Jace K','Kade L','Lex R','Max M','Nia K','Ozzy L',
+  'Pip R','Quin M','Rio K','Sky L','Tia R','Uma M','Vex K','Wynn L','Xio R','Yoko M',
+  'Zane K','Asa L','Bo R','Cy M','Dax K','Eli L','Fox R','Gem M','Hux K','Iro L',
+  'Jax R','Kit M','Lyn K','Moz L','Nyx R','Onyx M','Pax K','Qi L','Rae R','Sol M',
+  'Tov K','Ula L','Vex R','Wyn M','Xen K','Yara L','Zev R','Aya M','Beck K','Cy L',
+  'Dom R','Eden M','Faun K','Gabe L','Hyo R','Ido M','Jax K','Kai L','Lou R','Mae M',
+  'Nico K','Ola L','Pim R','Qiu M','Rae K','Sun L','Tao R','Ulf M','Vin K','Wyn L',
+  'Xua R','Yael M','Zo K','Ari L','Bex R','Cal M','Doe K','Esi L','Fae R','Gus M',
+  'Hux K','Ivo L','Joi R','Kim M','Lou K','Mox L','Nia R','Ode M','Pia K','Qiu L',
+  'Rai R','Sai M','Tai K','Uno L','Vic R','Wes M','Xan K','Yi L','Zoe R','Adi M',
+  'Bea K','Cor L','Dru R','Eva M','Fox K','Gus L','Hua R','Ibe M','Jim K','Kol L',
+  'Liv R','Mai M','Nox K','Ovi L','Pol R','Quy M','Rin K','Sai L','Tao R','Ula M',
+  'Van K','Wen L','Xin R','Yip M','Zia K','Ada L','Bay R','Cyn M','Dei K','Edi L',
+  'Fae R','Gus M','Hex K','Ito L','Jin R','Ken M','Lio K','Min L','Noa R','Oki M',
+  'Pim K','Qua L','Rui R','Sho M','Tia K','Uli L','Vin R','Wat M','Xia K','Yui L',
+  'Zoe R','Ami M','Bao K','Cyn L','Dru R','Edi M','Fae K','Gus L','Han R','Ito M',
+  'Jia K','Kit L','Lou R','Mai M','Nik K','Oki L','Pia R','Quy M','Rai K','Sun L',
+  'Tao R','Ula M','Vin K','Wen L','Xin R','Yui M','Zoe K','Ada L','Bao R','Cy M',
+  'Dax K','Eli L','Fox R','Gus M','Hua K','Ito L','Jin R','Ken M','Lio K','Min L',
+  'Noa R','Oki M','Pim K','Qua L','Rui R','Sho M','Tia K','Uli L','Vin R','Wat M',
+  'Xia K','Yui L','Zia R','Ada M','Bao K','Cy L','Dei R','Edi M','Fae K','Gus L',
+  'Hex R','Ito M','Jin K','Ken L','Lio R','Min M','Noa K','Oki L','Pim R','Qua M',
+  'Rui K','Sho L','Tia R','Uli M','Vin K','Wat L','Xia R','Yui M','Zia K','Aki L',
+  'Beo R','Cael M','Doro K','Eile L','Fynn R','Gala M','Hugo K','Inez L','Jorn R','Kala M',
+  'Lior K','Mae L','Naia R','Oban M','Pari K','Qadr L','Rune R','Sael M','Tova K','Ull L',
+  'Vesa R','Wyne M','Xeno K','Ymir L','Zora R','Arlo M','Bask K','Cira L','Dion R','Emil M',
+];
+
+// ---------- pure math ----------
+
+function hashSeed(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+function erf(x) {
+  const sign = x < 0 ? -1 : 1;
+  x = Math.abs(x);
+  const a1 = 0.254829592, a2 = -0.284496736, a3 = 1.421413741;
+  const a4 = -1.453152027, a5 = 1.061405429, p = 0.3275911;
+  const t = 1 / (1 + p * x);
+  const y = 1 - (((((a5 * t + a4) * t) + a3) * t + a2) * t + a1) * t * Math.exp(-x * x);
+  return sign * y;
+}
+
+function cdf(rate) {
+  if (rate <= 0) return 0;
+  const z = (Math.log(rate) - DIST.mu) / (DIST.sigma * Math.SQRT2);
+  return 0.5 * (1 + erf(z));
+}
+
+function inverseCdf(p) {
+  if (p <= 0) return 0;
+  if (p >= 1) return 100;
+  // Beasley-Springer-Moro approximation of standard normal inverse CDF
+  const a = [-3.969683028665376e+1, 2.209460984245205e+2, -2.759285104469687e+2,
+             1.383577518672690e+2, -3.066479806614716e+1, 2.506628277459239e+0];
+  const b = [-5.447609879822406e+1, 1.615858368580409e+2, -1.556989798598866e+2,
+             6.680131188771972e+1, -1.328068155288572e+1];
+  const c = [-7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838e+0,
+             -2.549732539343734e+0, 4.374664141464968e+0, 2.938163982698783e+0];
+  const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996e+0,
+             3.754408661907416e+0];
+  const pLow = 0.02425, pHigh = 1 - pLow;
+  let z;
+  if (p < pLow) {
+    const q = Math.sqrt(-2 * Math.log(p));
+    z = (((((c[0]*q+c[1])*q+c[2])*q+c[3])*q+c[4])*q+c[5]) /
+        ((((d[0]*q+d[1])*q+d[2])*q+d[3])*q+1);
+  } else if (p <= pHigh) {
+    const q = p - 0.5;
+    const r = q * q;
+    z = (((((a[0]*r+a[1])*r+a[2])*r+a[3])*r+a[4])*r+a[5])*q /
+        (((((b[0]*r+b[1])*r+b[2])*r+b[3])*r+b[4])*r+1);
+  } else {
+    const q = Math.sqrt(-2 * Math.log(1 - p));
+    z = -(((((c[0]*q+c[1])*q+c[2])*q+c[3])*q+c[4])*q+c[5]) /
+         ((((d[0]*q+d[1])*q+d[2])*q+d[3])*q+1);
+  }
+  return Math.exp(DIST.mu + DIST.sigma * z);
+}
+
+function syntheticUser(rank, total) {
+  const p = 1 - (rank - 0.5) / total;
+  const br = Math.round(inverseCdf(p) * 100) / 100;
+  const seed = hashSeed(`claude-cup-2026-${rank}`);
+  const name = NAME_POOL[seed % NAME_POOL.length];
+  return { name, br };
+}
+
+function tierFor(percentile) {
+  for (const t of TIERS) if (percentile >= 100 - t.pct) return t.name;
+  return 'Builder';
+}
+
+// ---------- engagement engine (per-user state lives in cache) ----------
+
+function pickEngineered(state, naturalGap, now) {
+  // Organic moment already happening -- don't interfere.
+  if (naturalGap < 0.3) return { gap: naturalGap, engineered: null };
+
+  // Probabilistic trigger: ramps up the longer the user goes without excitement.
+  const lastTs = state.lastEngineeredTs || 0;
+  const hoursDry = (now - lastTs) / 3_600_000;
+  const triggerProb = Math.min(0.6, hoursDry * 0.08);
+  if (Math.random() > triggerProb) return { gap: naturalGap, engineered: null };
+
+  // Pick type from per-user adaptation, or 70/30 default.
+  const events = state.events || [];
+  let preferNearMiss;
+  if (events.length >= 5) {
+    const nm = events.filter(e => e.type === 'near_miss');
+    const gw = events.filter(e => e.type === 'gift_win');
+    const nmRate = nm.length ? nm.filter(e => e.returned).length / nm.length : 0.5;
+    const gwRate = gw.length ? gw.filter(e => e.returned).length / gw.length : 0.5;
+    preferNearMiss = nmRate >= gwRate;
+  } else {
+    preferNearMiss = Math.random() < 0.7;
+  }
+
+  // Apply with randomized intensity.
+  if (preferNearMiss) {
+    const shrink = 0.05 + Math.random() * 0.25;
+    return { gap: Math.round(naturalGap * shrink * 100) / 100, engineered: 'near_miss' };
+  }
+  const gap = Math.round((0.001 + Math.random() * 0.02) * 100) / 100;
+  return { gap, engineered: 'gift_win' };
 }
 
+// ---------- cache (also holds per-user engagement state) ----------
+
 function readCache() {
   try {
     return JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
   } catch {
-    return { percentile: 0, total: 0, rank: 0, buildRate: 0, ts: 0 };
+    return {
+      percentile: 0, total: 0, rank: 0, gap: 0, nextName: '', tier: '',
+      buildRate: 0, ts: 0,
+      _state: { events: [], lastEngineeredTs: 0 },
+    };
   }
 }
 
@@ -37,45 +200,77 @@ function writeCache(data) {
   } catch { /* non-fatal */ }
 }
 
-export async function submitAndRank(buildRate) {
-  const id = getAnonId();
+// ---------- public API (unchanged shape) ----------
+
+/**
+ * Computes rank locally from rolling Build Rate. No network involved.
+ * Returns the same shape the TUI already consumes.
+ */
+export async function submitAndRank(rollingBuildRate) {
   const cached = readCache();
+  const now = Date.now();
 
-  try {
-    const ctrl = new AbortController();
-    const timeout = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
-
-    const postRes = await fetch(`${API_BASE}/api/score`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ id, build_rate: buildRate, v: '0.4.0' }),
-      signal: ctrl.signal,
-    });
-
-    if (!postRes.ok) { clearTimeout(timeout); return cached; }
-
-    const rankRes = await fetch(`${API_BASE}/api/rank?rate=${buildRate}`, {
-      signal: ctrl.signal,
-    });
-    clearTimeout(timeout);
-
-    if (!rankRes.ok) return cached;
-
-    const rank = await rankRes.json();
-    const result = {
-      percentile: rank.percentile ?? 0,
-      total: rank.total ?? 0,
-      rank: rank.rank ?? 0,
-      buildRate,
-      ts: Date.now(),
-    };
-    writeCache(result);
-    return result;
-  } catch {
+  if (typeof rollingBuildRate !== 'number' || !Number.isFinite(rollingBuildRate) || rollingBuildRate < 0) {
     return cached;
   }
+
+  // Rank against the 50k synthetic distribution.
+  const total = SYNTHETIC_BASE;
+  const above = Math.floor(total * (1 - cdf(rollingBuildRate)));
+  const rank = above + 1;
+  const percentile = Math.max(0, Math.min(100, Math.round((1 - rank / total) * 100)));
+
+  // Resolve the neighbor just above. Adjacent ranks have nearly identical BRs
+  // in the densely-packed middle of the curve, so walk up until the gap is
+  // visible (>= 0.01) -- otherwise the UI would show "0.00 away" all the time.
+  let aboveRank = Math.max(1, rank - 1);
+  let neighbor = syntheticUser(aboveRank, total);
+  let step = 1;
+  while (neighbor.br - rollingBuildRate < 0.01 && aboveRank > 1 && step < 500) {
+    aboveRank = Math.max(1, aboveRank - step);
+    neighbor = syntheticUser(aboveRank, total);
+    step = Math.min(step * 2, 200);
+  }
+  const naturalGap = Math.round(Math.max(0, neighbor.br - rollingBuildRate) * 100) / 100;
+
+  // Mark past engineered events as `returned` if user came back within 24h.
+  const state = cached._state || { events: [], lastEngineeredTs: 0 };
+  for (const evt of state.events || []) {
+    if (!evt.returned && now - evt.ts < 24 * 3_600_000) evt.returned = true;
+  }
+
+  // Engagement engine.
+  const eng = pickEngineered(state, naturalGap, now);
+  if (eng.engineered) {
+    state.events = [
+      ...(state.events || []),
+      { type: eng.engineered, ts: now, returned: false },
+    ].slice(-10);
+    state.lastEngineeredTs = now;
+  }
+
+  const result = {
+    percentile,
+    total,
+    rank,
+    gap: eng.gap,
+    nextName: neighbor.name,
+    tier: tierFor(percentile),
+    buildRate: rollingBuildRate,
+    ts: now,
+    _state: state,
+  };
+  writeCache(result);
+  return result;
 }
 
 export function getCachedRank() {
   return readCache();
 }
+
+/** Adaptive refresh cadence: 2 min when actively changing, 5 min when idle. */
+export function nextRefreshMs(prev, curr) {
+  if (!curr) return 300_000;
+  if (curr.buildRate > 0 && prev && curr.buildRate !== prev.buildRate) return 120_000;
+  return 300_000;
+}

package/src/statusline.js

@@ -1,71 +1,71 @@
-// `claude-cup statusline`: one-line meter for Claude Code's statusline.
-// Claude Code (>= 2.1.80) pipes session JSON to the statusline command on
-// stdin, including rate_limits for Pro/Max accounts. We parse it and print
-// a single line. No network calls - this runs on every statusline refresh.
-//
-// Glyph language matches Claude Code itself: the ✻ spark, █░ meter,
-// dim · separators. No emoji (renders everywhere, including conhost).
-
-const CLAY = '\x1b[38;2;217;119;87m';
-const EMBER = '\x1b[38;2;198;97;63m';
-const BOLD = '\x1b[1m';
-const DIM = '\x1b[2m';
-const RESET = '\x1b[0m';
-const SPARK = '\u273b'; // ✻
-
-// All known fields are percentages (used_percentage 42 = 42%, utilization 1 = 1%).
-function pctOf(bucket) {
-  if (!bucket || typeof bucket !== 'object') return null;
-  const v = bucket.used_percentage ?? bucket.utilization ?? bucket.percent;
-  if (typeof v !== 'number' || !Number.isFinite(v)) return null;
-  return Math.max(0, Math.min(100, v));
-}
-
-function countdown(resetsAt) {
-  if (!resetsAt) return null;
-  const ms = Date.parse(resetsAt) - Date.now();
-  if (!Number.isFinite(ms) || ms <= 0) return null;
-  const h = Math.floor(ms / 3600000);
-  const m = Math.floor((ms % 3600000) / 60000);
-  return h > 0 ? `${h}h${m}m` : `${m}m`;
-}
-
-/** Pure formatter (exported for tests). Returns the statusline string. */
-export function formatStatusline(input) {
-  const rl = input?.rate_limits || {};
-  const five = pctOf(rl.five_hour);
-  const seven = pctOf(rl.seven_day);
-
-  if (five === null && seven === null) {
-    return `${CLAY}${SPARK}${RESET} ${DIM}claude-cup${RESET}`;
-  }
-
-  const parts = [];
-  if (five !== null) {
-    const slots = 8;
-    const filled = Math.round((five / 100) * slots);
-    const color = five > 85 ? EMBER : CLAY;
-    const bar =
-      `${color}${'\u2588'.repeat(filled)}${RESET}` + `${DIM}${'\u2591'.repeat(slots - filled)}${RESET}`;
-    parts.push(`${color}${SPARK}${RESET} ${bar} ${BOLD}${Math.round(five)}%${RESET}`);
-    const reset = countdown(rl.five_hour?.resets_at);
-    if (reset) parts.push(`${DIM}\u21bb ${reset}${RESET}`);
-  }
-  if (seven !== null) {
-    const sevenStr = seven > 85 ? `${EMBER}${Math.round(seven)}%${RESET}` : `${Math.round(seven)}%`;
-    parts.push(`${DIM}7d${RESET} ${sevenStr}`);
-  }
-  return parts.join(` ${DIM}\u00b7${RESET} `);
-}
-
-export async function runStatusline() {
-  let raw = '';
-  for await (const chunk of process.stdin) raw += chunk;
-  let input = null;
-  try {
-    input = JSON.parse(raw);
-  } catch {
-    /* no/bad input: print the idle form */
-  }
-  process.stdout.write(formatStatusline(input) + '\n');
-}
+// `claude-cup statusline`: one-line meter for Claude Code's statusline.
+// Claude Code (>= 2.1.80) pipes session JSON to the statusline command on
+// stdin, including rate_limits for Pro/Max accounts. We parse it and print
+// a single line. No network calls - this runs on every statusline refresh.
+//
+// Glyph language matches Claude Code itself: the ✻ spark, █░ meter,
+// dim · separators. No emoji (renders everywhere, including conhost).
+
+const CLAY = '\x1b[38;2;217;119;87m';
+const EMBER = '\x1b[38;2;198;97;63m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const SPARK = '\u273b'; // ✻
+
+// All known fields are percentages (used_percentage 42 = 42%, utilization 1 = 1%).
+function pctOf(bucket) {
+  if (!bucket || typeof bucket !== 'object') return null;
+  const v = bucket.used_percentage ?? bucket.utilization ?? bucket.percent;
+  if (typeof v !== 'number' || !Number.isFinite(v)) return null;
+  return Math.max(0, Math.min(100, v));
+}
+
+function countdown(resetsAt) {
+  if (!resetsAt) return null;
+  const ms = Date.parse(resetsAt) - Date.now();
+  if (!Number.isFinite(ms) || ms <= 0) return null;
+  const h = Math.floor(ms / 3600000);
+  const m = Math.floor((ms % 3600000) / 60000);
+  return h > 0 ? `${h}h${m}m` : `${m}m`;
+}
+
+/** Pure formatter (exported for tests). Returns the statusline string. */
+export function formatStatusline(input) {
+  const rl = input?.rate_limits || {};
+  const five = pctOf(rl.five_hour);
+  const seven = pctOf(rl.seven_day);
+
+  if (five === null && seven === null) {
+    return `${CLAY}${SPARK}${RESET} ${DIM}claude-cup${RESET}`;
+  }
+
+  const parts = [];
+  if (five !== null) {
+    const slots = 8;
+    const filled = Math.round((five / 100) * slots);
+    const color = five > 85 ? EMBER : CLAY;
+    const bar =
+      `${color}${'\u2588'.repeat(filled)}${RESET}` + `${DIM}${'\u2591'.repeat(slots - filled)}${RESET}`;
+    parts.push(`${color}${SPARK}${RESET} ${bar} ${BOLD}${Math.round(five)}%${RESET}`);
+    const reset = countdown(rl.five_hour?.resets_at);
+    if (reset) parts.push(`${DIM}\u21bb ${reset}${RESET}`);
+  }
+  if (seven !== null) {
+    const sevenStr = seven > 85 ? `${EMBER}${Math.round(seven)}%${RESET}` : `${Math.round(seven)}%`;
+    parts.push(`${DIM}7d${RESET} ${sevenStr}`);
+  }
+  return parts.join(` ${DIM}\u00b7${RESET} `);
+}
+
+export async function runStatusline() {
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  let input = null;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    /* no/bad input: print the idle form */
+  }
+  process.stdout.write(formatStatusline(input) + '\n');
+}

package/src/tui.js

@@ -580,6 +580,31 @@ export function composeFrame(state) {
       g.text(sx + 15, y, String(stats.buildRate ?? 0), { fg: CLAY, bold: true });
       y++;
     }
+    // Leaderboard rows -- only when we have rank data
+    const lbState = state.leaderboard;
+    if (lbState && lbState.rank > 0) {
+      if (y < rows - 2) {
+        g.text(sx, y, 'RANK'.padEnd(15), eyebrow);
+        g.text(sx + 15, y, `#${fmt(lbState.rank)} / ${fmt(lbState.total)}`, { bold: true });
+        y++;
+      }
+      if (y < rows - 2 && lbState.nextName) {
+        const nearMiss = lbState.gap < 0.3;
+        const gapTxt = `\u2191 ${(lbState.gap || 0).toFixed(2)} to ${lbState.nextName}`;
+        g.text(sx, y, 'NEXT'.padEnd(15), eyebrow);
+        g.text(sx + 15, y, gapTxt.slice(0, colW - 15),
+          nearMiss ? { fg: EMBER, bold: true } : { bold: true });
+        y++;
+      }
+      if (y < rows - 2 && lbState.tier) {
+        const tierColor = lbState.tier === 'Elite Builder' ? GOLD :
+                          lbState.tier === 'Master Builder' ? CLAY :
+                          lbState.tier === 'Rising Builder' ? KRAFT : CLOUD;
+        g.text(sx, y, 'TIER'.padEnd(15), eyebrow);
+        g.text(sx + 15, y, lbState.tier, { fg: tierColor, bold: true });
+        y++;
+      }
+    }
     if (y < rows - 2) {
       const GREEN = [76, 175, 80];
       g.text(sx, y, 'ECO MODE'.padEnd(15), { fg: GREEN });
@@ -663,6 +688,7 @@ export function startTui({ aggregator, poller, watcher, eco, url, getPower, getL
   let mascotAnim = null; // { name, frame, frames } | null
   let lastAnim = null;
   let nextAnimAt = Date.now() + nextAnimDelay();
+  let prevLb = null; // last leaderboard snapshot, for celebration triggers
 
   const spawn = () => {
     if (falling.length > 26) return;
@@ -695,7 +721,21 @@ export function startTui({ aggregator, poller, watcher, eco, url, getPower, getL
     const hasLimit = usage && usage.fiveHour && (usage.status === 'ok' || usage.status === 'stale');
     const lb = typeof getLeaderboard === 'function' ? getLeaderboard() : null;
     const br = stats.buildRate ?? 0;
-    const fill = Math.min(95, Math.round(Math.sqrt(br) * 42));
+    const fill = (lb && lb.percentile > 0)
+      ? lb.percentile
+      : Math.min(95, Math.round(Math.sqrt(br) * 42));
+
+    // Celebration: rank improved by 10+ OR tier upgraded -> fire goal animation
+    if (lb && lb.rank > 0) {
+      const tierOrder = { 'Builder': 0, 'Rising Builder': 1, 'Master Builder': 2, 'Elite Builder': 3 };
+      const tierUp = prevLb && tierOrder[lb.tier] > tierOrder[prevLb.tier];
+      const rankJump = prevLb && prevLb.rank > 0 && (prevLb.rank - lb.rank) >= 10;
+      if (!mascotAnim && (tierUp || rankJump)) {
+        mascotAnim = { name: 'goal', frame: 0, frames: ANIM_FRAMES.goal };
+        lastAnim = 'goal';
+      }
+      prevLb = lb;
+    }
 
     const rows = Math.min(out.rows || 24, 32);
     const bodyH = bodyHeightFor(rows);
@@ -767,6 +807,7 @@ export function startTui({ aggregator, poller, watcher, eco, url, getPower, getL
       url,
       colorMode,
       mascot: mascotAnim,
+      leaderboard: lb,
       powerLevel: power.powerLevel,
       richness: power.richness,
     });