tokenmaxing 0.1.0

package/src/report.js

@@ -0,0 +1,974 @@
+import {
+  compactNumber,
+  dollars,
+  formatInteger,
+  formatPercent,
+  sortedEntries,
+  tokenTotal,
+} from "./utils.js";
+import { estimateModelCosts } from "./pricing.js";
+
+// ---------------------------------------------------------------------------
+// palette — ember on black, edex-terminal style
+// ---------------------------------------------------------------------------
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+const RED = [255, 59, 48];
+const EMBER = [255, 94, 0];
+const ORANGE = [255, 138, 0];
+const AMBER = [255, 184, 48];
+const FG = [235, 226, 210];
+const GRAY = [128, 119, 104];
+const SHADOW = [82, 74, 64];
+const COAL = [54, 49, 43];
+const HEAT_STOPS = [
+  [255, 59, 48],
+  [255, 94, 0],
+  [255, 184, 48],
+];
+const GRID_LEVELS = [
+  [92, 36, 26],
+  [178, 60, 30],
+  [255, 94, 0],
+  [255, 184, 48],
+];
+
+// categorical provider hues — claude warm orange, codex cool cyan, combined amber
+const CYAN = [0, 209, 255];
+const PROVIDER_COLORS = {
+  claude: ORANGE,
+  codex: CYAN,
+  all: AMBER,
+};
+
+function providerKey(name) {
+  const value = String(name || "").toLowerCase();
+  if (value.includes("codex") || /^(gpt|o3|o4|codex)/.test(value)) return "codex";
+  if (value.includes("claude")) return "claude";
+  return "all";
+}
+
+function providerColor(name) {
+  return PROVIDER_COLORS[providerKey(name)] || ORANGE;
+}
+
+const colorEnabled =
+  process.env.NO_COLOR === undefined &&
+  (process.env.FORCE_COLOR !== undefined || process.stdout.isTTY === true);
+
+export function isColorEnabled() {
+  return colorEnabled;
+}
+
+function fg([r, g, b]) {
+  return colorEnabled ? `\x1b[38;2;${r};${g};${b}m` : "";
+}
+
+function bold(text) {
+  return colorEnabled ? `${BOLD}${text}${RESET}` : text;
+}
+
+function reset() {
+  return colorEnabled ? RESET : "";
+}
+
+function paint(rgb, text) {
+  return `${fg(rgb)}${text}${reset()}`;
+}
+
+function lerp(a, b, t) {
+  return [
+    Math.round(a[0] + (b[0] - a[0]) * t),
+    Math.round(a[1] + (b[1] - a[1]) * t),
+    Math.round(a[2] + (b[2] - a[2]) * t),
+  ];
+}
+
+function heat(t) {
+  const clamped = Math.min(1, Math.max(0, t));
+  const [low, mid, high] = HEAT_STOPS;
+  return clamped < 0.5 ? lerp(low, mid, clamped * 2) : lerp(mid, high, (clamped - 0.5) * 2);
+}
+
+function scale(rgb, k) {
+  return [Math.round(rgb[0] * k), Math.round(rgb[1] * k), Math.round(rgb[2] * k)];
+}
+
+// single-hue ramp: dim at the base, full saturation toward the bar tip
+function shadeRamp(color) {
+  const base = scale(color, 0.42);
+  const tip = lerp(color, [255, 255, 255], 0.12);
+  return (t) => (t < 0.5 ? lerp(base, color, t * 2) : lerp(color, tip, (t - 0.5) * 2));
+}
+
+// ---------------------------------------------------------------------------
+// ansi-aware layout helpers
+// ---------------------------------------------------------------------------
+
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+
+function visibleLength(text) {
+  return text.replace(ANSI_PATTERN, "").length;
+}
+
+function padEndVisible(text, width) {
+  return text + " ".repeat(Math.max(0, width - visibleLength(text)));
+}
+
+function padStartVisible(text, width) {
+  return " ".repeat(Math.max(0, width - visibleLength(text))) + text;
+}
+
+function truncate(text, width) {
+  return text.length > width ? `${text.slice(0, width - 1)}…` : text;
+}
+
+function wrapText(text, width) {
+  const words = String(text).split(/\s+/);
+  const wrapped = [];
+  let current = "";
+  for (const word of words) {
+    if (current && current.length + word.length + 1 > width) {
+      wrapped.push(current);
+      current = word;
+    } else {
+      current = current ? `${current} ${word}` : word;
+    }
+  }
+  if (current) wrapped.push(current);
+  return wrapped;
+}
+
+function reportWidth() {
+  const columns = process.stdout.columns || Number(process.env.COLUMNS) || 96;
+  return Math.min(Math.max(columns - 2, 80), 104);
+}
+
+function fmtUSD(value) {
+  return `$${(Number(value) || 0).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+// ---------------------------------------------------------------------------
+// banner — 5x5 pixel font folded into half-blocks
+// ---------------------------------------------------------------------------
+
+const GLYPHS = {
+  A: [".###.", "#...#", "#####", "#...#", "#...#"],
+  I: ["#####", "..#..", "..#..", "..#..", "#####"],
+  W: ["#...#", "#...#", "#.#.#", "##.##", "#...#"],
+  R: ["####.", "#...#", "####.", "#..#.", "#...#"],
+  P: ["####.", "#...#", "####.", "#....", "#...."],
+  E: ["#####", "#....", "####.", "#....", "#####"],
+  D: ["####.", "#...#", "#...#", "#...#", "####."],
+  " ": ["..", "..", "..", "..", ".."],
+};
+
+function banner(text, indent, colorFn = heat) {
+  const grid = ["", "", "", "", ""];
+  for (const letter of text) {
+    const glyph = GLYPHS[letter] || GLYPHS[" "];
+    for (let row = 0; row < 5; row += 1) grid[row] += `${glyph[row]}.`;
+  }
+
+  const totalCols = grid[0].length;
+  const lines = [];
+  for (let pair = 0; pair < 3; pair += 1) {
+    const top = grid[pair * 2];
+    const bottom = grid[pair * 2 + 1] || ".".repeat(totalCols);
+    let line = " ".repeat(indent);
+    for (let col = 0; col < totalCols; col += 1) {
+      const upper = top[col] === "#";
+      const lower = bottom[col] === "#";
+      const glyphChar = upper && lower ? "█" : upper ? "▀" : lower ? "▄" : " ";
+      if (glyphChar === " ") {
+        line += " ";
+      } else {
+        line += fg(colorFn(totalCols <= 1 ? 1 : col / (totalCols - 1))) + glyphChar;
+      }
+    }
+    lines.push(line + reset());
+  }
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// panel frame — edex-style boxed sections
+// ---------------------------------------------------------------------------
+
+function panel(title, contentLines, width) {
+  const interior = width - 4;
+  const lines = [];
+
+  const head =
+    paint(COAL, "┌── ") +
+    bold(paint(ORANGE, title.toUpperCase())) +
+    paint(SHADOW, " ");
+  lines.push(head + paint(COAL, `${"─".repeat(Math.max(0, width - visibleLength(head) - 1))}┐`));
+  lines.push(paint(COAL, "│") + " ".repeat(width - 2) + paint(COAL, "│"));
+
+  for (const content of contentLines) {
+    lines.push(paint(COAL, "│ ") + padEndVisible(content, interior) + paint(COAL, " │"));
+  }
+
+  lines.push(paint(COAL, "│") + " ".repeat(width - 2) + paint(COAL, "│"));
+  lines.push(paint(COAL, `└${"─".repeat(width - 2)}┘`));
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// widgets — every widget takes the panel interior width
+// ---------------------------------------------------------------------------
+
+const PARTIALS = "▏▎▍▌▋▊▉█";
+
+function gradientBar(ratio, width, colorFn = heat) {
+  const cells = Math.min(1, Math.max(0, ratio)) * width;
+  const full = Math.floor(cells);
+  const fracIndex = Math.round((cells - full) * 8);
+
+  let out = "";
+  for (let cell = 0; cell < full; cell += 1) {
+    out += fg(colorFn(width <= 1 ? 1 : cell / (width - 1))) + "█";
+  }
+  let used = full;
+  if (fracIndex > 0 && full < width) {
+    out += fg(colorFn(width <= 1 ? 1 : full / (width - 1))) + PARTIALS[fracIndex - 1];
+    used += 1;
+  }
+  out += fg(COAL) + "·".repeat(Math.max(0, width - used)) + reset();
+  return out;
+}
+
+function barChart(items, width, options = {}) {
+  const clean = items.filter((item) => Number.isFinite(item.value) && item.value >= 0);
+  if (!clean.length) return [paint(GRAY, "no data")];
+
+  const labelWidth = options.labelWidth || 18;
+  const valueWidth = options.valueWidth || 9;
+  const prefixWidth = options.ranked ? 3 : 0;
+  const barWidth = Math.max(14, width - labelWidth - valueWidth - prefixWidth - 3);
+  const max = Math.max(...clean.map((item) => item.value), Number.EPSILON);
+  const valueFormatter = options.valueFormatter || compactNumber;
+
+  return clean.map((item, index) => {
+    const hue = item.color || null;
+    const colorFn = hue ? shadeRamp(hue) : heat;
+    const isTop = options.rankTop && item.value === max;
+    const labelColor = hue || (isTop ? AMBER : GRAY);
+    const label = padEndVisible(paint(labelColor, truncate(item.label, labelWidth)), labelWidth);
+    const value = padStartVisible(
+      isTop ? bold(paint(AMBER, valueFormatter(item.value))) : paint(hue || FG, valueFormatter(item.value)),
+      valueWidth,
+    );
+    const prefix = options.ranked
+      ? paint(index === 0 ? RED : SHADOW, `${String(index + 1).padStart(2, "0")} `)
+      : "";
+    return `${prefix}${label} ${paint(SHADOW, "▕")}${gradientBar(item.value / max, barWidth, colorFn)} ${value}`;
+  });
+}
+
+function statTiles(stats, width) {
+  const columns = 3;
+  const gap = 2;
+  const tileWidth = Math.floor((width - gap * (columns - 1)) / columns);
+  const inner = tileWidth - 4;
+  const lines = [];
+
+  for (let start = 0; start < stats.length; start += columns) {
+    const row = stats.slice(start, start + columns);
+    const top = [];
+    const labelLine = [];
+    const valueLine = [];
+    const bottom = [];
+
+    for (const stat of row) {
+      top.push(paint(COAL, `┌${"─".repeat(tileWidth - 2)}┐`));
+      labelLine.push(
+        paint(COAL, "│ ") +
+          padEndVisible(paint(GRAY, truncate(stat.label.toUpperCase(), inner)), inner) +
+          paint(COAL, " │"),
+      );
+      const accent = stat.accent || ORANGE;
+      valueLine.push(
+        paint(COAL, "│ ") +
+          padEndVisible(bold(paint(accent, truncate(String(stat.value), inner))), inner) +
+          paint(COAL, " │"),
+      );
+      bottom.push(paint(COAL, `└${"─".repeat(tileWidth - 2)}┘`));
+    }
+
+    const joiner = " ".repeat(gap);
+    lines.push(top.join(joiner), labelLine.join(joiner), valueLine.join(joiner), bottom.join(joiner));
+  }
+  return lines;
+}
+
+const BLOCKS_VERTICAL = "▁▂▃▄▅▆▇█";
+
+function hourHistogram(hours) {
+  const total = hours.reduce((sum, value) => sum + (Number(value) || 0), 0);
+  if (!total) return [paint(GRAY, "no data")];
+
+  const max = Math.max(...hours, Number.EPSILON);
+  let peakHour = 0;
+  for (let hour = 0; hour < 24; hour += 1) {
+    if ((hours[hour] || 0) > (hours[peakHour] || 0)) peakHour = hour;
+  }
+
+  const ROWS = 6;
+  const lines = [];
+  for (let row = ROWS; row >= 1; row -= 1) {
+    let line = "";
+    for (let hour = 0; hour < 24; hour += 1) {
+      const level = ((hours[hour] || 0) / max) * ROWS;
+      const fill = Math.min(1, Math.max(0, level - (row - 1)));
+      const index = Math.round(fill * 8);
+      if (index === 0) {
+        line += "   ";
+      } else {
+        const color = hour === peakHour ? RED : heat((hours[hour] || 0) / max);
+        line += fg(color) + BLOCKS_VERTICAL[index - 1].repeat(2) + reset() + " ";
+      }
+    }
+    lines.push(line);
+  }
+
+  lines.push(paint(COAL, "▔".repeat(24 * 3 - 1)));
+
+  let axis = "";
+  for (let hour = 0; hour < 24; hour += 1) {
+    if (hour % 3 === 0 || hour === peakHour) {
+      const color = hour === peakHour ? RED : SHADOW;
+      axis += paint(color, String(hour).padStart(2, "0")) + " ";
+    } else {
+      axis += "   ";
+    }
+  }
+  lines.push(axis);
+  lines.push("");
+  lines.push(
+    paint(GRAY, "peak ") +
+      bold(paint(RED, `${String(peakHour).padStart(2, "0")}:00`)) +
+      paint(GRAY, ` — ${formatInteger(hours[peakHour])} messages (${formatPercent(hours[peakHour] / total)} of all activity)`),
+  );
+  return lines;
+}
+
+// github-contribution-style daily activity matrix, edex memory-grid flavored
+function activityMatrix(dailyActivity, width) {
+  const days = Object.keys(dailyActivity || {}).sort();
+  if (!days.length) return [paint(GRAY, "no data")];
+
+  const LABEL_WIDTH = 4;
+  const first = new Date(`${days[0]}T00:00:00`);
+  const last = new Date(`${days[days.length - 1]}T00:00:00`);
+
+  // grid columns are weeks starting monday; drop to single-char cells when a
+  // full history (e.g. a whole year) would not fit, trim oldest weeks last
+  const gridStart = new Date(first);
+  gridStart.setDate(gridStart.getDate() - ((gridStart.getDay() + 6) % 7));
+  const totalWeeks = Math.floor((last - gridStart) / (7 * 86400000)) + 1;
+  const cellWidth = LABEL_WIDTH + totalWeeks * 2 <= width ? 2 : 1;
+  const maxWeeks = Math.floor((width - LABEL_WIDTH) / cellWidth);
+  const weeks = Math.min(totalWeeks, maxWeeks);
+  const start = new Date(gridStart);
+  start.setDate(start.getDate() + (totalWeeks - weeks) * 7);
+
+  const max = Math.max(...Object.values(dailyActivity), 1);
+  const dayKey = (date) =>
+    `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+
+  // month labels across the top
+  const monthCells = Array.from({ length: LABEL_WIDTH + weeks * cellWidth }, () => " ");
+  let lastMonth = -1;
+  let lastLabelEnd = -1;
+  for (let week = 0; week < weeks; week += 1) {
+    const weekDate = new Date(start);
+    weekDate.setDate(weekDate.getDate() + week * 7);
+    const month = weekDate.getMonth();
+    const at = LABEL_WIDTH + week * cellWidth;
+    if (month !== lastMonth && at > lastLabelEnd && at + 3 <= monthCells.length) {
+      for (let offset = 0; offset < 3; offset += 1) monthCells[at + offset] = MONTH_NAMES[month][offset];
+      lastLabelEnd = at + 3;
+      lastMonth = month;
+    }
+  }
+  const monthRow = paint(GRAY, monthCells.join("").trimEnd());
+
+  const DAY_LABELS = ["MON", "", "WED", "", "FRI", "", "SUN"];
+  const gap = cellWidth === 2 ? " " : "";
+  const rows = [monthRow];
+  for (let weekday = 0; weekday < 7; weekday += 1) {
+    let row = padEndVisible(paint(GRAY, DAY_LABELS[weekday]), LABEL_WIDTH);
+    for (let week = 0; week < weeks; week += 1) {
+      const date = new Date(start);
+      date.setDate(date.getDate() + week * 7 + weekday);
+      if (date < first || date > last) {
+        row += " " + gap;
+        continue;
+      }
+      const value = dailyActivity[dayKey(date)] || 0;
+      if (value <= 0) {
+        row += paint(GRAY, "·") + gap;
+      } else {
+        const level = Math.min(GRID_LEVELS.length - 1, Math.floor((value / max) * GRID_LEVELS.length));
+        row += paint(GRID_LEVELS[level], "■") + gap;
+      }
+    }
+    rows.push(row);
+  }
+
+  // streaks + busiest day, edex "using x of y" style header
+  const activeDays = days.filter((day) => dailyActivity[day] > 0);
+  const spanDays = Math.round((last - first) / 86400000) + 1;
+  let longestStreak = 0;
+  let streak = 0;
+  let previousTime = null;
+  for (const day of activeDays) {
+    const time = new Date(`${day}T00:00:00`).getTime();
+    streak = previousTime !== null && time - previousTime === 86400000 ? streak + 1 : 1;
+    longestStreak = Math.max(longestStreak, streak);
+    previousTime = time;
+  }
+  const busiest = activeDays.reduce((best, day) => (dailyActivity[day] > dailyActivity[best] ? day : best), activeDays[0]);
+
+  const header =
+    paint(GRAY, "ACTIVE ") +
+    bold(paint(AMBER, `${activeDays.length}`)) +
+    paint(GRAY, ` OUT OF ${spanDays} DAYS`) +
+    paint(SHADOW, totalWeeks > weeks ? `  · showing last ${weeks} weeks` : "");
+
+  let legend = paint(SHADOW, "LESS ") + paint(GRAY, "· ");
+  for (const level of GRID_LEVELS) legend += paint(level, "■ ");
+  legend += paint(SHADOW, "MORE");
+  const facts =
+    paint(GRAY, "longest streak ") +
+    bold(paint(RED, `${longestStreak}d`)) +
+    paint(GRAY, " · busiest ") +
+    paint(AMBER, `${monthLabel(busiest.slice(0, 7)).split(" ")[0]} ${Number(busiest.slice(8))}`) +
+    paint(GRAY, ` — ${formatInteger(dailyActivity[busiest])} messages`);
+
+  return [header, "", ...rows, "", legend, facts];
+}
+
+function stackedShareBar(segments, width) {
+  const barWidth = width - 2;
+  const total = segments.reduce((sum, segment) => sum + segment.value, 0);
+  if (!total) return [paint(GRAY, "no data")];
+
+  let bar = "";
+  let used = 0;
+  const visible = segments.filter((segment) => segment.value > 0);
+  for (let index = 0; index < visible.length; index += 1) {
+    const segment = visible[index];
+    const isLast = index === visible.length - 1;
+    const cells = isLast
+      ? Math.max(0, barWidth - used)
+      : Math.max(1, Math.round((segment.value / total) * barWidth));
+    bar += fg(segment.color) + "█".repeat(Math.max(0, cells));
+    used += cells;
+  }
+  bar += reset();
+
+  const lines = [bar, ""];
+  const labelWidth = Math.max(...segments.map((segment) => segment.label.length)) + 2;
+  for (const segment of segments) {
+    const share = segment.value / total;
+    lines.push(
+      paint(segment.color, "■ ") +
+        padEndVisible(paint(GRAY, segment.label.toUpperCase()), labelWidth) +
+        padStartVisible(paint(FG, compactNumber(segment.value)), 9) +
+        padStartVisible(paint(segment.value > 0 ? AMBER : SHADOW, formatPercent(share)), 8),
+    );
+  }
+  return lines;
+}
+
+function tokenSummaryTable(reports) {
+  const columns = [
+    { key: "name", label: "SOURCE", width: 12, left: true },
+    { key: "input", label: "INPUT", width: 8 },
+    { key: "output", label: "OUTPUT", width: 8 },
+    { key: "cacheRead", label: "CACHE R", width: 8 },
+    { key: "cacheCreation", label: "CACHE W", width: 8 },
+    { key: "reasoning", label: "REASON", width: 8 },
+    { key: "total", label: "TOTAL", width: 9 },
+  ];
+
+  const rows = reports.map((report) => ({
+    name: report.provider,
+    hue: providerColor(report.key),
+    input: report.tokens.input || 0,
+    output: report.tokens.output || 0,
+    cacheRead: report.tokens.cacheRead || 0,
+    cacheCreation: report.tokens.cacheCreation || 0,
+    reasoning: report.tokens.reasoning || 0,
+    total: tokenTotal(report.tokens),
+    combined: report.key === "all",
+  }));
+
+  const header = columns
+    .map((column) =>
+      column.left
+        ? padEndVisible(paint(SHADOW, column.label), column.width)
+        : padStartVisible(paint(SHADOW, column.label), column.width),
+    )
+    .join(" ");
+
+  const tableWidth = columns.reduce((sum, column) => sum + column.width + 1, -1);
+  const lines = [header, paint(COAL, "─".repeat(tableWidth))];
+
+  for (const row of rows) {
+    const cells = columns.map((column) => {
+      if (column.left) {
+        const name = truncate(row.name, column.width);
+        return padEndVisible(row.combined ? bold(paint(row.hue, name)) : paint(row.hue, name), column.width);
+      }
+      const value = compactNumber(row[column.key]);
+      const color = column.key === "total" ? AMBER : row[column.key] > 0 ? FG : SHADOW;
+      return padStartVisible(row.combined ? bold(paint(color, value)) : paint(color, value), column.width);
+    });
+    lines.push(cells.join(" "));
+  }
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// month / model labels
+// ---------------------------------------------------------------------------
+
+const MONTH_NAMES = ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"];
+
+function monthLabel(month) {
+  const [year, monthNumber] = String(month).split("-");
+  const name = MONTH_NAMES[Number(monthNumber) - 1];
+  return name ? `${name} ${year}` : month;
+}
+
+function shortDate(iso) {
+  const date = new Date(iso);
+  if (!Number.isFinite(date.getTime())) return iso;
+  return `${MONTH_NAMES[date.getMonth()]} ${String(date.getDate()).padStart(2, "0")}`;
+}
+
+function modelLabel(usage) {
+  return `${usage.provider || ""} ${usage.model || "unknown"}`.trim();
+}
+
+// ---------------------------------------------------------------------------
+// burn estimation — list prices applied to per-model token splits
+// ---------------------------------------------------------------------------
+
+function buildBurnLines(combined, width) {
+  const lines = [];
+  const hasLocalSpend = Object.keys(combined.monthlySpendUSD).length > 0;
+
+  if (hasLocalSpend) {
+    lines.push(
+      ...barChart(
+        sortedEntries(combined.monthlySpendUSD).map(([month, spendUSD]) => ({
+          label: monthLabel(month),
+          value: spendUSD,
+        })),
+        width,
+        { valueFormatter: fmtUSD, rankTop: true, valueWidth: 11 },
+      ),
+    );
+    return lines;
+  }
+
+  const { priced, unpriced, totalUSD } = estimateModelCosts(combined.modelUsage);
+  if (!priced.length) {
+    lines.push(paint(GRAY, "no local spend cache and no models matched the pricing table"));
+    return lines;
+  }
+
+  lines.push(paint(GRAY, "EST. ALL-TIME BURN  ") + bold(paint(RED, `≈ ${fmtUSD(totalUSD)}`)));
+  lines.push("");
+
+  // allocate the estimated total across months in proportion to token volume
+  const monthTotals = Object.entries(combined.monthlyTokens || {}).map(([month, tokens]) => ({
+    month,
+    tokens: tokenTotal(tokens),
+  }));
+  const trackedTokens = monthTotals.reduce((sum, entry) => sum + entry.tokens, 0);
+  if (trackedTokens > 0) {
+    lines.push(
+      ...barChart(
+        monthTotals
+          .sort((a, b) => a.month.localeCompare(b.month))
+          .map((entry) => ({
+            label: monthLabel(entry.month),
+            value: (totalUSD * entry.tokens) / trackedTokens,
+          })),
+        width,
+        { valueFormatter: (value) => `≈ ${fmtUSD(value)}`, rankTop: true, valueWidth: 12 },
+      ),
+    );
+    lines.push("");
+  }
+
+  lines.push(paint(SHADOW, "BY MODEL"));
+  lines.push(
+    ...barChart(
+      priced.slice(0, 8).map((entry) => ({
+        label: modelLabel(entry.usage),
+        value: entry.costUSD,
+      })),
+      width,
+      { valueFormatter: (value) => `≈ ${fmtUSD(value)}`, labelWidth: 32, valueWidth: 12, ranked: true },
+    ),
+  );
+  lines.push("");
+  const footnotes = [
+    "estimated from public API list prices per 1M tokens — subscription plans not reflected",
+    "reasoning tokens billed within output",
+  ];
+  if (unpriced.length) footnotes.push(`unpriced models excluded: ${unpriced.join(", ")}`);
+  for (const footnote of footnotes) {
+    for (const wrapped of wrapText(footnote, width)) lines.push(paint(SHADOW, wrapped));
+  }
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// hero — the one big screenshot stat
+// ---------------------------------------------------------------------------
+
+const WAR_AND_PEACE_WORDS = 587287;
+
+// full-height 5x5 digit font — rendered upright (no half-block folding) so the
+// numbers stay unambiguous; magnitude (BILLION/MILLION/…) goes in the label
+const HERO_DIGITS = {
+  "0": ["█████", "█   █", "█   █", "█   █", "█████"],
+  "1": ["  █  ", " ██  ", "  █  ", "  █  ", "█████"],
+  "2": ["█████", "    █", "█████", "█    ", "█████"],
+  "3": ["█████", "    █", " ████", "    █", "█████"],
+  "4": ["█   █", "█   █", "█████", "    █", "    █"],
+  "5": ["█████", "█    ", "█████", "    █", "█████"],
+  "6": ["█████", "█    ", "█████", "█   █", "█████"],
+  "7": ["█████", "    █", "   █ ", "  █  ", " █   "],
+  "8": ["█████", "█   █", "█████", "█   █", "█████"],
+  "9": ["█████", "█   █", "█████", "    █", "█████"],
+  ".": ["     ", "     ", "     ", "     ", "  ██ "],
+};
+
+const MAGNITUDE_WORDS = { K: "THOUSAND", M: "MILLION", B: "BILLION", T: "TRILLION" };
+
+function centerVisible(line, width) {
+  const pad = Math.max(0, Math.floor((width - visibleLength(line)) / 2));
+  return " ".repeat(pad) + line;
+}
+
+function heroColor(t) {
+  return t < 0.5 ? lerp(EMBER, AMBER, t * 2) : lerp(AMBER, [255, 240, 205], (t - 0.5) * 2);
+}
+
+// big upright number, each pixel doubled horizontally for weight
+function heroNumber(text) {
+  const rows = ["", "", "", "", ""];
+  for (const char of text) {
+    const glyph = HERO_DIGITS[char] || HERO_DIGITS["."];
+    for (let row = 0; row < 5; row += 1) {
+      rows[row] += glyph[row].replace(/./g, (cell) => (cell === "█" ? "██" : "  ")) + "  ";
+    }
+  }
+
+  const totalCols = Math.max(...rows.map((row) => row.length));
+  return rows.map((row) => {
+    let out = "";
+    for (let col = 0; col < row.length; col += 1) {
+      out += row[col] === " " ? " " : fg(heroColor(totalCols <= 1 ? 1 : col / (totalCols - 1))) + row[col];
+    }
+    return out + reset();
+  });
+}
+
+function heroBlock(combined, width) {
+  const tokens = tokenTotal(combined.tokens);
+  const useTokens = tokens > 0;
+  const compact = compactNumber(useTokens ? tokens : combined.totalMessages);
+  const match = compact.match(/^([\d.,]+)([A-Z]?)$/) || [compact, compact, ""];
+  const digits = match[1].replace(/,/g, "");
+  const magnitude = MAGNITUDE_WORDS[match[2]] || "";
+  const noun = useTokens ? "TOKENS PROCESSED" : "MESSAGES SENT";
+  const label = `${magnitude ? `${magnitude} ` : ""}${noun}`;
+
+  const big = heroNumber(digits);
+  const lines = ["", ...big.map((line) => centerVisible(line, width)), ""];
+  lines.push(centerVisible(bold(paint(AMBER, label.split("").join(" "))), width));
+
+  if (useTokens) {
+    const words = Math.round(tokens * 0.75);
+    const novels = words / WAR_AND_PEACE_WORDS;
+    const burn = estimateModelCosts(combined.modelUsage).totalUSD;
+    const novelText =
+      novels >= 1 ? `${novels < 10 ? novels.toFixed(1) : compactNumber(Math.round(novels))}× War & Peace` : null;
+    const parts = [`≈ ${compactNumber(words)} words`];
+    if (novelText) parts.push(novelText);
+    if (burn > 0) parts.push(`≈ ${fmtUSD(burn)} at list price`);
+    lines.push("");
+    lines.push(centerVisible(paint(SHADOW, parts.join("   ·   ")), width));
+  }
+
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// report
+// ---------------------------------------------------------------------------
+
+export function renderReportBlocks(payload) {
+  const { reports, combined, generatedAt } = payload;
+  const width = reportWidth();
+  const interior = width - 4;
+  const blocks = [];
+  let lines = [];
+  const endBlock = () => {
+    blocks.push(lines.join("\n"));
+    lines = [];
+  };
+
+  // banner + status header
+  lines.push("");
+  lines.push(...banner("AI WRAPPED", 2));
+  lines.push("");
+  const range =
+    combined.firstSeen && combined.lastSeen
+      ? `${shortDate(combined.firstSeen)} → ${shortDate(combined.lastSeen)}`
+      : "no history";
+  const subtitle =
+    "  " +
+    paint(GRAY, "TERMINAL USAGE REPORT  ") +
+    paint(SHADOW, "· ") +
+    paint(AMBER, range) +
+    paint(SHADOW, " · ") +
+    paint(GRAY, "LOCAL ONLY");
+  const generated = paint(SHADOW, `generated ${new Date(generatedAt).toLocaleString()}`);
+  if (visibleLength(subtitle) + visibleLength(generated) + 3 <= width) {
+    lines.push(`${subtitle}${paint(SHADOW, " · ")}${generated}`);
+  } else {
+    lines.push(subtitle);
+    lines.push(`  ${generated}`);
+  }
+  for (const report of reports) {
+    const hue = providerColor(report.key);
+    const dot = report.available ? paint(hue, "●") : paint(RED, "○");
+    const status = report.available ? paint(GRAY, report.root || "n/a") : paint(RED, "missing");
+    const extra =
+      report.key === "claude" && report.available && report.projectConfigDirs
+        ? paint(SHADOW, `  +${report.projectConfigDirs} project .claude dirs`)
+        : "";
+    lines.push(`  ${dot} ${padEndVisible(paint(hue, report.provider), 13)} ${status}${extra}`);
+  }
+  lines.push("");
+  endBlock();
+
+  // hero — the screenshot stat
+  lines.push(...heroBlock(combined, width));
+  lines.push("");
+  endBlock();
+
+  // overview tiles
+  const burn = estimateModelCosts(combined.modelUsage);
+  const spendTile = combined.knownSpendUSD
+    ? { label: "known spend", value: fmtUSD(combined.knownSpendUSD), accent: AMBER }
+    : burn.totalUSD > 0
+      ? { label: "est. burn (list price)", value: `≈ ${fmtUSD(burn.totalUSD)}`, accent: AMBER }
+      : { label: "known spend", value: dollars(0), accent: AMBER };
+  lines.push(
+    ...statTiles(
+      [
+        { label: "messages", value: formatInteger(combined.totalMessages), accent: RED },
+        { label: "all-time tokens", value: compactNumber(tokenTotal(combined.tokens)) },
+        { label: "sessions", value: `${formatInteger(combined.totalSessions)} · ${formatInteger(combined.sessionFiles)} files` },
+        spendTile,
+        {
+          label: "favorite model",
+          value: combined.favoriteModel ? combined.favoriteModel.model : "unknown",
+          accent: combined.favoriteModel ? providerColor(combined.favoriteModel.model) : RED,
+        },
+        { label: "history range", value: range, accent: AMBER },
+      ],
+      width,
+    ),
+  );
+  lines.push("");
+  endBlock();
+
+  // 01 messages by source
+  lines.push(
+    ...panel(
+      "01 · messages",
+      barChart(
+        [combined, ...reports].map((report) => ({
+          label: report.provider,
+          value: report.totalMessages,
+          color: providerColor(report.key),
+        })),
+        interior,
+        { valueFormatter: formatInteger, valueWidth: 11 },
+      ),
+      width,
+    ),
+  );
+  endBlock();
+
+  // 02 monthly tokens
+  lines.push(
+    ...panel(
+      "02 · monthly tokens",
+      barChart(
+        sortedEntries(combined.monthlyTokens).map(([month, tokens]) => ({
+          label: monthLabel(month),
+          value: tokenTotal(tokens),
+        })),
+        interior,
+        { valueFormatter: compactNumber, rankTop: true },
+      ),
+      width,
+    ),
+  );
+  endBlock();
+
+  // 03 burn — local spend cache when present, list-price estimate otherwise
+  lines.push(...panel("03 · burn — list-price estimate", buildBurnLines(combined, interior), width));
+  endBlock();
+
+  // 04 all-time tokens by source
+  lines.push(
+    ...panel(
+      "04 · all-time tokens",
+      barChart(
+        [combined, ...reports].map((report) => ({
+          label: report.provider,
+          value: tokenTotal(report.tokens),
+          color: providerColor(report.key),
+        })),
+        interior,
+        { valueFormatter: compactNumber },
+      ),
+      width,
+    ),
+  );
+  endBlock();
+
+  // 05 token ledger
+  lines.push(...panel("05 · token ledger", tokenSummaryTable([combined, ...reports]), width));
+  endBlock();
+
+  // 06 token mix
+  lines.push(
+    ...panel(
+      "06 · token mix",
+      stackedShareBar(
+        [
+          { label: "input", value: combined.tokens.input || 0, color: AMBER },
+          { label: "output", value: combined.tokens.output || 0, color: RED },
+          { label: "cache read", value: combined.tokens.cacheRead || 0, color: EMBER },
+          { label: "cache write", value: combined.tokens.cacheCreation || 0, color: ORANGE },
+          { label: "reasoning", value: combined.tokens.reasoning || 0, color: GRAY },
+        ],
+        interior,
+      ),
+      width,
+    ),
+  );
+  endBlock();
+
+  // 07 model leaderboard (total tokens)
+  lines.push(
+    ...panel(
+      "07 · model leaderboard — total tokens",
+      barChart(
+        Object.values(combined.modelUsage)
+          .map((usage) => ({ label: modelLabel(usage), value: tokenTotal(usage), color: providerColor(usage.provider) }))
+          .sort((a, b) => b.value - a.value)
+          .slice(0, 16),
+        interior,
+        { valueFormatter: compactNumber, labelWidth: 32, ranked: true },
+      ),
+      width,
+    ),
+  );
+  endBlock();
+
+  // 08 model standing (input + output)
+  lines.push(
+    ...panel(
+      "08 · model standing — input + output",
+      [
+        ...barChart(
+          Object.values(combined.modelUsage)
+            .map((usage) => ({
+              label: modelLabel(usage),
+              value: (usage.input || 0) + (usage.output || 0),
+              color: providerColor(usage.provider),
+            }))
+            .sort((a, b) => b.value - a.value)
+            .slice(0, 12),
+          interior,
+          { valueFormatter: compactNumber, labelWidth: 32, ranked: true },
+        ),
+        "",
+        paint(SHADOW, "favorite = highest input + output token count"),
+      ],
+      width,
+    ),
+  );
+  endBlock();
+
+  // 09 time of day
+  lines.push(...panel("09 · active hours", hourHistogram(combined.hourlyActivity), width));
+  endBlock();
+
+  // 10 daily activity matrix
+  lines.push(...panel("10 · activity matrix", activityMatrix(combined.dailyActivity, interior), width));
+  endBlock();
+
+  return blocks;
+}
+
+// ---------------------------------------------------------------------------
+// decode reveal — scramble cipher glyphs, then resolve left-to-right
+// ---------------------------------------------------------------------------
+
+const SCRAMBLE_CHARS = "01<>/\\|+=*#%&@?!;:^~";
+const SCRAMBLE_TARGET = /[A-Za-z0-9]/;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function animateReveal(text) {
+  const lines = text.split("\n");
+  process.stdout.write("\x1b[?25l");
+  try {
+    for (const line of lines) {
+      const plain = line.replace(ANSI_PATTERN, "");
+      if (!plain.trim()) {
+        process.stdout.write(`${line}\n`);
+        continue;
+      }
+      const FRAMES = 2;
+      for (let frame = 0; frame < FRAMES; frame += 1) {
+        const resolved = Math.floor(plain.length * (frame / FRAMES));
+        let scrambled = "";
+        for (let index = 0; index < plain.length; index += 1) {
+          const char = plain[index];
+          scrambled +=
+            index < resolved || !SCRAMBLE_TARGET.test(char)
+              ? char
+              : SCRAMBLE_CHARS[Math.floor(Math.random() * SCRAMBLE_CHARS.length)];
+        }
+        process.stdout.write(`\r\x1b[2K${fg(SHADOW)}${scrambled}${reset()}`);
+        await sleep(5);
+      }
+      process.stdout.write(`\r\x1b[2K${line}\n`);
+    }
+  } finally {
+    process.stdout.write("\x1b[?25h");
+  }
+}