@brimveyn/aimux 1.22.12 → 1.23.0

package/src/ui/components/stats/heatmap.tsx

@@ -0,0 +1,305 @@
+import type { BoxRenderable, MouseEvent, RGBA } from '@opentui/core'
+
+import { useCallback, useMemo, useRef, useState } from 'react'
+
+import {
+  buildHeatmap,
+  coveredWeeks,
+  type HeatmapCell,
+  mixColor,
+  monthLabels,
+  promptCounts,
+} from '../../../services/usage-history/stats'
+import { localDay, type UsageDays } from '../../../services/usage-history/store'
+import { useTheme } from '../../theme'
+import { dayDetails, DayFacts, DayPanel, PANEL_WIDTH } from './day-facts'
+
+/**
+ * The activity calendar.
+ *
+ * A cell is `md-square_rounded`, a filled rounded square that fills its
+ * terminal cell. Unicode has no filled rounded square — `▢` U+25A2 is an
+ * outline — so this is a nerd-font glyph, like the status bar's round separator.
+ *
+ * One hue, light to dark, because the only thing a cell encodes is magnitude.
+ * A hue per month grouped the calendar prettily but spent the colour channel on
+ * something the month labels already say, and it borrowed the status colours,
+ * which on this page mean a quota is running out.
+ */
+
+/** nf-md-square_rounded. Needs a nerd font, and measures one cell wide. */
+const CELL = '\u{F14FB}'
+/** The glyph plus its gap — the stride one day occupies. */
+const CELL_WIDTH = 2
+const BLANK = ' '.repeat(CELL_WIDTH)
+const LABEL_WIDTH = 5
+
+const ROW_LABELS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const
+/** A constant, not an inline attribute: a JSX string does not process `\u` escapes. */
+const CHEVRON = '\u{00BB}'
+const RULE = '\u{2500}'
+
+/** Rows the grid draws above the first weekday: the month header and its rule. */
+const HEADER_ROWS = 2
+/** The box's own border and padding on the left. */
+const BOX_INSET = 2
+/** Between the calendar and the day panel beside it. */
+const PANEL_GAP = 2
+type Ramp = (RGBA | string)[]
+
+/** Light to dark on one hue, over the neutral an unrecorded day keeps. */
+function rampOf(empty: string, hue: string): Ramp {
+  return [
+    empty,
+    mixColor(empty, hue, 0.35),
+    mixColor(empty, hue, 0.6),
+    mixColor(empty, hue, 0.82),
+    hue,
+  ]
+}
+
+export function useHeatmapRamp(): Ramp {
+  const t = useTheme()
+  // borderSubtle rather than a background token: backgrounds resolve to alpha 0
+  // in transparent mode, which would erase the empty days entirely.
+  return useMemo(() => rampOf(t.borderSubtle, t.primary), [t.borderSubtle, t.primary])
+}
+
+export function HeatmapLegend({ ramp }: { ramp: Ramp }) {
+  const t = useTheme()
+  return (
+    <box flexDirection="row" flexShrink={0}>
+      <text fg={t.textMuted} selectable={false} wrapMode="none">
+        {'Less '}
+      </text>
+      {ramp.map((color, index) => (
+        <text key={String(color) + String(index)} fg={color} selectable={false} wrapMode="none">
+          {`${CELL} `}
+        </text>
+      ))}
+      <text fg={t.textMuted} selectable={false} wrapMode="none">
+        More
+      </text>
+    </box>
+  )
+}
+
+function Gutter({ label }: { label: string }) {
+  const t = useTheme()
+  return (
+    <box width={LABEL_WIDTH} flexShrink={0}>
+      <text fg={t.textMuted} selectable={false} wrapMode="none">
+        {label}
+      </text>
+    </box>
+  )
+}
+
+function HeatRow({
+  cells,
+  label,
+  ramp,
+  selected,
+}: {
+  cells: HeatmapCell[]
+  label: string
+  ramp: Ramp
+  selected: number
+}) {
+  const t = useTheme()
+
+  // One <text> per colour run, not per cell: a year is 371 of them.
+  const runs: { color: RGBA | string; start: number; text: string }[] = []
+  for (const [index, cell] of cells.entries()) {
+    let color: RGBA | string = ''
+    if (cell.day !== '') {
+      color = index === selected ? t.text : (ramp[cell.level] ?? t.borderSubtle)
+    }
+    const glyph = cell.day === '' ? BLANK : `${CELL} `
+    const last = runs.at(-1)
+    // The selected cell always starts its own run, so it keeps its own colour.
+    if (last !== undefined && last.color === color && index !== selected) last.text += glyph
+    else runs.push({ color, start: index, text: glyph })
+  }
+
+  return (
+    <box flexDirection="row" flexShrink={0}>
+      <Gutter label={label} />
+      {runs.map((run) =>
+        run.color === '' ? (
+          <text key={run.start} selectable={false} wrapMode="none">
+            {run.text}
+          </text>
+        ) : (
+          <text key={run.start} fg={run.color} selectable={false} wrapMode="none">
+            {run.text}
+          </text>
+        )
+      )}
+    </box>
+  )
+}
+
+/** Month names over the columns they occupy. */
+function MonthHeader({ grid, weeks }: { grid: HeatmapCell[][]; weeks: number }) {
+  const t = useTheme()
+  const labels = monthLabels(grid, weeks, CELL_WIDTH)
+
+  let cursor = 0
+  const parts: string[] = []
+  for (const label of labels) {
+    parts.push(' '.repeat(Math.max(0, label.offset - cursor)), label.name)
+    cursor = label.offset + label.name.length
+  }
+
+  return (
+    <box flexDirection="row" flexShrink={0}>
+      <Gutter label={CHEVRON} />
+      <text fg={t.textMuted} selectable={false} wrapMode="none">
+        {parts.join('')}
+      </text>
+    </box>
+  )
+}
+
+interface Selection {
+  column: number
+  key: string
+  row: number
+}
+
+/**
+ * How many weeks the grid draws in `width` columns.
+ *
+ * Bounded by what is recorded: empty months predating the first rollup read as
+ * broken, not as history.
+ */
+function weeksFor(days: UsageDays, today: Date, width: number): number {
+  // Less the day-name column and the box's own border and padding, so the grid
+  // sizes to what is actually left inside it.
+  const usable = Math.max(CELL_WIDTH, width - LABEL_WIDTH - 4)
+  return coveredWeeks(days, today, Math.max(4, Math.min(53, Math.floor(usable / CELL_WIDTH))))
+}
+
+/**
+ * The columns the calendar's box actually occupies.
+ *
+ * The section's legend is pinned to this rather than to the pane, so it sits
+ * over the grid's own top-right corner: the calendar is as wide as the history
+ * is long, and a legend flush with the far edge of the page belongs to nothing
+ * the eye can see.
+ */
+export function heatmapWidth(days: UsageDays, today: Date, width: number): number {
+  return BOX_INSET * 2 + LABEL_WIDTH + weeksFor(days, today, width) * CELL_WIDTH
+}
+
+export function Heatmap({
+  days,
+  ramp,
+  summary,
+  today,
+  width,
+}: {
+  days: UsageDays
+  ramp: Ramp
+  /** What the whole calendar says, above the day the pointer is on. */
+  summary?: string
+  today: Date
+  width: number
+}) {
+  const t = useTheme()
+  const boxRef = useRef<BoxRenderable | null>(null)
+  const [selected, setSelected] = useState<Selection | null>(null)
+
+  const weeks = weeksFor(days, today, width)
+  const grid = buildHeatmap(promptCounts(days), weeks, today)
+
+  /**
+   * The grid is a fixed pitch, so where the pointer is is arithmetic rather
+   * than a hit test: one handler beats a handler on each of 371 cells, and the
+   * cells stay batched into colour runs for rendering.
+   *
+   * Movement rather than clicks. Reading a day was a mode — open the popover,
+   * read it, dismiss it — for numbers that take a second to scan, and the box
+   * covered the month it was describing. Following the pointer has no state to
+   * open or to get stuck in, and scanning a week is a sweep rather than a dozen
+   * clicks. Mouse-down runs the same path so the readout still answers a click,
+   * which is what a terminal without motion reporting will send.
+   */
+  const handlePoint = useCallback(
+    (event: MouseEvent) => {
+      const box = boxRef.current
+      if (box === null) return
+      const row = event.y - box.y - HEADER_ROWS - 1
+      const column = Math.floor((event.x - box.x - BOX_INSET - LABEL_WIDTH) / CELL_WIDTH)
+      const key = grid[row]?.[column]?.day
+      // A cell with no day behind it — the future, or before the first rollup —
+      // leaves the last one up rather than blanking the slot as the pointer
+      // crosses it.
+      if (key == null || key === '') return
+      setSelected((current) => (current?.key === key ? current : { column, key, row }))
+    },
+    [grid]
+  )
+
+  // Today until the pointer says otherwise: the slot is worth its rows from the
+  // moment the page opens, and today is the day a reader wants first.
+  const shown = selected?.key ?? localDay(today)
+  const details = useMemo(() => dayDetails(shown, days[shown]), [days, shown])
+
+  // The calendar is bounded by what has been recorded, so it usually leaves
+  // room to its right. The panel goes there when it fits, and drops to running
+  // lines underneath when it does not.
+  const beside = width - heatmapWidth(days, today, width) - PANEL_GAP >= PANEL_WIDTH
+
+  return (
+    <box flexDirection="column" flexShrink={0} alignSelf="flex-start">
+      <box flexDirection="row" flexShrink={0}>
+        <box
+          ref={boxRef}
+          border
+          borderStyle="rounded"
+          borderColor={t.border}
+          paddingLeft={1}
+          paddingRight={1}
+          flexDirection="column"
+          flexShrink={0}
+          onMouseDown={handlePoint}
+          onMouseMove={handlePoint}
+        >
+          <MonthHeader grid={grid} weeks={weeks} />
+          <box flexDirection="row" flexShrink={0}>
+            <Gutter label="" />
+            <text fg={t.borderSubtle} selectable={false} wrapMode="none">
+              {RULE.repeat(weeks * CELL_WIDTH)}
+            </text>
+          </box>
+          {grid.map((cells, index) => (
+            <HeatRow
+              key={ROW_LABELS[index]}
+              cells={cells}
+              label={ROW_LABELS[index] ?? ''}
+              ramp={ramp}
+              selected={selected?.row === index ? selected.column : -1}
+            />
+          ))}
+        </box>
+        {beside ? (
+          <>
+            <box width={PANEL_GAP} flexShrink={0} />
+            <DayPanel details={details} />
+          </>
+        ) : null}
+      </box>
+      {summary == null || summary === '' ? null : (
+        <text fg={t.textMuted} selectable={false} wrapMode="none">
+          {summary}
+        </text>
+      )}
+      {/* Below only when it could not go beside. The date line is the only
+          bright text down here, so the year and the day never read as one
+          paragraph. */}
+      {beside ? null : <DayFacts details={details} width={width} />}
+    </box>
+  )
+}

