@drakulavich/zapara 0.1.0

package/src/card.ts

@@ -0,0 +1,162 @@
+// Card data: which of four characters a window is, the sentence behind it, the
+// peak hour, the load spectrum and three highlights, every value already
+// formatted for the page. Pure: Day[] in, CardData out. Nothing here knows a
+// date, a path or a file, so nothing here can leak one.
+import { formatCount, formatTokens, plural } from "./format.ts";
+import { NORMS, WEIGHTS } from "./score.ts";
+import type { Day, HourBucket, Level, Score } from "./types.ts";
+
+export type Character = "conductor" | "supervisor" | "marathoner" | "nightOwl";
+export type Segment = { text: string; strong: boolean };
+export type HighlightKey = "peakSessions" | "contextSwitches" | "longestStreak" | "reportsRead" | "tokensRead" | "interrupts" | "lateShare";
+export type Highlight = { key: HighlightKey; value: string; caption: string };
+export type Spectrum = { calm: number; warming: number; heating: number; fried: number };
+export type CardData = {
+  days: number;
+  character: Character;
+  name: string;
+  sentence: Segment[];
+  motto: string;
+  shares: Record<Character, number>;
+  peak: { index: number; level: Level };
+  spectrum: Spectrum;
+  highlights: Highlight[];
+};
+
+// Tie order: the first of equal shares wins.
+const CHARACTERS: readonly Character[] = ["conductor", "supervisor", "marathoner", "nightOwl"];
+const NAMES: Record<Character, string> = {
+  conductor: "The Conductor", supervisor: "The Supervisor", marathoner: "The Marathoner", nightOwl: "The Night Owl",
+};
+const MOTTOS: Record<Character, string> = {
+  conductor: "You run agents like an orchestra.",
+  supervisor: "Nothing ships without your eyes on it.",
+  marathoner: "You do not stop while it compiles.",
+  nightOwl: "The best commits happen after midnight.",
+};
+// Ranking norms for the third highlight: a value over its norm says how remarkable
+// it is next to the others. Sums are per active hour. These rank a picture and
+// never touch the index; the index's own norms stay in score.ts.
+const CARD_NORMS = { reportsPerHour: 12, tokensPerHour: 65_000, interruptsPerHour: 3, latePercent: 25 } as const;
+const OWNED: Record<Character, [HighlightKey, HighlightKey]> = {
+  conductor: ["peakSessions", "contextSwitches"],
+  supervisor: ["reportsRead", "tokensRead"],
+  marathoner: ["longestStreak", "interrupts"],
+  nightOwl: ["lateShare", "longestStreak"],
+};
+const POOL: readonly HighlightKey[] = ["peakSessions", "contextSwitches", "longestStreak", "reportsRead", "tokensRead", "interrupts", "lateShare"];
+const CAPTIONS: Record<HighlightKey, string> = {
+  peakSessions: "sessions at once",
+  contextSwitches: "switches in one hour",
+  longestStreak: "longest streak",
+  reportsRead: "agent reports read",
+  tokensRead: "tokens of output read",
+  interrupts: "times you stopped Claude",
+  lateShare: "of hours after midnight",
+};
+
+function formatStreak(min: number): string {
+  if (min < 60) return `${min}m`;
+  const h = Math.floor(min / 60);
+  if (h < 10) return `${h}h${String(min % 60).padStart(2, "0")}m`;
+  if (h < 1000) return `${h}h`;
+  return "999h+";
+}
+const percent = (part: number, whole: number): number => Math.round((100 * part) / whole);
+
+// Whole percents that sum to 100: floors first, then one more to the largest
+// remainders, ties resolved in the given order.
+function spectrumOf(counts: [number, number, number, number], total: number): Spectrum {
+  const raw = counts.map((c) => (100 * c) / total);
+  const floors = raw.map((r) => Math.floor(r)) as [number, number, number, number];
+  let left = 100 - floors.reduce((a, b) => a + b, 0);
+  const byRemainder = raw.map((r, i) => ({ i, rem: r - Math.floor(r) })).sort((a, b) => b.rem - a.rem || a.i - b.i);
+  for (const { i } of byRemainder) {
+    if (left === 0) break;
+    floors[i]! += 1;
+    left -= 1;
+  }
+  const [calm, warming, heating, fried] = floors;
+  return { calm, warming, heating, fried };
+}
+
+const strong = (text: string): Segment => ({ text, strong: true });
+const plain = (text: string): Segment => ({ text, strong: false });
+export const sentenceText = (segments: Segment[]): string => segments.map((s) => s.text).join("");
+
+type Active = HourBucket & { score: Score };
+
+export function cardData(days: Day[], w: { days: number }): CardData | null {
+  const active = days.flatMap((d) => d.buckets).filter((b): b is Active => b.score !== null);
+  const n = active.length;
+  if (n === 0) return null;
+  const sum = (f: (b: Active) => number): number => active.reduce((a, b) => a + f(b), 0);
+  const max = (f: (b: Active) => number): number => active.reduce((a, b) => Math.max(a, f(b)), 0);
+  const count = (level: Level): number => active.filter((b) => b.score.level === level).length;
+
+  // Each share is the fraction of that character's maximum possible points the
+  // window collected, so a 10-point component competes fairly with a 40-point one.
+  const shares: Record<Character, number> = {
+    conductor: sum((b) => b.score.parts.parallel + b.score.parts.pace) / ((WEIGHTS.parallel + WEIGHTS.pace) * n),
+    supervisor: sum((b) => b.score.parts.supervision + b.score.parts.reading) / ((WEIGHTS.supervision + WEIGHTS.reading) * n),
+    marathoner: sum((b) => b.score.parts.streak) / (WEIGHTS.streak * n),
+    nightOwl: sum((b) => b.score.parts.late) / (WEIGHTS.late * n),
+  };
+  // Strict > keeps the earlier of equal shares: CHARACTERS is the tie order.
+  const character = CHARACTERS.reduce((best, c) => (shares[c] > shares[best] ? c : best));
+
+  const maxSessions = max((b) => b.sessions);
+  const maxSwitches = max((b) => b.contextSwitches);
+  const maxStreak = max((b) => b.streakMin);
+  const reports = sum((b) => b.reports);
+  const tokens = sum((b) => b.outputTokens);
+  const interrupts = sum((b) => b.interrupts);
+  const late = percent(active.filter((b) => b.lateNight).length, n);
+  const calm = percent(count("Calm"), n);
+
+  const sentences: Record<Character, Segment[]> = {
+    conductor: [strong(plural(maxSessions, "session")), plain(" at once, "), strong(plural(maxSwitches, "context switch", "context switches")), plain(" in one hour.")],
+    supervisor: [strong(plural(reports, "agent report")), plain(" and "), strong(plural(tokens, "token", "tokens", formatTokens)), plain(" of output read.")],
+    marathoner: [plain("Longest streak "), strong(formatStreak(maxStreak)), plain(" without a break, "), strong(`${calm}%`), plain(" of your hours calm.")],
+    nightOwl: [strong(`${late}%`), plain(" of your hours "), strong("after midnight"), plain(".")],
+  };
+
+  const peakBucket = active.reduce((a, b) => (b.score.index > a.score.index ? b : a));
+  const spectrum = spectrumOf([count("Calm"), count("Warming"), count("Heating"), count("Fried")], n);
+
+  const values: Record<HighlightKey, string> = {
+    peakSessions: formatCount(maxSessions),
+    contextSwitches: formatCount(maxSwitches),
+    longestStreak: formatStreak(maxStreak),
+    reportsRead: formatCount(reports),
+    tokensRead: formatTokens(tokens),
+    interrupts: formatCount(interrupts),
+    lateShare: `${late}%`,
+  };
+  const norms: Record<HighlightKey, number> = {
+    peakSessions: (maxSessions - 1) / NORMS.parallelSpan,
+    contextSwitches: maxSwitches / NORMS.supervisionPerHour,
+    longestStreak: maxStreak / NORMS.streakMin,
+    reportsRead: reports / (CARD_NORMS.reportsPerHour * n),
+    tokensRead: tokens / (CARD_NORMS.tokensPerHour * n),
+    interrupts: interrupts / (CARD_NORMS.interruptsPerHour * n),
+    lateShare: late / CARD_NORMS.latePercent,
+  };
+  const owned = OWNED[character];
+  // A late-night number on anyone but the Night Owl is the kind of thing they would hide.
+  const rest = POOL.filter((k) => !owned.includes(k) && (k !== "lateShare" || character === "nightOwl"));
+  const third = rest.reduce((best, k) => (norms[k] > norms[best] ? k : best));
+  const highlights = [...owned, third].map((key) => ({ key, value: values[key], caption: CAPTIONS[key] }));
+
+  return {
+    days: w.days,
+    character,
+    name: NAMES[character],
+    sentence: sentences[character],
+    motto: MOTTOS[character],
+    shares,
+    peak: { index: peakBucket.score.index, level: peakBucket.score.level },
+    spectrum,
+    highlights,
+  };
+}

