Show counter values over time in pq counter info

Add an "over time" section that splits the current view into time buckets,
so a counter's trajectory is visible rather than only an aggregate. Each
slice shows the graph-type-appropriate value (level and delta for
accumulated counters, the amount for rate counters), its share of the
range, and a CO2e estimate where the schema requests one. Values reuse the
tooltip formatters and ts-N time names, matching the timeline.

A fixed-width sparkline of the trajectory is drawn alongside, in both
`counter info` and `counter list`.

Closes #6112

Author: fatadel

profiler-cli/guide.txt

@@ -224,7 +224,7 @@ COUNTERS
   network bandwidth, process CPU, power, and similar. Each counter has a handle
   (c-0, c-1, ...) and carries its own display metadata (label, unit, graph type).
 
-    profiler-cli counter list            List all counters with one-line summaries
+    profiler-cli counter list            List all counters, each with a sparkline
     profiler-cli counter info c-0        Detailed info and stats for one counter
 
   Counters also appear in "profile info", listed under their owning process
@@ -235,6 +235,14 @@ COUNTERS
   memory range for Memory, data transferred for Bandwidth, or energy used (with a
   CO2e estimate) for Power.
 
+  "counter info" also prints an "over time" section that splits the current view
+  into time buckets, so you can see when a counter's value changed - for any
+  counter, in its own unit. What each slice shows follows the counter's graph
+  type: accumulated counters (e.g. Memory) show the level and its change, rate
+  counters (e.g. Bandwidth, Power) show the amount in the slice. Each slice also
+  shows its share of the range, and a sparkline draws the trajectory above them.
+  "counter list" shows a sparkline next to each counter as well.
+
   All counter stats respect the current zoom: with no zoom they cover the whole
   profile; after "zoom push" they cover the committed range. Combine with zoom to
   see, for example, how much memory a specific time window allocated:

profiler-cli/schemas.txt

@@ -32,7 +32,8 @@ CounterSummary:
     unit, graphType,
     color, pid, mainThreadIndex, mainThreadHandle, mainThreadName,
     rangeSampleCount,
-    stats: [{ source, label, value, formattedValue, carbon? }]
+    stats: [{ source, label, value, formattedValue, carbon? }],
+    graph: [number]
   }
 
 profiler-cli counter list --json
@@ -49,6 +50,10 @@ profiler-cli counter info --json
     description,
     sampleCount,
     rangeStart, rangeEnd,
+    overTime: [{ startTime, startTimeName, startTimeStr,
+                 endTime, endTimeName, endTimeStr,
+                 value, formattedValue, delta?, formattedDelta?,
+                 percentage?, formattedPercentage?, carbon? }],
     context: SessionContext
   }
 

profiler-cli/src/formatters.ts