package/src/ui/components/stats/projects-page.tsx

@@ -0,0 +1,293 @@
+import { dayCost, formatUsd } from '../../../services/usage-history/cost'
+import {
+  lastDays,
+  lateNightPrompts,
+  meanOf,
+  peakDay,
+  projectTotals,
+  SESSION_BUCKETS,
+  sessionLengths,
+  sessionStats,
+  streaks,
+  totalMean,
+} from '../../../services/usage-history/insights'
+import { summarizeDays } from '../../../services/usage-history/stats'
+import { formatCompact } from '../../format-number'
+import { chartColumns } from './chart'
+import { formatCount, formatDayLabel, formatDuration, shortenPath, weeklyLabels } from './format'
+import {
+  BarRow,
+  GLYPH,
+  Muted,
+  pageLayout,
+  PageNotice,
+  type PageTile,
+  recordsOf,
+  RecordsSection,
+  Section,
+  StatsPage,
+  TwoColumn,
+  VBarChart,
+} from './shared'
+import { isEmpty, type StatsData } from './use-stats-data'
+
+/**
+ * Projects — where the work went and what a session looks like.
+ *
+ * Usage answers "how much"; this page answers "on what, and in what shape". The
+ * session-length bars are the reason it exists: a median says where the middle
+ * is, and the middle is the least interesting thing about a day made of one long
+ * session or of twenty two-minute ones.
+ */
+
+/** Tall enough to read a week off, short enough to sit beside a list of bars. */
+const CHART_HEIGHT = 7
+
+/**
+ * The median session length, or why it is zero.
+ *
+ * `formatDuration` renders nothing-at-all as an em dash, which is right for a
+ * missing measurement and wrong here: with thousands of single-prompt sessions
+ * the median really is zero, and "—" would report the most interesting fact on
+ * the page as an absence of data.
+ */
+function medianLabel(count: number, medianMs: number): string {
+  if (count === 0) return '\u{2014}'
+  return medianMs <= 0 ? '< 1 min' : formatDuration(medianMs)
+}
+
+function projectTiles(
+  projects: number,
+  branches: number,
+  sessions: number,
+  typical: string
+): PageTile[] {
+  return [
+    { glyph: GLYPH.projects, label: 'Projects', value: formatCount(projects) },
+    { glyph: GLYPH.branches, label: 'Branches', value: formatCount(branches) },
+    { glyph: GLYPH.sessions, label: 'Sessions', value: formatCount(sessions) },
+    { glyph: GLYPH.clock, label: 'Typical', value: typical },
+  ]
+}
+
+export function ProjectsPage({ data, width }: { data: StatsData; width: number }) {
+  // First, before the derivations it would make pointless.
+  if (isEmpty(data.claude)) {
+    return <PageNotice>no history yet — the first rollup runs in the background</PageNotice>
+  }
+
+  const { split, usable } = pageLayout(width)
+  const { leftWidth, rightWidth } = split
+
+  const projects = projectTotals(data.claude, 8)
+  const summary = summarizeDays(data.claude)
+  const sessions = sessionStats(data.claude)
+  const lengths = sessionLengths(data.claude)
+  const promptChars = totalMean(data.claude, (day) => day.promptChars)
+  const turns = totalMean(data.claude, (day) => day.turnMs)
+  const streak = streaks(data.claude, data.todayDate)
+
+  const projectMax = projects.entries[0]?.[1] ?? 0
+  const branchMax = summary.branches[0]?.[1] ?? 0
+  const lengthMax = Math.max(...lengths, 0)
+  const perDay = sessions.days === 0 ? 0 : sessions.count / sessions.days
+
+  const chartDays = chartColumns(rightWidth - 8)
+  const daily = lastDays(
+    data.claude,
+    chartDays,
+    data.todayDate,
+    (day) => Object.keys(day.sessions).length
+  )
+  const chartLabels = weeklyLabels(chartDays, data.todayDate)
+
+  const busiest = peakDay(data.claude, (day) => day.prompts)
+  const richest = peakDay(data.claude, (day) => day.tokens.total)
+  const priciest = peakDay(data.claude, (day) => dayCost(day).total)
+  const lateNight = lateNightPrompts(data.claude)
+
+  // Only records that exist. A row of `—` teaches nothing and reads as broken.
+  const records = recordsOf([
+    busiest.value === 0
+      ? null
+      : {
+          label: 'Busiest day',
+          value: `${formatCount(busiest.value)} prompts`,
+          when: formatDayLabel(busiest.day),
+        },
+    streak.longest === 0
+      ? null
+      : { label: 'Longest streak', value: `${streak.longest} days`, when: '' },
+    sessions.longestMs === 0
+      ? null
+      : {
+          label: 'Longest session',
+          value: formatDuration(sessions.longestMs),
+          when: formatDayLabel(sessions.longestDay),
+        },
+    richest.value === 0
+      ? null
+      : {
+          label: 'Most tokens',
+          value: `${formatCompact(richest.value)} in a day`,
+          when: formatDayLabel(richest.day),
+        },
+    priciest.value === 0
+      ? null
+      : {
+          label: 'Priciest day',
+          value: `${formatUsd(priciest.value)} est.`,
+          when: formatDayLabel(priciest.day),
+        },
+    promptChars.max === 0
+      ? null
+      : { label: 'Longest prompt', value: `${formatCount(promptChars.max)} chars`, when: '' },
+    lateNight === 0
+      ? null
+      : {
+          label: 'Late nights',
+          value: `${formatCount(lateNight)} prompts`,
+          when: 'between 02:00 and 05:00',
+        },
+  ])
+
+  const left = (
+    <>
+      <Section
+        glyph={GLYPH.projects}
+        title="Projects"
+        note={projects.entries.length === 0 ? '' : `${formatCount(projects.total)} prompts`}
+        width={leftWidth}
+      >
+        {projects.entries.length === 0 ? (
+          <Muted>recorded from the next rollup onward</Muted>
+        ) : (
+          projects.entries.map(([path, value]) => (
+            <BarRow
+              key={path}
+              label={shortenPath(path)}
+              max={projectMax}
+              value={value}
+              valueText={formatCount(value)}
+              width={leftWidth}
+            />
+          ))
+        )}
+      </Section>
+
+      <Section
+        glyph={GLYPH.sessions}
+        title="Session length"
+        note={
+          sessions.count === 0 ? '' : `median ${medianLabel(sessions.count, sessions.medianMs)}`
+        }
+        width={leftWidth}
+      >
+        {sessions.count === 0 ? (
+          <Muted>recorded from the next rollup onward</Muted>
+        ) : (
+          <>
+            {SESSION_BUCKETS.map((label, index) => (
+              <BarRow
+                key={label}
+                label={label}
+                max={lengthMax}
+                value={lengths[index] ?? 0}
+                valueText={formatCount(lengths[index] ?? 0)}
+                width={leftWidth}
+              />
+            ))}
+            <Muted>
+              {[
+                `longest ${formatDuration(sessions.longestMs)}`,
+                sessions.singlePrompt === 0
+                  ? ''
+                  : `${formatCount(sessions.singlePrompt)} one-prompt`,
+                turns.count === 0 ? '' : `average turn ${formatDuration(meanOf(turns))}`,
+              ]
+                .filter((part) => part !== '')
+                .join(' \u{00B7} ')}
+            </Muted>
+          </>
+        )}
+      </Section>
+    </>
+  )
+
+  const right = (
+    <>
+      <Section
+        glyph={GLYPH.branches}
+        title="Branches"
+        note={summary.branchTotal === 0 ? '' : `${formatCompact(summary.branchTotal)} tokens`}
+        width={rightWidth}
+      >
+        {summary.branches.length === 0 ? (
+          <Muted>no branch attribution recorded</Muted>
+        ) : (
+          summary.branches.map(([branch, value]) => (
+            <BarRow
+              key={branch}
+              label={branch}
+              max={branchMax}
+              value={value}
+              valueText={formatCompact(value)}
+              width={rightWidth}
+            />
+          ))
+        )}
+      </Section>
+
+      <Section
+        glyph={GLYPH.calendar}
+        title="Sessions a day"
+        note={sessions.count === 0 ? '' : `${perDay.toFixed(1)} on an active day`}
+        width={rightWidth}
+      >
+        {sessions.count === 0 ? (
+          <Muted>recorded from the next rollup onward</Muted>
+        ) : (
+          <>
+            <VBarChart
+              caption={`last ${chartDays} days`}
+              height={CHART_HEIGHT}
+              labels={chartLabels}
+              values={daily}
+            />
+            <Muted>
+              {[
+                `${formatCount(sessions.count)} over ${formatCount(sessions.days)} days`,
+                promptChars.count === 0 ? '' : `${formatCount(meanOf(promptChars))} chars a prompt`,
+              ]
+                .filter((part) => part !== '')
+                .join(' \u{00B7} ')}
+            </Muted>
+          </>
+        )}
+      </Section>
+    </>
+  )
+
+  return (
+    <StatsPage
+      tiles={projectTiles(
+        projects.entries.length,
+        summary.branches.length,
+        sessions.count,
+        medianLabel(sessions.count, sessions.medianMs)
+      )}
+      usable={usable}
+    >
+      <TwoColumn split={split}>
+        {left}
+        {right}
+      </TwoColumn>
+
+      <RecordsSection
+        empty="nothing to beat yet — records appear as history accumulates"
+        records={records}
+        width={usable}
+      />
+    </StatsPage>
+  )
+}