package/src/cardhtml.ts

@@ -0,0 +1,133 @@
+// The card page: one self-contained HTML document from CardData and the embedded
+// assets. Pure: strings in, string out. Nothing is escaped because nothing from a
+// transcript reaches this file: only CardData's fixed strings and formatted numbers.
+// The look is the table in docs/superpowers/specs/2026-09-18-zapara-card-design.md.
+import type { CardData, Character, Segment } from "./card.ts";
+import type { Level } from "./types.ts";
+
+export type CardAssets = {
+  fonts: { inter400: string; inter700: string; inter800: string; mono500: string };
+  characters: string;
+};
+
+// Where each character sits on the sheet, as fractions [x, y, w, h] of its side,
+// measured on the current assets/characters.webp. The box is scaled so the
+// rectangle's longer side is BOX px and centred at CENTRE, with CSS background-size
+// and background-position, so no cropping happens anywhere.
+export const CHARACTER_RECTS: Record<Character, [number, number, number, number]> = {
+  conductor: [0.02, 0.01, 0.53, 0.543],
+  supervisor: [0.55, 0.07, 0.38, 0.505],
+  marathoner: [0.02, 0.553, 0.50, 0.437],
+  nightOwl: [0.54, 0.585, 0.45, 0.41],
+};
+const BOX = 360;
+const CENTRE = { x: 195, y: 300 };
+
+// Streak accent, its rgb for alpha gradients, and the light shade for the repo link.
+const ACCENT: Record<Character, { main: string; rgb: string; light: string }> = {
+  conductor: { main: "#8b5cf6", rgb: "139,92,246", light: "#c4b5fd" },
+  supervisor: { main: "#22d3ee", rgb: "34,211,238", light: "#a5f3fc" },
+  marathoner: { main: "#f59e0b", rgb: "245,158,11", light: "#fde68a" },
+  nightOwl: { main: "#60a5fa", rgb: "96,165,250", light: "#bfdbfe" },
+};
+const LEVEL_CLASS: Record<Level, string> = { Calm: "calm", Warming: "warm", Heating: "heat", Fried: "fried" };
+
+function spriteStyle(c: Character): string {
+  const [x, y, w, h] = CHARACTER_RECTS[c];
+  const size = BOX / Math.max(w, h);
+  const bw = w * size;
+  const bh = h * size;
+  const px = (v: number): string => `${v.toFixed(1)}px`;
+  return `background-size:${px(size)} ${px(size)};background-position:${px(-x * size)} ${px(-y * size)};width:${px(bw)};height:${px(bh)};left:${px(CENTRE.x - bw / 2)};top:${px(CENTRE.y - bh / 2)}`;
+}
+const sentenceHtml = (segments: Segment[]): string => segments.map((s) => (s.strong ? `<b>${s.text}</b>` : s.text)).join("");
+const fontFace = (family: string, weight: number, data: string): string =>
+  `@font-face{font-family:"${family}";font-weight:${weight};font-style:normal;src:url("data:font/woff2;base64,${data}") format("woff2")}`;
+
+const GRAIN = `url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='300' height='300'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='.9' numOctaves='2' stitchTiles='stitch'/><feColorMatrix values='0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 .6 0'/></filter><rect width='300' height='300' filter='url(%23n)'/></svg>")`;
+
+export function cardHtml(card: CardData, assets: CardAssets): string {
+  const accent = ACCENT[card.character];
+  const levels = [
+    ["calm", card.spectrum.calm, "calm"],
+    ["warm", card.spectrum.warming, "warming"],
+    ["heat", card.spectrum.heating, "heating"],
+    ["fried", card.spectrum.fried, "fried"],
+  ] as const;
+  const bar = levels.filter(([, pct]) => pct > 0).map(([cls, pct]) => `<div class="${cls}" style="width:${pct}%"></div>`).join("");
+  const legend = levels.map(([cls, pct, name]) => `<span><i class="${cls}"></i><b>${pct}%</b> ${name}</span>`).join("&nbsp;&nbsp;");
+  const stats = card.highlights
+    .map((h) => `<div class="stat" data-key="${h.key}"><div class="v">${h.value}</div><div class="c mono">${h.caption}</div></div>`)
+    .join("");
+  const label = card.days === 1 ? "Last 1 day" : `Last ${card.days} days`;
+
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><title>zapara card</title>
+<style>
+${fontFace("Inter", 400, assets.fonts.inter400)}
+${fontFace("Inter", 700, assets.fonts.inter700)}
+${fontFace("Inter", 800, assets.fonts.inter800)}
+${fontFace("JetBrains Mono", 500, assets.fonts.mono500)}
+:root{--ink:#f5f5f7;--muted:#a1a1aa;--dim:#6b6b76;--line:rgba(255,255,255,.10);--accent:${accent.main};--accent2:${accent.light};--accent-rgb:${accent.rgb};--calm:#7ee2a3;--warm:#fbd77a;--heat:#c4a0ff;--fried:#ff6b8f}
+html{zoom:2}
+html,body{margin:0;background:#000}
+.card{position:relative;width:1200px;height:630px;overflow:hidden;font-family:Inter,-apple-system,system-ui,sans-serif;color:var(--ink);-webkit-font-smoothing:antialiased;background:#07070a}
+.mono{font-family:"JetBrains Mono",ui-monospace,monospace}
+.streaks{position:absolute;left:-200px;top:-260px;width:900px;height:1100px;transform:rotate(38deg);filter:blur(22px);opacity:.9}
+.streaks div{position:absolute;top:0;height:100%;border-radius:40px}
+.s1{left:120px;width:150px;background:linear-gradient(180deg,transparent 0%,rgba(var(--accent-rgb),.55) 35%,rgba(var(--accent-rgb),.9) 50%,rgba(var(--accent-rgb),.45) 70%,transparent 100%)}
+.s2{left:320px;width:70px;background:linear-gradient(180deg,transparent 10%,rgba(255,255,255,.35) 45%,rgba(var(--accent-rgb),.7) 55%,transparent 90%)}
+.s3{left:440px;width:200px;background:linear-gradient(180deg,transparent 0%,rgba(var(--accent-rgb),.35) 40%,rgba(34,211,238,.35) 58%,transparent 100%)}
+.s4{left:700px;width:90px;background:linear-gradient(180deg,transparent 15%,rgba(var(--accent-rgb),.5) 50%,transparent 85%)}
+.vignette{position:absolute;inset:0;background:radial-gradient(900px 600px at 30% 40%,transparent 30%,rgba(7,7,10,.85) 75%,#07070a 100%)}
+.grain{position:absolute;inset:0;opacity:.35;mix-blend-mode:overlay;background-image:${GRAIN}}
+.char{position:absolute;background-image:url("data:image/webp;base64,${assets.characters}");background-repeat:no-repeat;filter:drop-shadow(0 30px 40px rgba(0,0,0,.7))}
+.panel{position:absolute;left:380px;top:56px;width:760px;height:518px;box-sizing:border-box;border-radius:20px;border:1px solid var(--line);background:linear-gradient(180deg,rgba(255,255,255,.045),rgba(255,255,255,.02));box-shadow:inset 0 1px 0 rgba(255,255,255,.08),0 30px 80px rgba(0,0,0,.5);padding:36px 40px}
+.row{display:flex;justify-content:space-between;align-items:center}
+.label{font-size:13px;color:var(--dim);letter-spacing:.5px;text-transform:uppercase}
+.peak{display:inline-flex;align-items:center;gap:10px;padding:6px 12px;border-radius:8px;border:1px solid var(--line);background:rgba(255,255,255,.03);font-size:12px;color:var(--dim);letter-spacing:.5px;text-transform:uppercase;white-space:nowrap}
+.peak b{font-weight:500}
+.peak b.calm{color:var(--calm)}.peak b.warm{color:var(--warm)}.peak b.heat{color:var(--heat)}.peak b.fried{color:var(--fried)}
+.name{margin-top:18px;font-size:76px;font-weight:700;line-height:1;letter-spacing:-3px;color:#fff;text-shadow:0 0 40px rgba(255,255,255,.18);white-space:nowrap}
+.sentence{margin-top:22px;font-size:22px;line-height:31px;color:var(--muted);letter-spacing:-.2px;max-width:660px}
+.sentence b{color:#fff;font-weight:600}
+.divider{height:1px;background:var(--line);margin:30px 0 26px}
+.bar{height:8px;border-radius:4px;overflow:hidden;display:flex;gap:2px}
+.bar div{height:100%}
+.bar .calm{background:var(--calm)}.bar .warm{background:var(--warm)}.bar .heat{background:var(--heat)}.bar .fried{background:var(--fried)}
+.legend{margin-top:14px;font-size:12.5px;color:var(--dim);letter-spacing:.2px;white-space:nowrap}
+.legend b{color:var(--muted);font-weight:500}
+.legend i{display:inline-block;width:6px;height:6px;border-radius:50%;margin:0 7px 1px 0}
+.legend i.calm{background:var(--calm)}.legend i.warm{background:var(--warm)}.legend i.heat{background:var(--heat)}.legend i.fried{background:var(--fried)}
+.stats{display:flex;gap:16px;margin-top:30px}
+.stat{flex:1;min-width:0;box-sizing:border-box;padding:18px 16px;border-radius:12px;border:1px solid var(--line);background:rgba(255,255,255,.025);box-shadow:inset 0 1px 0 rgba(255,255,255,.06)}
+.stat .v{font-size:38px;font-weight:700;letter-spacing:-1.6px;line-height:1;color:#fff;font-variant-numeric:tabular-nums;white-space:nowrap}
+.stat .c{margin-top:8px;font-size:12px;color:var(--dim);letter-spacing:0;white-space:nowrap}
+.repo{position:absolute;left:60px;top:566px;line-height:1;white-space:nowrap}
+.repo small{display:block;font-size:11px;letter-spacing:1.5px;text-transform:uppercase;color:var(--dim);margin-bottom:8px}
+.repo span{font-size:17px;font-weight:500;color:var(--accent2);letter-spacing:-.2px}
+.source{position:absolute;right:60px;top:588px;font-size:12px;color:var(--muted);letter-spacing:.2px;white-space:nowrap}
+</style></head><body>
+<div class="card">
+  <div class="streaks"><div class="s1"></div><div class="s2"></div><div class="s3"></div><div class="s4"></div></div>
+  <div class="vignette"></div>
+  <div class="grain"></div>
+  <div class="char ${card.character}" style="${spriteStyle(card.character)}"></div>
+  <div class="panel">
+    <div class="row">
+      <div class="label mono">${label}</div>
+      <div class="peak mono">Peak hour <b class="${LEVEL_CLASS[card.peak.level]}">${card.peak.index} · ${card.peak.level}</b></div>
+    </div>
+    <div class="name">${card.name}</div>
+    <div class="sentence">${sentenceHtml(card.sentence)} ${card.motto}</div>
+    <div class="divider"></div>
+    <div class="bar">${bar}</div>
+    <div class="legend mono">${legend}</div>
+    <div class="stats">${stats}</div>
+  </div>
+  <div class="repo mono"><small>Get yours</small><span>github.com/drakulavich/zapara</span></div>
+  <div class="source mono">computed locally from your Claude Code transcripts · nothing leaves your machine</div>
+</div>
+</body></html>
+`;
+}

package/src/derive.ts

@@ -0,0 +1,129 @@
+import { score } from "./score.ts";
+import type { Day, Event, HourBucket, Metrics, Totals, Window } from "./types.ts";
+
+export const LOOKBACK_MS = 3 * 60 * 60 * 1000;
+export const GAP_MS = 10 * 60 * 1000;
+export const SLOT_MS = 5 * 60 * 1000;
+const LATE_HOURS = new Set([23, 0, 1, 2, 3, 4, 5]);
+
+const pad2 = (n: number) => String(n).padStart(2, "0");
+export const localDate = (d: Date) => `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+const parseDate = (s: string): Date => {
+  const [y, m, d] = s.split("-").map(Number) as [number, number, number];
+  return new Date(y, m - 1, d); // local midnight
+};
+
+export function windowBounds(w: Window): { startMs: number; endMs: number; cutoffMs: number; dates: string[] } {
+  const to = parseDate(w.to);
+  const dates: string[] = [];
+  for (let i = w.days - 1; i >= 0; i--) {
+    const d = new Date(to.getFullYear(), to.getMonth(), to.getDate() - i);
+    dates.push(localDate(d));
+  }
+  const startMs = parseDate(dates[0]!).getTime();
+  const endMs = new Date(to.getFullYear(), to.getMonth(), to.getDate() + 1).getTime();
+  return { startMs, endMs, cutoffMs: startMs - LOOKBACK_MS, dates };
+}
+
+const emptyMetrics = (): Metrics => ({
+  sessions: 0, prompts: 0, reports: 0, outputTokens: 0, interrupts: 0, rejects: 0, questions: 0, plans: 0, modeSwitches: 0,
+  decisions: 0, contextSwitches: 0, activeMin: 0, streakMin: 0, lateNight: false,
+});
+
+type Acc = { m: Metrics; sessions: Set<string>; slots: Set<number>; lastPromptSession: string | null; lastActivity: { ts: number; streakStart: number } | null };
+
+// Walks the sorted, look-back-filtered events once, keyed by "date|hour",
+// tracking the running activity streak (which may start before startMs) and
+// accumulating each bucket's raw counts. Events before startMs update the
+// streak only; they are never attributed to a bucket.
+function foldEvents(sorted: Event[], startMs: number): Map<string, Acc> {
+  const acc = new Map<string, Acc>(); // key "date|hour"
+  const key = (ts: number): string => {
+    const d = new Date(ts);
+    return `${localDate(d)}|${d.getHours()}`;
+  };
+  const get = (k: string): Acc => {
+    let a = acc.get(k);
+    if (!a) { a = { m: emptyMetrics(), sessions: new Set(), slots: new Set(), lastPromptSession: null, lastActivity: null }; acc.set(k, a); }
+    return a;
+  };
+
+  let prevActivityTs: number | null = null;
+  let streakStart: number | null = null;
+  for (const e of sorted) {
+    if (e.kind === "activity") {
+      streakStart = prevActivityTs === null || e.ts - prevActivityTs > GAP_MS ? e.ts : streakStart;
+      prevActivityTs = e.ts;
+    }
+    if (e.ts < startMs) continue; // look-back: streak bookkeeping only
+    const a = get(key(e.ts));
+    switch (e.kind) {
+      case "activity":
+        a.sessions.add(e.sessionId);
+        a.slots.add(Math.floor(e.ts / SLOT_MS));
+        a.lastActivity = { ts: e.ts, streakStart: streakStart! };
+        break;
+      case "prompt":
+        a.m.prompts++;
+        if (a.lastPromptSession !== null && a.lastPromptSession !== e.sessionId) a.m.contextSwitches++;
+        a.lastPromptSession = e.sessionId;
+        break;
+      case "report": a.m.reports++; break;
+      case "output": a.m.outputTokens += e.tokens ?? 0; break;
+      case "interrupt": a.m.interrupts++; break;
+      case "reject": a.m.rejects++; break;
+      case "question": a.m.questions++; break;
+      case "plan_review": a.m.plans++; break;
+      case "mode_change": a.m.modeSwitches++; break;
+    }
+  }
+  return acc;
+}
+
+// Builds one Day's 24 hour buckets from the accumulated counts, scores each,
+// and rolls up totals, peak and mean.
+function buildDay(date: string, acc: Map<string, Acc>): Day {
+  const buckets: HourBucket[] = [];
+  for (let hour = 0; hour < 24; hour++) {
+    const a = acc.get(`${date}|${hour}`);
+    const m = a ? a.m : emptyMetrics();
+    if (a) {
+      m.sessions = a.sessions.size;
+      m.activeMin = a.slots.size * 5;
+      m.streakMin = a.lastActivity ? Math.round((a.lastActivity.ts - a.lastActivity.streakStart) / 60000) : 0;
+    }
+    m.decisions = m.interrupts + m.rejects + m.questions + m.plans + m.modeSwitches;
+    // lateNight is a property of the hour label, so it is set on every bucket,
+    // including empty ones; score() returns null for buckets without
+    // sessions, so an empty late hour scores nothing.
+    m.lateNight = LATE_HOURS.has(hour);
+    buckets.push({ ...m, hour, score: score(m) });
+  }
+  const scored = buckets.filter((b) => b.score !== null);
+  const totals: Totals = buckets.reduce((t, b) => ({
+    prompts: t.prompts + b.prompts, reports: t.reports + b.reports, outputTokens: t.outputTokens + b.outputTokens,
+    interrupts: t.interrupts + b.interrupts, rejects: t.rejects + b.rejects,
+    questions: t.questions + b.questions, plans: t.plans + b.plans, modeSwitches: t.modeSwitches + b.modeSwitches,
+    decisions: t.decisions + b.decisions, contextSwitches: t.contextSwitches + b.contextSwitches,
+    maxSessions: Math.max(t.maxSessions, b.sessions),
+  }), { prompts: 0, reports: 0, outputTokens: 0, interrupts: 0, rejects: 0, questions: 0, plans: 0, modeSwitches: 0, decisions: 0, contextSwitches: 0, maxSessions: 0 });
+  return {
+    date,
+    peak: scored.length ? Math.max(...scored.map((b) => b.score!.index)) : null,
+    mean: scored.length ? Math.round(scored.reduce((s, b) => s + b.score!.index, 0) / scored.length) : null,
+    activeMin: buckets.reduce((s, b) => s + b.activeMin, 0),
+    totals,
+    buckets,
+  };
+}
+
+export function derive(events: Event[], w: Window): Day[] {
+  const { startMs, endMs, cutoffMs, dates } = windowBounds(w);
+  const sorted = events
+    .map((e, i) => ({ e, i }))
+    .filter(({ e }) => e.ts >= cutoffMs && e.ts < endMs)
+    .sort((a, b) => a.e.ts - b.e.ts || (a.e.sessionId < b.e.sessionId ? -1 : a.e.sessionId > b.e.sessionId ? 1 : 0) || a.i - b.i)
+    .map(({ e }) => e);
+  const acc = foldEvents(sorted, startMs);
+  return dates.map((date) => buildDay(date, acc));
+}

package/src/format.ts

@@ -0,0 +1,20 @@
+// Compact number formats shared by the card and the week footer. Pure: no
+// imports from node:/Bun, no clock, no file system.
+
+// Compact formats with a fixed longest form of five characters, so the layout
+// is sized once. Decimals are truncated, not rounded: 9.96M stays "9.9M".
+function ladder(n: number): string {
+  if (n >= 1e12) return "999B+";
+  for (const [unit, size] of [["B", 1e9], ["M", 1e6], ["k", 1e3]] as const) {
+    if (n < size) continue;
+    const v = n / size;
+    if (unit !== "k" && v < 10) return `${(Math.floor(v * 10) / 10).toFixed(1)}${unit}`;
+    return `${Math.floor(v)}${unit}`;
+  }
+  return String(n);
+}
+export const formatCount = (n: number): string => (n < 10_000 ? String(n) : ladder(n));
+export const formatTokens = (n: number): string => (n < 1000 ? String(n) : ladder(n));
+
+// "1 session", "5 sessions": a count with its noun, singular only for exactly one.
+export const plural = (n: number, one: string, many = `${one}s`, count = formatCount): string => `${count(n)} ${n === 1 ? one : many}`;

package/src/image.ts

@@ -0,0 +1,70 @@
+// The card's shell: the only module that reads the card assets, opens a
+// Bun.WebView or a Bun.Image, and writes a file. Everything it writes is the one
+// file the person named; nothing here prints.
+import { readFile, writeFile } from "node:fs/promises";
+import type { CardAssets } from "./cardhtml.ts";
+
+const ASSETS = new URL("../assets/", import.meta.url);
+const FILES = ["fonts/inter-400.woff2", "fonts/inter-700.woff2", "fonts/inter-800.woff2", "fonts/jetbrains-mono-500.woff2", "characters.webp"] as const;
+
+// Reads the five files next to the source. A missing, unreadable or empty one is
+// a broken install, reported without a path: the CLI never prints one.
+export async function loadAssets(): Promise<CardAssets> {
+  let parts: string[];
+  try {
+    parts = await Promise.all(FILES.map(async (name) => (await readFile(new URL(name, ASSETS))).toString("base64")));
+  } catch {
+    throw new Error("assets missing: reinstall zapara");
+  }
+  const [inter400, inter700, inter800, mono500, characters] = parts;
+  if (parts.some((p) => p.length === 0)) throw new Error("assets missing: reinstall zapara");
+  return { fonts: { inter400: inter400!, inter700: inter700!, inter800: inter800!, mono500: mono500! }, characters: characters! };
+}
+
+const BACKEND = process.platform === "darwin" ? "webkit" : "chrome";
+const ENGINE_LINE = "card needs a browser engine: install Google Chrome, or write --out card.html";
+const WIDTH = 2400;
+const HEIGHT = 1260;
+const READY = 'document.fonts.ready.then(() => document.fonts.status === "loaded" && Array.from(document.images).every((i) => i.complete))';
+
+// Writes the page as is for `.html`; otherwise photographs it at 2400x1260 and
+// writes PNG or WebP. The 15s budget bounds the whole render (construct, navigate,
+// poll, screenshot, resize, encode), raced against a single timer; the view is
+// closed on every path. Any engine failure (constructor, navigate, evaluate,
+// screenshot) is mapped to one line that never quotes the engine's own text; the
+// timeout error passes through unchanged. `writeFile` failures are the one
+// exception, left unmapped, so they keep reporting the user's own `--out` string.
+export async function renderCard(html: string, out: string, timeoutMs = 15_000): Promise<void> {
+  const lower = out.toLowerCase();
+  if (lower.endsWith(".html")) {
+    await writeFile(out, html);
+    return;
+  }
+  let bytes: Uint8Array;
+  let timer: ReturnType<typeof setTimeout>;
+  try {
+    bytes = await Promise.race([
+      (async () => {
+        const view = new Bun.WebView({ width: WIDTH, height: HEIGHT, backend: BACKEND });
+        try {
+          await view.navigate("data:text/html;charset=utf-8," + encodeURIComponent(html));
+          while (!(await view.evaluate<boolean>(READY))) await Bun.sleep(50);
+          const shot = await view.screenshot({ encoding: "buffer", format: "png" });
+          const image = new Bun.Image(shot);
+          const meta = await image.metadata();
+          if (meta.width !== WIDTH || meta.height !== HEIGHT) image.resize(WIDTH, HEIGHT, { fit: "fill" });
+          return lower.endsWith(".webp") ? await image.webp({ quality: 90 }).bytes() : await image.png().bytes();
+        } finally {
+          view.close();
+        }
+      })(),
+      new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error("render timed out")), timeoutMs); }),
+    ]);
+  } catch (e) {
+    if (e instanceof Error && e.message === "render timed out") throw e;
+    throw new Error(ENGINE_LINE);
+  } finally {
+    clearTimeout(timer!);
+  }
+  await writeFile(out, bytes);
+}

package/src/index.ts

@@ -0,0 +1,141 @@
+#!/usr/bin/env bun
+// zapara CLI. Argument parsing, the clock, stdout and exit codes live here; everything else is pure.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { cardData, sentenceText } from "./card.ts";
+import { cardHtml } from "./cardhtml.ts";
+import { localDate } from "./derive.ts";
+import { loadAssets, renderCard } from "./image.ts";
+import { renderDay, renderJson, renderWeek } from "./render.ts";
+import { report } from "./report.ts";
+import type { Day } from "./types.ts";
+
+// Read lazily, only when --version is actually handled, so a broken install
+// (missing or corrupt package.json) fails inside the guarded catch below
+// instead of throwing at module load, before any try/catch is in place.
+function version(): string {
+  const parsed: unknown = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  if (typeof parsed === "object" && parsed !== null && typeof (parsed as { version?: unknown }).version === "string") {
+    return (parsed as { version: string }).version;
+  }
+  throw new Error("package.json has no version");
+}
+
+const USAGE = `usage: zapara [week] [--days N] [--to YYYY-MM-DD]
+       zapara day [YYYY-MM-DD] [--explain]
+       zapara card [--days N] [--to YYYY-MM-DD] [--out PATH.png|.webp|.html]
+flags: --json  --projects <dir>  --no-color  --help  --version
+levels: calm 0-29  warming 30-59  heating 60-84  fried 85-100`;
+
+type Args = { command: "week" | "day" | "card"; to: string; days: number; date: string | null; explain: boolean; json: boolean; out: string; projects: string; color: boolean };
+
+class UsageError extends Error {}
+// Thrown only at a flag position (never when a token was consumed as another
+// flag's value, e.g. `--to --help`), so `main()` can short-circuit to exit 0
+// without parseArgs having to also validate the rest of a help/version call.
+class HelpRequested extends Error {}
+class VersionRequested extends Error {}
+
+function validDate(s: string): boolean {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+  if (!m) return false;
+  const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const dt = new Date(y, mo - 1, d);
+  return dt.getFullYear() === y && dt.getMonth() === mo - 1 && dt.getDate() === d;
+}
+
+function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boolean): Args {
+  const a: Args = { command: "week", to: localDate(now), days: 7, date: null, explain: false, json: false, out: "zapara-card.png", projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR };
+  let days: number | null = null;
+  let jsonFlag = false;
+  let outGiven = false;
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    // A missing value or one that looks like another flag is a usage error,
+    // never treated as this flag's value (e.g. `--projects --json`).
+    const value = (): string => { const v = argv[++i]; if (v === undefined || v.startsWith("-")) throw new UsageError(`${arg} needs a value`); return v; };
+    switch (arg) {
+      case "--help":
+      case "-h": throw new HelpRequested();
+      case "--version": throw new VersionRequested();
+      case "--json": jsonFlag = true; break;
+      case "--explain": a.explain = true; break;
+      case "--no-color": a.color = false; break;
+      case "--projects": a.projects = value(); break;
+      case "--to": a.to = value(); break;
+      case "--days": { const v = value(); if (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 90) throw new UsageError(`--days must be 1..90, got ${v}`); days = Number(v); break; }
+      case "--out": a.out = value(); outGiven = true; break;
+      default:
+        if (arg.startsWith("-")) throw new UsageError(`unknown flag ${arg}`);
+        positional.push(arg);
+    }
+  }
+  const [cmd, ...rest] = positional;
+  if (cmd === undefined || cmd === "week") { if (rest.length) throw new UsageError(`unexpected argument ${rest[0]}`); a.command = "week"; }
+  else if (cmd === "day") { a.command = "day"; a.date = rest[0] ?? a.to; if (rest.length > 1) throw new UsageError(`unexpected argument ${rest[1]}`); }
+  else if (cmd === "card") { a.command = "card"; if (rest.length) throw new UsageError(`unexpected argument ${rest[0]}`); }
+  else throw new UsageError(`unknown command ${cmd}`);
+  // Two weeks make a pattern; a week makes a picture of one week.
+  a.days = days ?? (a.command === "card" ? 14 : 7);
+  // Tables turn into JSON in a pipe; the card is a file either way, so only an explicit --json switches it.
+  a.json = a.command === "card" ? jsonFlag : jsonFlag || !isTTY;
+  if (a.command !== "day" && a.explain) throw new UsageError("--explain applies to day only");
+  if (a.command !== "card" && outGiven) throw new UsageError("--out applies to card only");
+  // The value is printed back verbatim in `wrote …`, so it must be one plain line:
+  // no control character, and the message never quotes it.
+  if (/[\x00-\x1f\x7f]/.test(a.out)) throw new UsageError("--out must not contain control characters");
+  if (!/\.(png|webp|html)$/i.test(a.out)) throw new UsageError("--out must end in .png, .webp or .html");
+  if (!validDate(a.to)) throw new UsageError(`--to must be YYYY-MM-DD, got ${a.to}`);
+  if (a.date !== null && !validDate(a.date)) throw new UsageError(`date must be YYYY-MM-DD, got ${a.date}`);
+  return a;
+}
+
+async function main(): Promise<number> {
+  const argv = process.argv.slice(2);
+  const a = parseArgs(argv, new Date(), process.env, process.stdout.isTTY === true);
+  if (a.command === "card") return card(a);
+  const days: Day[] = a.command === "day"
+    ? await report({ projects: a.projects, to: a.date!, days: 1 })
+    : await report({ projects: a.projects, to: a.to, days: a.days });
+  const data = a.command === "day" ? days[0] : days;
+  if (a.json) console.log(renderJson(data!));
+  else if (a.command === "day") console.log(renderDay(days[0]!, { explain: a.explain, color: a.color }));
+  else console.log(renderWeek(days, a.color));
+  return 0;
+}
+
+async function card(a: Args): Promise<number> {
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days });
+  const data = cardData(days, { days: a.days });
+  if (data === null) throw new Error(`no activity in the last ${a.days} days`);
+  if (a.json) {
+    const round2 = (x: number): number => Math.round(x * 100) / 100;
+    const json = {
+      from: days[0]!.date, to: days[days.length - 1]!.date, days: data.days, character: data.character, name: data.name,
+      sentence: sentenceText(data.sentence), motto: data.motto,
+      shares: { conductor: round2(data.shares.conductor), supervisor: round2(data.shares.supervisor), marathoner: round2(data.shares.marathoner), nightOwl: round2(data.shares.nightOwl) },
+      peak: data.peak, spectrum: data.spectrum, highlights: data.highlights,
+    };
+    console.log(JSON.stringify(json, null, 2));
+    return 0;
+  }
+  await renderCard(cardHtml(data, await loadAssets()), a.out);
+  console.log(`${data.name}: ${sentenceText(data.sentence)}\nwrote ${a.out}`);
+  return 0;
+}
+
+if (import.meta.main) {
+  main().then((code) => process.exit(code), (e: unknown) => {
+    if (e instanceof HelpRequested) { console.log(USAGE); process.exit(0); }
+    if (e instanceof VersionRequested) {
+      try { console.log(version()); process.exit(0); }
+      catch (err) { console.error(`zapara: ${err instanceof Error ? err.message : String(err)}`); process.exit(1); }
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    if (e instanceof UsageError) { console.error(`zapara: ${msg}\n${USAGE}`); process.exit(2); }
+    console.error(`zapara: ${msg}`);
+    process.exit(1);
+  });
+}