@@ -490,8 +490,42 @@ export function formatCounterListResult(
   if (result.counters.length === 0) {
     return `${contextHeader}\n\nNo counters in this profile.`;
   }
-  const lines = result.counters.map(formatCounterSummaryLine);
-  return `${contextHeader}\n\nCounters (${result.counters.length}):\n${lines.join('\n')}`;
+  const blocks = result.counters.map((counter) => {
+    const block = [formatCounterSummaryLine(counter)];
+    if (counter.graph.length > 0) {
+      block.push(`      ${renderSparkline(counter.graph)}`);
+    }
+    return block.join('\n');
+  });
+  // Trailing blank line so the last counter's sparkline is separated from the
+  // prompt, matching the blank lines between counters.
+  return `${contextHeader}\n\nCounters (${result.counters.length}):\n${blocks.join('\n\n')}\n`;
+}
+
+const SPARKLINE_CHARS = '▁▂▃▄▅▆▇█';
+
+/**
+ * Render a compact sparkline of the given values using block characters.
+ * Heights are normalized across the series (min..max); a flat series renders
+ * at a mid-height rather than the floor so it doesn't read as zero.
+ */
+function renderSparkline(values: number[]): string {
+  if (values.length === 0) {
+    return '';
+  }
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const range = max - min;
+  const lastIndex = SPARKLINE_CHARS.length - 1;
+  if (range === 0) {
+    return SPARKLINE_CHARS[Math.floor(lastIndex / 2)].repeat(values.length);
+  }
+  return values
+    .map((value) => {
+      const index = Math.round(((value - min) / range) * lastIndex);
+      return SPARKLINE_CHARS[index];
+    })
+    .join('');
 }
 
 /**
@@ -534,6 +568,36 @@ export function formatCounterInfoResult(
       lines.push(`    ${stat.label}: ${value}`);
     }
   }
+  if (result.overTime.length > 0) {
+    lines.push(`  ${result.label} over time:`);
+    if (result.graph.length > 0) {
+      lines.push(`    ${renderSparkline(result.graph)}`);
+      lines.push('');
+    }
+    // Build the columns first, then pad each to its widest cell so the values
+    // line up in a column.
+    const rows = result.overTime.map((bucket) => {
+      const extras = [
+        bucket.formattedDelta,
+        bucket.formattedPercentage,
+        bucket.carbon,
+      ].filter((part) => part !== undefined);
+      return {
+        handles: `[${bucket.startTimeName} → ${bucket.endTimeName}]`,
+        times: `(${bucket.startTimeStr} - ${bucket.endTimeStr})`,
+        value: bucket.formattedValue,
+        extras: extras.length > 0 ? `(${extras.join(', ')})` : '',
+      };
+    });
+    const handlesWidth = Math.max(...rows.map((row) => row.handles.length));
+    const timesWidth = Math.max(...rows.map((row) => row.times.length));
+    const valueWidth = Math.max(...rows.map((row) => row.value.length));
+    for (const row of rows) {
+      lines.push(
+        `    ${row.handles.padEnd(handlesWidth)}  ${row.times.padEnd(timesWidth)}  ${row.value.padEnd(valueWidth)}  ${row.extras}`.trimEnd()
+      );
+    }
+  }
   return lines.join('\n');
 }
 

profiler-cli/src/test/unit/counter-formatting.test.ts

@@ -46,6 +46,7 @@ function makeCounter(overrides: Partial<CounterSummary> = {}): CounterSummary {
         formattedValue: '27B',
       },
     ],
+    graph: [],
     ...overrides,
   };
 }
@@ -95,6 +96,19 @@ describe('formatCounterListResult', function () {
       'No counters in this profile.'
     );
   });
+
+  it('renders a sparkline next to each counter', function () {
+    const result: WithContext<CounterListResult> = {
+      context: createContext(),
+      type: 'counter-list',
+      counters: [makeCounter({ graph: [1, 5, 9] })],
+    };
+
+    const output = formatCounterListResult(result);
+    expect(output).toContain('c-0: Memory (Memory)');
+    expect(output).toContain('▁'); // lowest graph value
+    expect(output).toContain('█'); // highest graph value
+  });
 });
 
 describe('formatCounterInfoResult', function () {
@@ -109,6 +123,7 @@ describe('formatCounterInfoResult', function () {
       sampleCount: 7,
       rangeStart: 0,
       rangeEnd: 10,
+      overTime: [],
       ...overrides,
     };
   }
@@ -147,4 +162,81 @@ describe('formatCounterInfoResult', function () {
       'Energy used in the visible range: 5 Wh (2 g CO₂e)'
     );
   });
+
+  it('renders the over-time section with level and delta', function () {
+    const output = formatCounterInfoResult(
+      makeInfo({
+        overTime: [
+          {
+            startTime: 0,
+            startTimeName: 'ts-0',
+            startTimeStr: '0s',
+            endTime: 5,
+            endTimeName: 'ts-K',
+            endTimeStr: '5ms',
+            value: 2_100_000,
+            formattedValue: '2.1 MB',
+            delta: 2_100_000,
+            formattedDelta: '+2.1 MB',
+            percentage: 0.25,
+            formattedPercentage: '25%',
+          },
+          {
+            startTime: 5,
+            startTimeName: 'ts-K',
+            startTimeStr: '5ms',
+            endTime: 10,
+            endTimeName: 'ts-Z',
+            endTimeStr: '10ms',
+            value: 8_400_000,
+            formattedValue: '8.4 MB',
+            delta: 6_300_000,
+            formattedDelta: '+6.3 MB',
+            percentage: 1,
+            formattedPercentage: '100%',
+          },
+        ],
+      })
+    );
+    expect(output).toContain('Memory over time:');
+    // Columns are padded for alignment, so allow variable whitespace between them.
+    expect(output).toMatch(
+      /\[ts-0 → ts-K\]\s+\(0s - 5ms\)\s+2\.1 MB\s+\(\+2\.1 MB, 25%\)/
+    );
+    expect(output).toMatch(
+      /\[ts-K → ts-Z\]\s+\(5ms - 10ms\)\s+8\.4 MB\s+\(\+6\.3 MB, 100%\)/
+    );
+  });
+
+  function makeBucket(
+    value: number,
+    index: number
+  ): CounterInfoResult['overTime'][number] {
+    return {
+      startTime: index,
+      startTimeName: `ts-${index}`,
+      startTimeStr: `${index}ms`,
+      endTime: index + 1,
+      endTimeName: `ts-${index + 1}`,
+      endTimeStr: `${index + 1}ms`,
+      value,
+      formattedValue: `${value}B`,
+    };
+  }
+
+  it('renders a sparkline from the graph values', function () {
+    const output = formatCounterInfoResult(
+      makeInfo({ overTime: [makeBucket(1, 0)], graph: [1, 5, 9] })
+    );
+    expect(output).toContain('Memory over time:');
+    expect(output).toContain('▁'); // lowest graph value
+    expect(output).toContain('█'); // highest graph value
+  });
+
+  it('omits the sparkline when the graph is empty', function () {
+    const output = formatCounterInfoResult(
+      makeInfo({ overTime: [makeBucket(1, 0)], graph: [] })
+    );
+    expect(output).not.toMatch(/[▁▂▃▄▅▆▇█]/);
+  });
 });