clauddy 1.24.0 → 1.25.0

package/README.md

@@ -109,6 +109,35 @@ Other activities — **planning**, **researching**, **delegating**, **waiting**
 show up in the status line as they happen. When Claude goes quiet, the pet drops
 back to plain **working** / **idle**.
 
+## The pet talks
+
+Now and then the pet says something in a speech bubble. It only speaks when something changes, never on a timer, and it keeps quiet when it has nothing specific to say. Remarks are at least 10 minutes apart; the big moments can cut that line.
+
+| Moment | What it says (expanded) | Minimized | Blip |
+| --- | --- | --- | --- |
+| First launch of the day | _Good morning! Yesterday was your heaviest day this week, 12M tokens._ | _Morning! Big day yesterday._ | ✓ |
+| Session crosses your fire threshold | _Getting warm, 91% already. At this pace you'll run out in about 40m._ | _91%, getting warm!_ | ✓ |
+| The session window resets | _Fresh window! That was 34M tokens over 4h 12m, mostly editing code._ | _Fresh window! 34M last time._ | ✓ |
+| The session hits 100% | _That's the limit. I'll be back at 2:35 PM._ | _Maxed out till 2:35 PM._ | |
+| You're back after 2+ hours away | _Welcome back! You were gone 3h 12m. The session's at 12%._ | _Welcome back!_ | |
+| 90 minutes of unbroken work | _You've been at it for 1h 35m straight. Stretch break?_ | _Stretch break?_ | |
+| A new record day (30-day best) | _New record! 45M tokens today, your biggest day in a month._ | _New record: 45M!_ | |
+| Codex crosses fire, hits 100%, or resets | _Codex is at 91% now. It resets in 1h 12m._ | _Codex at 91%!_ | ✓ (fire, reset) |
+
+The greeting follows your clock (_Good morning_, _Good afternoon_, _Good evening_, or _Still up?_ before 5 AM) and appears once a day, and so does the record. The reset recap covers only what the pet actually saw, so if you launch it mid-session it says less. Click the bubble to dismiss it.
+
+### The voice
+
+Optionally the pet also **blips** as it talks: short chiptune notes, one per letter, generated live with Web Audio (square waves, no sound files). It blips faster and higher when it's on fire, slower and lower when it's sleepy. Only the headline moments blip (the ✓ rows above), because a sound on every remark wears out fast.
+
+Audio should never catch you off guard in a meeting:
+
+- **Off by default.** Turn it on under **⚙ Settings → voice → Chiptune voice** (you'll hear a sample).
+- **One-click mute.** While the voice is on, a 🔊 button sits in the title bar. Click it to mute for an hour, and again to unmute.
+- **Always silent** in menu-bar mode and while the pet is minimized.
+
+**Speech bubbles** can be switched off entirely in the same place. Try any remark from the terminal with `bunx clauddy say <kind>` ([see below](#play-with-the-pet)).
+
 ## Install
 
 **macOS (Apple Silicon)** is the first-class build. **Windows (x64)** and **Linux (x64)** work too. The `bunx`/`npx` route below runs on all of them today.
@@ -232,6 +261,9 @@ Settings saved from the UI live in `~/.claude-usage-monitor/config.json`, so you
   "activeThresholdMs": 20000, // "active" if Claude wrote to its logs within this window
   "sleepThresholdMs": 300000, // "sleeping" after this much idle time (5 min)
   "codex": { "enabled": false }, // set by Settings → Codex → Connect
+  "talk": true, // speech bubbles on transitions
+  "sound": false, // chiptune blips, opt-in
+  "soundMutedUntil": 0, // set by the 🔊 button: muted until this epoch ms
 }
 ```
 
@@ -248,6 +280,8 @@ bunx clauddy working     # 🍴 eats token coins
 bunx clauddy tired       # 🥵 maxed out
 bunx clauddy idle        # 🙂 calm
 bunx clauddy auto        # ↩️ back to your real usage
+bunx clauddy say         # 💬 a remark in the speech bubble
+bunx clauddy say fire    #    or a specific one: greeting, fire, reset, maxed, welcome, streak, record, codex
 ```
 
 Each state is written to the data dir the running widget watches, so it reacts
@@ -259,7 +293,7 @@ live. (Installed globally? Drop the `bunx`: `clauddy poke`. Working on the repo?
 - **`main.js`** — Electron main process: frameless, transparent, always-on-top window; polls usage; fires macOS notifications; watches `config.json` and `debug.json`.
 - **`usage.js`** — reads `~/.claude/projects/**/*.jsonl`, sums tokens per model/project/day, detects the rolling 5-hour session window, the working/sleeping status, and which activity (reading/editing/running/…) Claude is on from its latest tool use.
 - **`auth.js`** — OAuth login (PKCE, same public client as Claude Code) that fetches the authoritative usage %. Token stored locally, never committed.
-- **`renderer/`** — the pet itself: an SVG pixel sprite, CSS animations, and the Web Animations API for particles.
+- **`renderer/`** — the pet itself: an SVG pixel sprite, CSS animations, and the Web Animations API for particles. `voice.js` writes its remarks and synthesizes the blips.
 - **`make-icon.js`** — generates the app icon from the pixel sprite (`build/icon.icns`).
 
 ## Data & privacy

package/bin/clauddy.js

@@ -20,6 +20,7 @@ const STATES = [
   'idle',
   'poke',
   'celebrate',
+  'say',
   'auto',
   'clear',
   // activity states (what Claude Code is doing)
@@ -31,7 +32,10 @@ const STATES = [
   'delegating',
   'waiting',
 ]
+// `clauddy say <kind>` previews one of the pet's remarks
+const REMARKS = ['greeting', 'fire', 'reset', 'maxed', 'welcome', 'streak', 'record', 'codex']
 const arg = process.argv[2]
+const kind = arg === 'say' ? process.argv[3] || 'greeting' : undefined
 
 if (!arg) {
   // no argument → launch the app
@@ -47,19 +51,25 @@ if (!arg) {
       'Usage:',
       '  clauddy            launch the widget',
       '  clauddy <state>    poke the running widget (just for fun)',
+      '  clauddy say [kind] make the pet say one of its remarks',
       '',
       'States: fire, sleeping, working, tired, idle, poke, celebrate, auto',
+      `Remarks: ${REMARKS.join(', ')}`,
       '(the widget must be running for a state to show)',
     ].join('\n'),
   )
+} else if (kind && !REMARKS.includes(kind)) {
+  console.error(`clauddy: unknown remark "${kind}"`)
+  console.error(`try: ${REMARKS.join(', ')}`)
+  process.exit(1)
 } else if (STATES.includes(arg)) {
   // write the state for the running app to pick up
   fs.mkdirSync(dataDir, { recursive: true })
   fs.writeFileSync(
     path.join(dataDir, 'debug.json'),
-    `${JSON.stringify({ state: arg, t: Date.now() })}\n`,
+    `${JSON.stringify({ state: arg, kind, t: Date.now() })}\n`,
   )
-  console.log(`clauddy → ${arg} (the running widget will react)`)
+  console.log(`clauddy → ${arg}${kind ? ` ${kind}` : ''} (the running widget will react)`)
 } else {
   console.error(`clauddy: unknown command "${arg}"`)
   console.error('try: fire, sleeping, working, tired, idle, poke, celebrate, auto — or --help')

package/main.js

@@ -77,6 +77,9 @@ function publicConfig(c) {
     fireThreshold: c.fireThreshold,
     zoom: c.zoom,
     codex: !!c.codex?.enabled,
+    talk: c.talk,
+    sound: c.sound,
+    soundMutedUntil: c.soundMutedUntil,
   }
 }
 
@@ -92,6 +95,9 @@ function loadConfig() {
     fireThreshold: 90, // session % at which the pet catches fire (tired still fixed at 100)
     zoom: 100, // widget scale %, 100-200
     codex: { enabled: false }, // opt-in from Settings, never on by finding ~/.codex
+    talk: true, // speech bubbles on transitions
+    sound: false, // chiptune blips: opt-in, audio must never surprise anyone
+    soundMutedUntil: 0, // the one-click "mute for 1 hour", as an epoch ms
     pollIntervalMs: 4000,
     activeThresholdMs: 20000,
     sleepThresholdMs: 300000,
@@ -379,6 +385,9 @@ function createWindow() {
       preload: path.join(__dirname, 'preload.js'),
       contextIsolation: true,
       nodeIntegration: false,
+      // the pet's blips start from a usage change, never from a click, so
+      // Chromium would otherwise hold the AudioContext suspended
+      autoplayPolicy: 'no-user-gesture-required',
     },
   })
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clauddy",
   "desktopName": "clauddy.desktop",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "A cute desktop pet that tracks your Claude Code usage",
   "main": "main.js",
   "bin": {

package/renderer/index.html

@@ -33,6 +33,14 @@
             <circle cx="7" cy="7" r="3" />
           </svg>
         </button>
+        <button id="mute" title="Mute the voice for 1 hour" hidden>
+          <svg class="ic ic-sound" viewBox="0 0 24 24" aria-hidden="true">
+            <path d="M11 5 6 9H2v6h4l5 4Z" /><path d="M15.5 8.5a5 5 0 0 1 0 7M19 5a10 10 0 0 1 0 14" />
+          </svg>
+          <svg class="ic ic-muted" viewBox="0 0 24 24" aria-hidden="true">
+            <path d="M11 5 6 9H2v6h4l5 4Z" /><path d="m22 9-6 6M16 9l6 6" />
+          </svg>
+        </button>
         <button id="usage" title="Open Usage page">
           <svg class="ic" viewBox="0 0 24 24" aria-hidden="true">
             <path d="M7 7h10v10M7 17 17 7" />
@@ -146,6 +154,8 @@
           <div id="sweat"><i></i><i></i></div>
           <div id="dropzone"></div>
         </div>
+        <!-- the pet's remarks: only on transitions, never on a timer -->
+        <div id="bubble" role="status" aria-live="polite" hidden><span id="bubble-text"></span></div>
         <!-- editing mode, foreground: coffee mug in front of the pet -->
         <!-- mug: its own SVG with UNIFORM scaling (no stage stretch) so it stays perfectly shaped -->
         <svg id="mug" viewBox="0 0 46 44" preserveAspectRatio="xMidYMid meet" aria-hidden="true">
@@ -197,10 +207,10 @@
         <!-- Dual-service dock: two glanceable readings, one shared pet. -->
         <div id="mini-dual">
           <button type="button" class="mini-source" data-provider="claude">
-            <span>Claude</span><span class="mini-track"><i id="mini-claude-bar"></i></span><b id="mini-claude-value">—</b>
+            <svg class="mini-logo" viewBox="0 0 24 24" aria-hidden="true"><use href="#logo-claude" /></svg><span class="mini-source-name">Claude</span><span class="mini-track"><i id="mini-claude-bar"></i></span><b id="mini-claude-value">—</b>
           </button>
           <button type="button" class="mini-source" data-provider="codex">
-            <span>Codex</span><span class="mini-track"><i id="mini-codex-bar"></i></span><b id="mini-codex-value">—</b>
+            <svg class="mini-logo" viewBox="0 0 24 24" aria-hidden="true"><use href="#logo-openai" /></svg><span class="mini-source-name">Codex</span><span class="mini-track"><i id="mini-codex-bar"></i></span><b id="mini-codex-value">—</b>
           </button>
         </div>
         <div id="mini-reset" hidden></div>
@@ -380,6 +390,15 @@
             <span class="set-row-label">Zoom</span>
             <span class="num"><button type="button" class="num-btn" data-for="set-zoom" data-step="-25">−</button><span class="num-val"><input id="set-zoom" type="number" min="100" max="200" step="25" /><i>%</i></span><button type="button" class="num-btn" data-for="set-zoom" data-step="25">+</button></span>
           </div>
+          <div class="settings-label threshold-label">voice</div>
+          <div class="set-row">
+            <span class="set-row-label">Speech bubbles</span>
+            <input id="set-talk" class="set-toggle" type="checkbox" aria-label="Let the pet talk" />
+          </div>
+          <div class="set-row voice-sub">
+            <span class="set-row-label">Chiptune voice</span>
+            <input id="set-sound" class="set-toggle" type="checkbox" aria-label="Play blips when the pet talks" />
+          </div>
         </div>
 
         <div class="set-actions">
@@ -398,6 +417,7 @@
       </div>
     </div>
     <script src="burn.js"></script>
+<script src="voice.js"></script>
 <script src="pet.js"></script>
   </body>
 </html>

package/renderer/pet.js

@@ -471,6 +471,276 @@ function celebrate() {
   for (let i = 0; i < 24; i++) spawnConfetti(i)
 }
 
+// ---- voice ------------------------------------------------------------------
+// The bubble speaks on transitions only, at most once per REMARK_GAP_MS. The
+// headline moments (the day's first hello, a fresh window, catching fire) may
+// jump that queue, and only they blip: a noise on every remark wears out far
+// faster than the remark itself.
+const REMARK_GAP_MS = 10 * 60000
+const MUTE_MS = 60 * 60000
+const blipper = Voice.createBlipper(() => {
+  const AC = globalThis.AudioContext || globalThis.webkitAudioContext
+  return AC ? new AC() : null
+})
+let lastRemarkAt = 0
+let bubbleTimer = null
+
+const talkOn = () => currentConfig.talk !== false
+const mutedNow = () => currentConfig.soundMutedUntil > Date.now()
+// opt-in, and never where it would surprise someone: the menu-bar popover, the
+// mini face, or the hour after a mute
+function soundOn() {
+  if (!currentConfig.sound || currentConfig.mode === 'menubar') return false
+  if (document.body.classList.contains('collapsed')) return false
+  return !mutedNow()
+}
+
+function moodOf(st) {
+  return st === 'stressed' ? 'fire' : st === 'sleeping' || st === 'tired' ? 'sleepy' : 'normal'
+}
+
+// `line` is a remark from voice.js ({ text, short }) or a plain string. The
+// mini face has room for a glance, not a sentence, so it gets the short one.
+// `force` is the simulator's: it skips the gates but still respects the mute
+function say(line, { headline = false, mood = 'normal', force = false } = {}) {
+  if (!line) return false
+  const collapsed = document.body.classList.contains('collapsed')
+  const text = typeof line === 'string' ? line : collapsed ? line.short : line.text
+  if (!force) {
+    const b = document.body.classList
+    if (!talkOn() || b.contains('settings-open')) return false
+    if (!headline && Date.now() - lastRemarkAt < REMARK_GAP_MS) return false
+  }
+  lastRemarkAt = Date.now()
+  const bubble = el('bubble')
+  el('bubble-text').textContent = text
+  bubble.classList.remove('leaving')
+  placeBubble()
+  bubble.hidden = false
+  fitSize() // collapsed, the bubble is in the flow: the window grows to fit it
+  clearTimeout(bubbleTimer)
+  bubbleTimer = setTimeout(hideBubble, Math.max(4500, text.length * 70 + 2500))
+  // the mouth moves along, whether or not there's sound
+  for (let i = 0; i < Math.min(4, Math.ceil(text.length / 18)); i++) setTimeout(chomp, i * 260)
+  if ((headline || force) && soundOn()) blipper.play(text, mood)
+  return true
+}
+
+// expanded, the bubble floats over the scene beside the pet; collapsed there's
+// no room beside it, so it moves above the pet, into the card's flow
+function placeBubble() {
+  const bubble = el('bubble')
+  const stage = el('stage')
+  if (document.body.classList.contains('collapsed')) {
+    if (bubble.nextElementSibling !== stage) stage.before(bubble)
+  } else if (bubble.parentElement !== stage) stage.appendChild(bubble)
+}
+
+function hideBubble() {
+  clearTimeout(bubbleTimer)
+  const bubble = el('bubble')
+  if (bubble.hidden) return
+  bubble.classList.add('leaving')
+  bubbleTimer = setTimeout(() => {
+    bubble.hidden = true
+    bubble.classList.remove('leaving')
+    fitSize()
+  }, 180)
+}
+el('bubble').addEventListener('click', (e) => {
+  e.stopPropagation()
+  hideBubble()
+})
+
+// once-a-day remarks, keyed by local date; memory is the fallback when storage
+// isn't there, so a broken profile can't make the pet repeat itself
+const toldMemo = {}
+const dayKey = () => new Date().toDateString()
+function toldToday(key) {
+  try {
+    if (localStorage.getItem(key) === dayKey()) return true
+  } catch {}
+  return toldMemo[key] === dayKey()
+}
+function markToday(key) {
+  toldMemo[key] = dayKey()
+  try {
+    localStorage.setItem(key, dayKey())
+  } catch {}
+}
+
+// what the pet has noticed so far — the transitions are all relative to it
+const AWAY_MS = 2 * 3600000
+const STREAK_MS = 90 * 60000
+const STREAK_GAP_MS = 10 * 60000
+let greeted = false
+let heardConfig = false
+let lastLivePct = null // Claude's session %, null until a live reading lands
+let awayMs = 0
+let streakFrom = 0
+let lastWorkAt = 0
+let streakTold = false
+
+// what the current Claude window has been like, for the recap when it closes
+// (#31). The peak is the session's tokens just before the rollover — after it
+// the counter starts over. Only the time the pet actually watched counts.
+const TALLY_GAP_MS = 15000 // a longer gap is the machine asleep, not work
+let tally = { peak: 0, activeMs: 0, acts: {}, at: 0 }
+function noteSession(d) {
+  const now = Date.now()
+  const dt = tally.at ? Math.min(now - tally.at, TALLY_GAP_MS) : 0
+  tally.at = now
+  if (d.active) {
+    tally.activeMs += dt
+    if (d.activity) tally.acts[d.activity] = (tally.acts[d.activity] || 0) + dt
+  }
+  tally.peak = Math.max(tally.peak, d.session?.tokens || 0)
+}
+function takeRecap(was) {
+  const top = Object.entries(tally.acts).sort((a, b) => b[1] - a[1])[0]?.[0] || null
+  const r = { was, tokens: tally.peak, activeMs: tally.activeMs, top }
+  tally = { peak: 0, activeMs: 0, acts: {}, at: tally.at }
+  return r
+}
+
+// Codex, followed whichever tab is on screen. Its logs only move while it
+// runs, so a stale reading keeps the baseline: the next fresh one is compared
+// against the last number actually seen.
+let lastCodexPct = null
+function listenCodex() {
+  const c = codexData
+  if (!codexOn() || !c) {
+    lastCodexPct = null
+    return
+  }
+  const pct = c.session?.pct
+  if (pct == null || codexStale(c)) return
+  const was = lastCodexPct
+  lastCodexPct = pct
+  if (was == null) return
+  const fireAt = currentConfig.fireThreshold ?? 90
+  const reset = c.session.resetMs
+  if (was - pct > 25) say(Voice.codexResetLine(was), { headline: true })
+  else if (was < 100 && pct >= 100)
+    say(Voice.codexMaxedLine(fmtResetClock(reset)), { mood: 'sleepy' })
+  else if (was < fireAt && pct >= fireAt && pct < 100)
+    say(Voice.codexFireLine(pct, reset, fmtReset), { headline: true, mood: 'fire' })
+}
+
+// called by paint() with the state it just drew. The Claude remarks follow the
+// Claude view; Codex has its own, above.
+function listen(before, st, { isCodex, liveOn, sp, sessReset, proj }) {
+  // the saved config decides whether it talks at all, and it lands just after
+  // the first usage tick: speaking before it would ignore a "talk: false"
+  if (!heardConfig) return
+  const d = lastData
+  const mood = moodOf(st)
+  if (!greeted) {
+    greeted = true
+    if (!toldToday('clauddy.greeted')) {
+      markToday('clauddy.greeted')
+      const line = Voice.greetingLine(d.days30, new Date().getHours(), fmtTokens)
+      if (say(line, { headline: true, mood })) return
+    }
+  }
+  listenCodex()
+  if (isCodex) return
+  const now = Date.now()
+
+  if (liveOn) {
+    const fireAt = currentConfig.fireThreshold ?? 90
+    const was = lastLivePct
+    lastLivePct = sp
+    // a first reading is a baseline: launching at 95% is not "catching fire"
+    if (was != null && was < 100 && sp >= 100) {
+      say(Voice.maxedLine(fmtResetClock(sessReset)), { mood: 'sleepy' })
+    } else if (was != null && was < fireAt && sp >= fireAt && sp < 100) {
+      const eta = proj?.kind === 'eta' ? proj.ms : null
+      say(Voice.fireLine(sp, eta, sessReset, fmtReset), { headline: true, mood: 'fire' })
+    }
+  } else {
+    lastLivePct = null // logged out, or switching: the next reading starts over
+  }
+
+  if (st === 'sleeping' && Number.isFinite(d.lastActivityMs))
+    awayMs = Math.max(awayMs, d.lastActivityMs)
+  else if (before === 'sleeping') {
+    if (awayMs >= AWAY_MS) say(Voice.welcomeLine(awayMs, liveOn ? sp : null, fmtReset))
+    awayMs = 0
+  }
+
+  if (st === 'working') {
+    if (!streakFrom || now - lastWorkAt > STREAK_GAP_MS) {
+      streakFrom = now
+      streakTold = false
+    }
+    lastWorkAt = now
+    if (!streakTold && now - streakFrom >= STREAK_MS)
+      streakTold = say(Voice.streakLine(now - streakFrom, fmtReset))
+  }
+
+  const record = Voice.recordLine(d.days30, fmtTokens)
+  if (record && !toldToday('clauddy.record') && say(record, { mood })) markToday('clauddy.record')
+}
+
+// `./pet say <kind>` previews one remark — real numbers where there are some,
+// plausible ones where the moment hasn't happened
+function sampleLine(kind) {
+  const days = lastData?.days30?.length ? [...lastData.days30] : new Array(30).fill(0)
+  const pct = realUsage?.session?.pct
+  const reset = realUsage?.session?.resetMs ?? 72 * 60000
+  if (kind === 'fire') return Voice.fireLine(Math.max(pct ?? 0, 91), 40 * 60000, reset, fmtReset)
+  if (kind === 'reset') {
+    const t = tally.peak ? tally : { peak: 34e6, activeMs: 4 * 3600000 + 12 * 60000, acts: {} }
+    const top = Object.entries(t.acts).sort((a, b) => b[1] - a[1])[0]?.[0] || 'editing'
+    return Voice.recapLine(
+      { was: 92, tokens: t.peak, activeMs: t.activeMs, top },
+      fmtTokens,
+      fmtReset,
+    )
+  }
+  if (kind === 'codex')
+    return Voice.codexFireLine(91, codexData?.session?.resetMs ?? reset, fmtReset)
+  if (kind === 'maxed') return Voice.maxedLine(fmtResetClock(reset))
+  if (kind === 'welcome') return Voice.welcomeLine(3 * 3600000 + 12 * 60000, pct ?? null, fmtReset)
+  if (kind === 'streak') return Voice.streakLine(95 * 60000, fmtReset)
+  if (kind === 'record') {
+    days[days.length - 1] = Math.max(2e6, Math.max(...days.slice(0, -1)) * 1.15)
+    return Voice.recordLine(days, fmtTokens)
+  }
+  if (!days[days.length - 2]) days[days.length - 2] = 12e6 // no yesterday yet: pretend one
+  return Voice.greetingLine(days, new Date().getHours(), fmtTokens)
+}
+function sayDebug(kind) {
+  const st = [...document.body.classList].find((c) => c.startsWith('state-'))?.slice(6)
+  const mood =
+    kind === 'fire' || kind === 'codex' ? 'fire' : kind === 'maxed' ? 'sleepy' : moodOf(st)
+  return say(sampleLine(kind), { force: true, mood })
+}
+
+// mute sits in the title bar while the voice is on: one click before a call
+let unmuteTimer = null
+function paintMute() {
+  const btn = el('mute')
+  // menu-bar mode is always silent, so there is nothing there to mute
+  btn.hidden = !(currentConfig.sound && talkOn()) || currentConfig.mode === 'menubar'
+  document.body.classList.toggle('has-mute', !btn.hidden) // the chip makes room for it
+  const muted = mutedNow()
+  btn.classList.toggle('muted', muted)
+  btn.title = muted
+    ? `Muted until ${new Date(currentConfig.soundMutedUntil).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })} — click to unmute`
+    : 'Mute the voice for 1 hour'
+  clearTimeout(unmuteTimer)
+  if (muted) unmuteTimer = setTimeout(paintMute, currentConfig.soundMutedUntil - Date.now() + 50)
+}
+el('mute').addEventListener('click', (e) => {
+  e.stopPropagation()
+  const until = mutedNow() ? 0 : Date.now() + MUTE_MS
+  currentConfig = { ...currentConfig, soundMutedUntil: until } // repaint now, main confirms
+  paintMute()
+  window.api.saveConfig({ soundMutedUntil: until })
+})
+
 // ---- services ---------------------------------------------------------------
 // Claude and Codex are monitored side by side, but the panel shows one at a
 // time: the tabs under the pet pick which one owns the chip, the pet, the
@@ -635,6 +905,7 @@ const prevPct = {} // per service: a switch must not read as a reset
 let lastData = null
 function render(d) {
   lastData = d
+  noteSession(d)
   // the burn trail is Claude's, fed on every Claude tick whatever is on screen
   const cl = realUsage
   burn.note(d.session.tokens, !!cl && cl.session.resetMs != null)
@@ -697,6 +968,7 @@ function paint() {
   for (const a of acts) {
     document.body.classList.toggle(`act-${a}`, st === 'working' && curActivity === a)
   }
+  const before = prevState
   if (prevState && prevState !== st) {
     if (st === 'sleeping') oneShot('drowse', 700)
     else if (prevState === 'sleeping') oneShot('wake', 700)
@@ -721,7 +993,11 @@ function paint() {
       : `${fmtTokens(d.today.tokens)} tokens today`
 
   const was = prevPct[view]
-  if (liveOn && was != null && sessActive && sessPct != null && was - sessPct > 25) celebrate()
+  if (liveOn && was != null && sessActive && sessPct != null && was - sessPct > 25) {
+    celebrate()
+    // Codex's own reset is called out by listenCodex, on screen or not
+    if (!isCodex) say(Voice.recapLine(takeRecap(was), fmtTokens, fmtReset), { headline: true })
+  }
   prevPct[view] = sessPct
   el('session-pct').textContent = pctText(liveOn ? sessPct : 0)
   setLevel(el('session-pct'), liveOn ? sp : 0)
@@ -786,6 +1062,7 @@ function paint() {
     stopEating()
   }
 
+  listen(before, st, { isCodex, liveOn, sp, sessReset, proj })
   fitSize()
 }
 
@@ -824,6 +1101,7 @@ window.api.onDebugState((o) => {
   const s = o?.state
   if (s === 'poke') return pokePet()
   if (s === 'celebrate') return celebrate()
+  if (s === 'say') return sayDebug(o.kind)
   debugState = s === 'auto' || s === 'clear' || !s ? null : s
   if (lastData) render(lastData)
 })
@@ -837,6 +1115,8 @@ window.api.onConfig((cfg) => {
   document.body.classList.toggle('is-menubar', currentConfig.mode === 'menubar')
   document.body.classList.toggle('codex-on', !!currentConfig.codex)
   if (!currentConfig.codex) codexData = null
+  heardConfig = true
+  paintMute()
   paint()
   applyZoom(currentConfig.zoom)
   fitSize()
@@ -1307,6 +1587,8 @@ function snapshotSettings() {
     t2: el('set-t2').value,
     fire: el('set-fire').value,
     zoom: el('set-zoom').value,
+    talk: el('set-talk').checked,
+    sound: el('set-sound').checked,
   })
 }
 function refreshSaveDirty() {
@@ -1325,6 +1607,9 @@ function clearSaveDirty() {
 function reflectAlertsOn() {
   el('set-rows').classList.toggle('alerts-off', !el('set-alerts').checked)
 }
+function reflectTalkOn() {
+  el('set-rows').classList.toggle('talk-off', !el('set-talk').checked)
+}
 // zoom applies as you step it, so the widget shows the size right away;
 // Cancel puts the saved value back
 function previewZoom() {
@@ -1344,9 +1629,13 @@ function populateSettings() {
   el('set-t2').value = th[1] != null ? th[1] : 95
   el('set-fire').value = c.fireThreshold != null ? c.fireThreshold : 90
   el('set-zoom').value = c.zoom != null ? c.zoom : 100
+  el('set-talk').checked = c.talk !== false
+  el('set-sound').checked = !!c.sound
+  reflectTalkOn()
   clearSaveDirty() // fields now match the saved config
 }
 function openSettings() {
+  hideBubble()
   document.body.classList.remove('collapsed')
   populateSettings()
   document.body.classList.add('settings-open')
@@ -1388,11 +1677,24 @@ for (const b of document.querySelectorAll('.num-btn')) {
   })
 }
 // light up Save whenever an editable field changes
-for (const id of ['set-alerts', 'set-t1', 'set-t2', 'set-fire', 'set-zoom']) {
+for (const id of [
+  'set-alerts',
+  'set-t1',
+  'set-t2',
+  'set-fire',
+  'set-zoom',
+  'set-talk',
+  'set-sound',
+]) {
   el(id).addEventListener('input', refreshSaveDirty)
   el(id).addEventListener('change', refreshSaveDirty)
 }
 el('set-alerts').addEventListener('change', reflectAlertsOn)
+el('set-talk').addEventListener('change', reflectTalkOn)
+// turning the voice on plays a sample, so you hear what you just agreed to
+el('set-sound').addEventListener('change', () => {
+  if (el('set-sound').checked) blipper.play('Hello there!')
+})
 el('set-zoom').addEventListener('input', previewZoom)
 // display-mode segmented control (floating pet | menu bar)
 for (const b of document.querySelectorAll('#set-mode .seg-btn')) {
@@ -1417,17 +1719,21 @@ el('set-save').addEventListener('click', () => {
       .sort((a, b) => a - b),
     fireThreshold: fire >= 1 && fire <= 99 ? fire : 90,
     zoom,
+    talk: el('set-talk').checked,
+    sound: el('set-sound').checked,
   })
   clearSaveDirty()
   document.body.classList.remove('settings-open')
   fitSize()
 })
 el('min').addEventListener('click', () => {
+  hideBubble()
   document.body.classList.toggle('collapsed')
   fitSize()
 })
 // double-click the pet to collapse / expand
 el('pet').addEventListener('dblclick', () => {
+  hideBubble()
   document.body.classList.toggle('collapsed')
   fitSize()
 })
@@ -1476,5 +1782,9 @@ if (typeof module === 'object' && module.exports) {
     paint,
     pickProvider,
     burn,
+    say,
+    hideBubble,
+    soundOn,
+    blipper,
   }
 }

package/renderer/style.css

@@ -1100,7 +1100,10 @@ body:not(.live) #bymodel {
   border: 1px solid rgba(206, 146, 109, 0.22);
   border-radius: 7px;
   background: rgba(206, 146, 109, 0.055);
-  padding: 10px 11px;
+  /* the same breathing room the meters get, so it never touches the tabs
+     above it or the Details rule below */
+  margin: 12px 0;
+  padding: 12px 13px;
   cursor: pointer;
   -webkit-app-region: no-drag;
   transition:
@@ -2429,13 +2432,21 @@ body.collapsed.dual #mini-acct-name {
   max-width: 112px;
   font-size: 10px;
 }
+
+/* The mood sits beneath the pet, level with the selected source reset. */
 body.collapsed.dual .mini-line {
-  justify-content: flex-start;
-  margin: 0 0 5px 3px;
+  position: absolute;
+  bottom: 12px;
+  left: 12px;
+  width: 66px;
+  justify-content: center;
+  margin: 0;
+  gap: 5px;
 }
 body.collapsed.dual #mini-text {
-  font-size: 10px;
+  font-size: 9px;
   font-weight: 400;
+  color: #b9afa3;
 }
 body.collapsed.dual #mini-dot {
   width: 4px;
@@ -2443,67 +2454,97 @@ body.collapsed.dual #mini-dot {
 }
 body.collapsed.dual #mini-dual {
   display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 8px;
+  grid-template-columns: 1fr;
+  gap: 5px;
 }
 .mini-source {
+  --src: #e4a17c;
+  position: relative;
   display: grid;
-  grid-template-columns: 1fr;
-  gap: 3px;
+  grid-template-columns: 12px minmax(0, 1fr) auto;
+  align-items: center;
+  column-gap: 5px;
+  row-gap: 4px;
   min-width: 0;
-  padding: 4px 6px;
+  min-height: 29px;
+  padding: 3px 0 3px 5px;
   border: 0;
-  border-radius: 5px;
+  border-radius: 4px;
   background: transparent;
-  color: #aba59d;
+  color: #aaa298;
   text-align: left;
   font: inherit;
   font-size: 10px;
   cursor: pointer;
   -webkit-app-region: no-drag;
+  transition: color 0.15s;
 }
-.mini-source:hover {
-  background: #ffffff08;
+.mini-source[data-provider="codex"] {
+  --src: #b9c8b0;
 }
-.mini-source[aria-pressed="true"] > span:first-child {
-  color: #eee4d9;
+.mini-logo {
+  grid-column: 1;
+  grid-row: 1;
+  width: 12px;
+  height: 12px;
+  fill: currentColor;
 }
-/* the selected service gets the tab's tinted plate; the other steps back */
-.mini-source[aria-pressed="false"] {
-  opacity: 0.5;
+.mini-source-name {
+  grid-column: 2;
+  grid-row: 1;
 }
-.mini-source[aria-pressed="false"]:hover {
-  opacity: 0.8;
+/* Selection uses contrast; urgent readings retain their warning color. */
+.mini-source[aria-pressed="false"] .mini-track i {
+  opacity: 0.55;
 }
-.mini-source[data-provider="claude"][aria-pressed="true"] {
-  background: #d977571c;
+.mini-source[aria-pressed="false"]:hover .mini-track i,
+.mini-source.urgent .mini-track i {
+  opacity: 1;
 }
-.mini-source[data-provider="codex"][aria-pressed="true"] {
-  background: #a7baa11c;
+.mini-source[aria-pressed="true"] {
+  color: #eee4d9;
+}
+.mini-source[aria-pressed="true"] .mini-logo {
+  color: var(--src);
+}
+.mini-source:hover {
+  color: #fff4e8;
+}
+.mini-source:hover .mini-logo {
+  color: var(--src);
 }
 .mini-source b {
-  grid-row: 2;
-  font-size: 18px;
+  grid-column: 3;
+  grid-row: 1;
+  font-size: 15px;
   line-height: 1.1;
   letter-spacing: -0.4px;
   font-weight: 500;
-  color: #eee4d9;
+  color: inherit;
   font-variant-numeric: tabular-nums;
 }
 .mini-source.urgent b {
   color: #f3a38b;
 }
-.mini-source.urgent > span:first-child::after {
+.mini-source.urgent .mini-source-name::after {
   content: " !";
   color: #f3a38b;
 }
 .mini-track {
-  grid-row: 3;
+  grid-column: 2 / -1;
+  grid-row: 2;
   height: 2px;
   border-radius: 2px;
   overflow: hidden;
   background: #ffffff0d;
 }
+body.collapsed.dual #mini-reset {
+  text-align: right;
+  margin-top: 7px;
+  font-size: 8px;
+  color: #b4a18a;
+}
+
 .mini-track i {
   display: block;
   height: 100%;
@@ -2578,11 +2619,19 @@ body.view-codex .mrow .mname::before {
 body.view-codex .ac-caret {
   display: none;
 }
+/* keyboard focus: a soft inner glow in the brand coral rather than a detached
+   cream ring — still visible, but it reads as the control lighting up */
 #card button:focus-visible,
 #card input:focus-visible,
 #account-chip:focus-visible {
-  outline: 2px solid #c9bda6;
-  outline-offset: 2px;
+  outline: none;
+  box-shadow:
+    inset 0 0 0 1px #e6a07f8c,
+    0 0 0 3px #d977571f;
+}
+#controls button:focus-visible {
+  background: rgba(255, 255, 255, 0.1);
+  color: #fff;
 }
 @media (prefers-reduced-motion: reduce) {
   #card,
@@ -2790,3 +2839,184 @@ body.awaiting #acc-intro.connection-card {
 .claude-connect-btn:hover {
   background: #ce926d33;
 }
+
+/* ---- voice: speech bubble + mute ---- */
+/* the bubble speaks the sprite's language: square pixels, a notched 2px
+   outline (no radius), a stepped tail aimed at the pet's head, small type */
+#bubble {
+  --ink: #221b16;
+  --paper: #f1e9dd;
+  position: absolute;
+  left: 84px;
+  top: 16px;
+  z-index: 4;
+  max-width: 148px;
+  padding: 5px 7px 6px;
+  background: var(--paper);
+  color: var(--ink);
+  font:
+    600 9px / 1.35 ui-monospace,
+    "SF Mono",
+    Menlo,
+    monospace;
+  letter-spacing: -0.01em;
+  /* four offset edges instead of a border: the corners stay open, like a sprite */
+  box-shadow:
+    0 -2px 0 0 var(--ink),
+    0 2px 0 0 var(--ink),
+    -2px 0 0 0 var(--ink),
+    2px 0 0 0 var(--ink),
+    2px 4px 0 0 #0006;
+  cursor: pointer;
+  -webkit-app-region: no-drag;
+  transform-origin: 0% 100%;
+  animation: bubble-pop 0.18s steps(3, end);
+}
+#bubble[hidden] {
+  display: none;
+}
+/* the tail: a stepped right triangle hanging off the bottom-left edge, aimed
+   down at the pet. The ink one is the outline; the paper one sits 2px inside it
+   and starts on the outline row, so the bubble opens into the tail */
+#bubble::before,
+#bubble::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+}
+#bubble::before {
+  left: 8px;
+  width: 14px;
+  height: 12px;
+  background: var(--ink);
+  clip-path: polygon(
+    0 0,
+    14px 0,
+    14px 2px,
+    12px 2px,
+    12px 4px,
+    10px 4px,
+    10px 6px,
+    8px 6px,
+    8px 8px,
+    6px 8px,
+    6px 10px,
+    4px 10px,
+    4px 12px,
+    0 12px
+  );
+}
+#bubble::after {
+  left: 10px;
+  width: 10px;
+  height: 10px;
+  background: var(--paper);
+  clip-path: polygon(
+    0 0,
+    10px 0,
+    10px 2px,
+    8px 2px,
+    8px 4px,
+    6px 4px,
+    6px 6px,
+    4px 6px,
+    4px 8px,
+    2px 8px,
+    2px 10px,
+    0 10px
+  );
+}
+#bubble.leaving {
+  animation: bubble-out 0.15s steps(2, end) forwards;
+}
+@keyframes bubble-pop {
+  from {
+    transform: scale(0.5);
+    opacity: 0;
+  }
+  to {
+    transform: scale(1);
+    opacity: 1;
+  }
+}
+@keyframes bubble-out {
+  to {
+    transform: scale(0.8);
+    opacity: 0;
+  }
+}
+body.settings-open #bubble {
+  display: none;
+}
+/* collapsed: above the pet, in the card's flow, tail pointing straight down */
+body.collapsed #bubble {
+  position: relative;
+  left: auto;
+  top: auto;
+  max-width: none;
+  margin: 6px 2px 14px;
+  grid-column: 1 / -1;
+  transform-origin: 50% 100%;
+}
+/* one service: the card has no title band, so clear the window controls, and
+   hug the short line instead of spanning the whole card */
+body.collapsed:not(.dual) #bubble {
+  align-self: center;
+  margin-top: 26px;
+  text-align: center;
+}
+body.collapsed.dual #bubble {
+  justify-self: start;
+}
+body.collapsed #bubble::before {
+  left: calc(50% - 7px);
+}
+body.collapsed #bubble::after {
+  left: calc(50% - 5px);
+}
+/* with both services the pet sits in the left column: aim there */
+body.collapsed.dual #bubble::before {
+  left: 24px;
+}
+body.collapsed.dual #bubble::after {
+  left: 26px;
+}
+
+#controls button[hidden] {
+  display: none;
+}
+/* a fifth button pushes #controls ~23px left: the account chip gives that up.
+   Minimized is always silent, so the button (and the squeeze) go away there */
+body.has-mute #account-chip {
+  max-width: 141px;
+}
+body.collapsed #mute {
+  display: none;
+}
+#mute .ic-muted,
+#mute.muted .ic-sound {
+  display: none;
+}
+#mute.muted .ic-muted {
+  display: block;
+}
+#mute.muted {
+  color: var(--coral-soft);
+}
+
+.set-row.voice-sub .set-row-label {
+  font-weight: 400;
+  font-size: 10.5px;
+  color: var(--muted);
+}
+#set-rows.talk-off .voice-sub {
+  opacity: 0.35;
+  pointer-events: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  #bubble,
+  #bubble.leaving {
+    animation: none;
+  }
+}

package/renderer/voice.js

@@ -0,0 +1,243 @@
+// ---- the pet's voice ----
+// Two channels. The bubble carries the meaning: a short remark, only on a
+// transition, and only when there's something specific to say — a pet that
+// talks on a timer is Clippy. The sound carries the personality: chiptune
+// blips, one square-wave note per letter, Animal Crossing style. Oscillators
+// only, so no assets, no dependency, and no language baked into the sound.
+;(() => {
+  const BASE_HZ = 400
+  const SPREAD_HZ = 250
+  const STEP_MS = 115
+  const MAX_BLIPS = 14 // a sentence is a babble, not a recital
+  const GAIN = 0.05
+
+  // the tone doubles as state: hot is faster and higher, sleepy slower and lower
+  const MOODS = {
+    normal: { speed: 1, pitch: 1 },
+    fire: { speed: 0.72, pitch: 1.25 },
+    sleepy: { speed: 1.35, pitch: 0.8 },
+  }
+
+  // letters and digits each get a fixed pitch, so the same word always sounds
+  // the same; anything else is a rest
+  function pitchOf(ch) {
+    const c = ch.toLowerCase()
+    if (c >= 'a' && c <= 'z') return BASE_HZ + ((c.charCodeAt(0) - 97) / 25) * SPREAD_HZ
+    if (c >= '0' && c <= '9') return BASE_HZ + ((c.charCodeAt(0) - 48) / 9) * SPREAD_HZ
+    return null
+  }
+
+  // the schedule for a line: [{ at, hz, dur }] in ms, pure so it can be tested
+  function blipPlan(text, mood = 'normal') {
+    const m = MOODS[mood] || MOODS.normal
+    const step = STEP_MS * m.speed
+    const plan = []
+    let t = 0
+    for (const ch of String(text)) {
+      if (plan.length >= MAX_BLIPS) break
+      const hz = pitchOf(ch)
+      if (hz != null) {
+        plan.push({ at: Math.round(t), hz: Math.round(hz * m.pitch), dur: Math.round(step * 0.6) })
+        t += step
+      } else if (/[.,!?—:;]/.test(ch)) {
+        t += step * 1.5 // a breath on punctuation
+      } else if (ch === ' ') {
+        t += step * 0.4
+      }
+    }
+    return plan
+  }
+
+  // `makeCtx` builds the AudioContext lazily: creating one up front would hold
+  // an audio device open for a pet that, by default, never makes a sound
+  function createBlipper(makeCtx) {
+    let ctx = null
+    return {
+      play(text, mood) {
+        try {
+          ctx = ctx || makeCtx()
+          if (!ctx) return 0
+          if (ctx.state === 'suspended') ctx.resume?.()
+          const plan = blipPlan(text, mood)
+          const t0 = ctx.currentTime + 0.02
+          for (const b of plan) {
+            const start = t0 + b.at / 1000
+            const end = start + b.dur / 1000
+            const osc = ctx.createOscillator()
+            const gain = ctx.createGain()
+            osc.type = 'square'
+            osc.frequency.setValueAtTime(b.hz, start)
+            // a quick attack and decay, or every note clicks
+            gain.gain.setValueAtTime(0, start)
+            gain.gain.linearRampToValueAtTime(GAIN, start + 0.008)
+            gain.gain.exponentialRampToValueAtTime(0.0001, end)
+            osc.connect(gain)
+            gain.connect(ctx.destination)
+            osc.start(start)
+            osc.stop(end + 0.01)
+          }
+          return plan.length
+        } catch {
+          return 0 // no audio device, or a context the OS took away: stay quiet
+        }
+      },
+    }
+  }
+
+  // ---- remarks ----
+  // Each returns { text, short }, or null when there's nothing worth saying.
+  // `text` is a full, spoken sentence for the scene; `short` is the glance the
+  // mini face has room for. Numbers arrive preformatted through `fmt` / `fmtDur`
+  // so this file stays free of the widget.
+  const line = (text, short) => ({ text, short: short || text })
+
+  // the small hours get their own hello: "Good morning!" at 2am rings false
+  const LATE_UNTIL = 5
+  function salutation(hour) {
+    if (hour < LATE_UNTIL) return 'Still up?'
+    return hour < 12 ? 'Good morning!' : hour < 18 ? 'Good afternoon!' : 'Good evening!'
+  }
+  function hello(hour) {
+    if (hour < LATE_UNTIL) return 'Up late!'
+    return hour < 12 ? 'Morning!' : hour < 18 ? 'Afternoon!' : 'Evening!'
+  }
+
+  // `days` is the 30-day series, oldest first, today last
+  function greetingLine(days, hour, fmt) {
+    if (!Array.isArray(days) || days.length < 2) return null
+    const y = days[days.length - 2]
+    if (!y) return null
+    const week = days.slice(-8, -1) // the seven days before today, yesterday included
+    const worked = week.filter((v) => v > 0)
+    const hi = salutation(hour)
+    const short = `${hello(hour)} ${fmt(y)} yesterday.`
+    if (worked.length > 1 && y >= Math.max(...week))
+      return line(
+        `${hi} Yesterday was your heaviest day this week, ${fmt(y)} tokens.`,
+        `${hello(hour)} Big day yesterday.`,
+      )
+    const avg = worked.reduce((n, v) => n + v, 0) / (worked.length || 1)
+    if (worked.length > 2 && y < avg * 0.5)
+      return line(`${hi} Yesterday was a quiet one, just ${fmt(y)} tokens.`, short)
+    return line(`${hi} You spent ${fmt(y)} tokens yesterday.`, short)
+  }
+
+  function fireLine(pct, etaMs, resetMs, fmtDur) {
+    const p = Math.round(pct)
+    if (etaMs != null)
+      return line(
+        `Getting warm, ${p}% already. At this pace you'll run out in about ${fmtDur(etaMs)}.`,
+        `${p}%, getting warm!`,
+      )
+    if (resetMs != null)
+      return line(
+        `Getting warm, ${p}% already. It resets in ${fmtDur(resetMs)}.`,
+        `${p}%, getting warm!`,
+      )
+    return line(`Getting warm, ${p}% already.`, `${p}%, getting warm!`)
+  }
+
+  function resetLine(was) {
+    return line(`Fresh window! The last one closed at ${Math.round(was)}%.`, 'Fresh window!')
+  }
+
+  // what each activity was, said the way you'd say it
+  const DOING = {
+    editing: 'mostly editing code',
+    reading: 'mostly reading',
+    planning: 'mostly planning',
+    running: 'mostly running commands',
+    researching: 'mostly researching',
+    delegating: 'mostly delegating to agents',
+    waiting: 'mostly waiting on you',
+  }
+
+  // the recap of the window that just closed (#31), built from whatever is
+  // known, so a pet launched mid-session still says something true
+  function recapLine({ was, tokens, activeMs, top }, fmt, fmtDur) {
+    if (!(tokens > 0)) return resetLine(was ?? 0)
+    let text = `Fresh window! That was ${fmt(tokens)} tokens`
+    if (activeMs >= 60000) text += ` over ${fmtDur(activeMs)}`
+    if (DOING[top]) text += `, ${DOING[top]}`
+    return line(`${text}.`, `Fresh window! ${fmt(tokens)} last time.`)
+  }
+
+  // Codex speaks through the same pet, so its lines always say whose they are
+  function codexFireLine(pct, resetMs, fmtDur) {
+    const p = Math.round(pct)
+    const text =
+      resetMs != null
+        ? `Codex is at ${p}% now. It resets in ${fmtDur(resetMs)}.`
+        : `Codex is at ${p}% now.`
+    return line(text, `Codex at ${p}%!`)
+  }
+  function codexMaxedLine(resetAt) {
+    return line(
+      resetAt ? `Codex is maxed out. It's back at ${resetAt}.` : 'Codex is maxed out.',
+      'Codex is maxed out.',
+    )
+  }
+  function codexResetLine(was) {
+    return line(
+      `Codex has a fresh window! The last one closed at ${Math.round(was)}%.`,
+      'Codex: fresh window!',
+    )
+  }
+
+  function maxedLine(resetAt) {
+    return resetAt
+      ? line(`That's the limit. I'll be back at ${resetAt}.`, `Maxed out till ${resetAt}.`)
+      : line("That's the limit. Nap time.", 'Maxed out.')
+  }
+
+  function welcomeLine(awayMs, pct, fmtDur) {
+    const away = fmtDur(awayMs)
+    const text =
+      pct != null
+        ? `Welcome back! You were gone ${away}. The session's at ${Math.round(pct)}%.`
+        : `Welcome back! You were gone ${away}.`
+    return line(text, 'Welcome back!')
+  }
+
+  function streakLine(ms, fmtDur) {
+    return line(`You've been at it for ${fmtDur(ms)} straight. Stretch break?`, 'Stretch break?')
+  }
+
+  // a record only counts against a real history, and past a floor that makes
+  // it more than noise
+  const RECORD_FLOOR = 1e6
+  function recordLine(days, fmt) {
+    if (!Array.isArray(days) || days.length < 8) return null
+    const today = days[days.length - 1]
+    const before = days.slice(0, -1)
+    const best = Math.max(...before)
+    if (best <= 0 || today < RECORD_FLOOR || today <= best) return null
+    return line(
+      `New record! ${fmt(today)} tokens today, your biggest day in a month.`,
+      `New record: ${fmt(today)}!`,
+    )
+  }
+
+  const api = {
+    BASE_HZ,
+    SPREAD_HZ,
+    STEP_MS,
+    MAX_BLIPS,
+    pitchOf,
+    blipPlan,
+    createBlipper,
+    greetingLine,
+    fireLine,
+    resetLine,
+    recapLine,
+    codexFireLine,
+    codexMaxedLine,
+    codexResetLine,
+    maxedLine,
+    welcomeLine,
+    streakLine,
+    recordLine,
+  }
+  if (typeof module === 'object' && module.exports) module.exports = api
+  else globalThis.Voice = api
+})()