@hienlh/ppm 0.18.7 → 0.18.9

package/src/web/components/system/process-row-format.ts

@@ -0,0 +1,56 @@
+/** Formatting helpers for a single process row, salvaged from the deleted
+ *  `system-monitor-group-row.tsx` byte-for-byte (same thresholds, same rounding).
+ *  Grid template logic (which columns exist, the `@lg` trend/age track) now lives
+ *  in `process-columns-grid.ts` since it grew a runtime dependency (enabled
+ *  optional columns + active sort key) that no longer fits a static constant. */
+import { formatBps, formatRam } from "@/lib/format-bytes";
+
+export function cpuColor(cpu: number): string {
+  if (cpu > 80) return "text-error";
+  if (cpu > 50) return "text-warning";
+  return "text-success";
+}
+
+export function formatAge(startedAt?: number): string {
+  if (!startedAt) return "";
+  const secs = Math.round((Date.now() - startedAt) / 1000);
+  if (secs < 60) return `${secs}s`;
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ${mins % 60}m`;
+  const days = Math.floor(hrs / 24);
+  return `${days}d ${hrs % 24}h`;
+}
+
+/** `undefined` on both sides means the host cannot measure this metric for this
+ *  row at all (contract: `undefined` = OS/tier cannot measure) — render an em
+ *  dash rather than a misleading "0 B/s". A single defined side (e.g. read known,
+ *  write not) still renders, treating the missing side as 0. */
+export function formatDiskCell(readBps?: number, writeBps?: number): string {
+  if (readBps === undefined && writeBps === undefined) return "—";
+  return `↓ ${formatBps(readBps ?? 0)} ↑ ${formatBps(writeBps ?? 0)}`;
+}
+
+export function formatNetCell(inBps?: number, outBps?: number): string {
+  if (inBps === undefined && outBps === undefined) return "—";
+  return `↓ ${formatBps(inBps ?? 0)} ↑ ${formatBps(outBps ?? 0)}`;
+}
+
+/** GPU % and VRAM are measured independently on some platforms (e.g. NVIDIA
+ *  consumer drivers on Linux only expose per-process memory, not per-process
+ *  utilization) — each half renders its own dash when unmeasured. */
+export function formatGpuCell(pct?: number, memMB?: number): string {
+  if (pct === undefined && memMB === undefined) return "—";
+  const pctText = pct === undefined ? "—" : `${pct.toFixed(0)}%`;
+  const memText = memMB === undefined ? "—" : formatRam(memMB);
+  return `${pctText} · ${memText}`;
+}
+
+/** Row-level `data-*` sort attribute for e2e/debugging: sums a disk or net pair
+ *  into one comparable number, `undefined` only when NEITHER side is measured —
+ *  same rule the sort comparator and the cell formatters use. */
+export function sumOptionalBps(a?: number, b?: number): number | undefined {
+  if (a === undefined && b === undefined) return undefined;
+  return (a ?? 0) + (b ?? 0);
+}

package/src/web/components/system/process-row.tsx

@@ -0,0 +1,82 @@
+import { X } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { formatRam } from "@/lib/format-bytes";
+import { cpuColor, formatAge, formatDiskCell, formatGpuCell, formatNetCell, sumOptionalBps } from "./process-row-format";
+import { optionalCellClassName, type ProcessGridResult } from "./process-columns-grid";
+import type { ProcessInfo } from "../../../types/system-metrics";
+
+const PROTECTED_TOOLTIP = "Protected: PPM or OS-critical process — cannot be ended.";
+
+export interface ProcessRowProps {
+  proc: ProcessInfo;
+  indent: boolean;
+  grid: ProcessGridResult;
+  onKillClick: (proc: ProcessInfo) => void;
+}
+
+export function ProcessRow({ proc, indent, grid, onKillClick }: ProcessRowProps) {
+  return (
+    <div
+      className="grid items-center gap-1 min-h-11 md:min-h-7 px-3 text-xs group/proc hover:bg-surface-hover transition-colors grid-cols-[var(--sysmon-grid-n)] @lg:grid-cols-[var(--sysmon-grid-w)]"
+      data-testid="sysmon-process-row"
+      data-pid={proc.pid}
+      data-ppm={proc.ppm}
+      data-protected={proc.protected}
+      data-disk-bps={sumOptionalBps(proc.diskReadBps, proc.diskWriteBps)}
+      data-gpu-pct={proc.gpuPct}
+      data-net-bps={sumOptionalBps(proc.netInBps, proc.netOutBps)}
+    >
+      <div className={cn("flex items-start gap-1.5 min-w-0", indent && "pl-6")}>
+        <span className="text-text-subtle shrink-0">{proc.pid}</span>
+        <span className="truncate text-text-secondary" title={proc.command}>
+          {proc.command}
+        </span>
+      </div>
+      <span className={cn("text-right", cpuColor(proc.cpu))}>{proc.cpu.toFixed(1)}%</span>
+      <span className="text-right text-text-secondary">{formatRam(proc.ramMB)}</span>
+      {grid.columns.disk && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "disk"))}>
+          {formatDiskCell(proc.diskReadBps, proc.diskWriteBps)}
+        </span>
+      )}
+      {grid.columns.gpu && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "gpu"))}>
+          {formatGpuCell(proc.gpuPct, proc.gpuMemMB)}
+        </span>
+      )}
+      {grid.columns.net && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "net"))}>
+          {formatNetCell(proc.netInBps, proc.netOutBps)}
+        </span>
+      )}
+      <span
+        className="hidden @lg:block text-text-subtle text-right"
+        title={proc.startedAt ? new Date(proc.startedAt).toLocaleString() : ""}
+      >
+        {formatAge(proc.startedAt || undefined)}
+      </span>
+      <div className="flex justify-end">
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            onKillClick(proc);
+          }}
+          disabled={proc.protected}
+          aria-label={`End process ${proc.name} (${proc.pid})`}
+          title={proc.protected ? PROTECTED_TOOLTIP : `End process ${proc.name}`}
+          data-testid="sysmon-kill-btn"
+          className={cn(
+            "flex items-center justify-center size-11 md:size-7 rounded transition-all",
+            "can-hover:opacity-0 can-hover:group-hover/proc:opacity-100",
+            proc.protected
+              ? "opacity-40 cursor-not-allowed"
+              : "hover:bg-error/20 hover:text-error active:bg-error/30",
+          )}
+        >
+          <X className="size-3.5" />
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/web/components/system/process-table-model.ts

@@ -0,0 +1,127 @@
+/** Pure filter/sort/flatten/rollup for the process table. No React, no I/O, so the
+ *  filter/sort/expand/rollup rules are unit-testable without mounting a component.
+ *  Sort comparator lives in `process-table-sort.ts`, totals accumulator in
+ *  `process-table-totals.ts` — both split out to stay under the file-size guideline. */
+import type {
+  MetricsHistoryPoint,
+  ProcessGroup,
+  ProcessInfo,
+  SortDir,
+  SortKey,
+} from "../../../types/system-metrics";
+import { sortByKey, sortFields } from "./process-table-sort";
+import { accumulateTotals, EMPTY_TOTALS, type Totals } from "./process-table-totals";
+
+export type { Totals } from "./process-table-totals";
+
+export type TableRow =
+  | { kind: "group"; group: ProcessGroup; expanded: boolean; spark: number[] }
+  | { kind: "process"; proc: ProcessInfo; indent: boolean };
+
+export interface BuildRowsInput {
+  processes: ProcessInfo[];
+  groups: ProcessGroup[];
+  history: MetricsHistoryPoint[];
+  mode: "grouped" | "flat";
+  ppmOnly: boolean;
+  query: string;
+  sortKey: SortKey;
+  sortDir: SortDir;
+  expanded: Set<string>;
+}
+
+export interface BuildRowsResult {
+  rows: TableRow[];
+  totals: Totals;
+  /** Group keys the search auto-expanded (only in grouped mode with a non-empty query). */
+  autoExpanded: Set<string>;
+}
+
+const SPARK_POINTS = 60;
+
+function matches(text: string, query: string): boolean {
+  return text.toLowerCase().includes(query);
+}
+
+function processMatches(proc: ProcessInfo, query: string): boolean {
+  return matches(proc.name, query) || matches(proc.command, query);
+}
+
+function sparkFor(history: MetricsHistoryPoint[], groupKey: string): number[] {
+  return history.slice(-SPARK_POINTS).map((h) => h.groups[groupKey]?.cpu ?? 0);
+}
+
+/** Order fixed: filter (ppmOnly) -> filter (query) -> sort -> flatten (expand). */
+export function buildRows(input: BuildRowsInput): BuildRowsResult {
+  const { processes, groups, history, mode, ppmOnly, query, sortKey, sortDir, expanded } = input;
+  const q = query.trim().toLowerCase();
+  const byPid = new Map(processes.map((p) => [p.pid, p]));
+
+  if (mode === "flat") {
+    let flat = ppmOnly ? processes.filter((p) => p.ppm) : processes;
+    if (q) flat = flat.filter((p) => processMatches(p, q));
+    flat = sortByKey(flat, sortKey, sortDir, (p) => sortFields(p, p.name));
+
+    const totals = flat.reduce((acc, p) => accumulateTotals(acc, p, 1), EMPTY_TOTALS);
+
+    return {
+      rows: flat.map((proc) => ({ kind: "process" as const, proc, indent: false })),
+      totals,
+      autoExpanded: new Set(),
+    };
+  }
+
+  // Grouped mode.
+  let filteredGroups = ppmOnly ? groups.filter((g) => g.ppm) : groups;
+
+  const autoExpanded = new Set<string>();
+  if (q) {
+    filteredGroups = filteredGroups.filter((g) => {
+      const labelMatch = matches(g.label, q);
+      const memberMatch = g.pids.some((pid) => {
+        const proc = byPid.get(pid);
+        return proc ? processMatches(proc, q) : false;
+      });
+      const isMatch = labelMatch || memberMatch;
+      if (isMatch && memberMatch) autoExpanded.add(g.key);
+      return isMatch;
+    });
+  }
+
+  filteredGroups = sortByKey(filteredGroups, sortKey, sortDir, (g) => sortFields(g, g.label));
+
+  const rows: TableRow[] = [];
+  for (const group of filteredGroups) {
+    const isExpanded = q ? autoExpanded.has(group.key) || expanded.has(group.key) : expanded.has(group.key);
+    rows.push({
+      kind: "group",
+      group,
+      expanded: isExpanded,
+      spark: sparkFor(history, group.key),
+    });
+    if (!isExpanded) continue;
+
+    // Skip pids the current snapshot no longer has — a process can exit between the
+    // server's tick and the client's render, or the group's own snapshot is already
+    // one tick stale. Must not throw.
+    let children = group.pids
+      .map((pid) => byPid.get(pid))
+      .filter((p): p is ProcessInfo => p !== undefined);
+    if (q) children = children.filter((p) => processMatches(p, q));
+    children = sortByKey(children, sortKey, sortDir, (p) => sortFields(p, p.name));
+    for (const proc of children) {
+      rows.push({ kind: "process", proc, indent: true });
+    }
+  }
+
+  const totals = filteredGroups.reduce((acc, g) => accumulateTotals(acc, g, g.count), EMPTY_TOTALS);
+
+  return { rows, totals, autoExpanded };
+}
+
+/** Three-state sort toggle: desc -> asc -> off, shared by every sortable column. */
+export function toggleSort(current: SortKey, dir: SortDir, clicked: Exclude<SortKey, null>): [SortKey, SortDir] {
+  if (current !== clicked) return [clicked, "desc"];
+  if (dir === "desc") return [clicked, "asc"];
+  return [null, "desc"];
+}

package/src/web/components/system/process-table-sort.ts

@@ -0,0 +1,90 @@
+/** Sort comparator for the process table, split out of `process-table-model.ts`
+ *  to keep that file under the repo's 200-line guideline once Disk/GPU/Net sort
+ *  keys were added. No React, no I/O — pure so it's directly unit-testable. */
+import type { SortDir, SortKey } from "../../../types/system-metrics";
+
+/** Fields the comparator can read from either a `ProcessInfo` or a `ProcessGroup`
+ *  roll-up — both carry the same six optional metric names per the contract.
+ *  Optional metrics stay optional here: the "undefined sorts last, regardless of
+ *  direction" rule below depends on being able to tell "unmeasured" from "0". */
+export interface SortableFields {
+  cpu: number;
+  ramMB: number;
+  name: string;
+  diskReadBps?: number;
+  diskWriteBps?: number;
+  gpuPct?: number;
+  gpuMemMB?: number;
+  netInBps?: number;
+  netOutBps?: number;
+}
+
+/** Maps a `ProcessInfo` or `ProcessGroup` into `SortableFields` — only `name`
+ *  differs between the two shapes (process `name` vs. group `label`), so one
+ *  function covers both sort inputs. */
+export function sortFields(m: {
+  cpu: number;
+  ramMB: number;
+  diskReadBps?: number;
+  diskWriteBps?: number;
+  gpuPct?: number;
+  gpuMemMB?: number;
+  netInBps?: number;
+  netOutBps?: number;
+}, name: string): SortableFields {
+  return {
+    cpu: m.cpu,
+    ramMB: m.ramMB,
+    name,
+    diskReadBps: m.diskReadBps,
+    diskWriteBps: m.diskWriteBps,
+    gpuPct: m.gpuPct,
+    gpuMemMB: m.gpuMemMB,
+    netInBps: m.netInBps,
+    netOutBps: m.netOutBps,
+  };
+}
+
+/** `undefined` when neither side of the pair is measured — matches the
+ *  ProcessInfo/ProcessGroup contract ("undefined when NO member has a value"). */
+function sumPair(a?: number, b?: number): number | undefined {
+  if (a === undefined && b === undefined) return undefined;
+  return (a ?? 0) + (b ?? 0);
+}
+
+function optionalValueFor(key: "disk" | "gpu" | "gpuMem" | "net", f: SortableFields): number | undefined {
+  if (key === "disk") return sumPair(f.diskReadBps, f.diskWriteBps);
+  if (key === "net") return sumPair(f.netInBps, f.netOutBps);
+  if (key === "gpu") return f.gpuPct;
+  return f.gpuMemMB;
+}
+
+function isOptionalSortKey(key: SortKey): key is "disk" | "gpu" | "gpuMem" | "net" {
+  return key === "disk" || key === "gpu" || key === "gpuMem" || key === "net";
+}
+
+export function sortByKey<T>(items: T[], key: SortKey, dir: SortDir, get: (item: T) => SortableFields): T[] {
+  if (!key) return items;
+  return [...items].sort((a, b) => {
+    const av = get(a);
+    const bv = get(b);
+    if (key === "name") {
+      const cmp = av.name.localeCompare(bv.name);
+      return dir === "asc" ? cmp : -cmp;
+    }
+    if (key === "cpu") return dir === "asc" ? av.cpu - bv.cpu : bv.cpu - av.cpu;
+    if (key === "ram") return dir === "asc" ? av.ramMB - bv.ramMB : bv.ramMB - av.ramMB;
+
+    // disk/gpu/gpuMem/net: optional metrics. Undefined always sorts last, in
+    // EITHER direction — it means "unmeasurable", not "smallest value".
+    if (isOptionalSortKey(key)) {
+      const aVal = optionalValueFor(key, av);
+      const bVal = optionalValueFor(key, bv);
+      if (aVal === undefined && bVal === undefined) return 0;
+      if (aVal === undefined) return 1;
+      if (bVal === undefined) return -1;
+      return dir === "asc" ? aVal - bVal : bVal - aVal;
+    }
+    return 0;
+  });
+}

package/src/web/components/system/process-table-toolbar.tsx

@@ -0,0 +1,190 @@
+import { useEffect, useRef, useState } from "react";
+import { Search } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { formatRam } from "@/lib/format-bytes";
+import { cpuColor, formatDiskCell, formatGpuCell, formatNetCell } from "./process-row-format";
+import { optionalCellClassName, PROCESS_ROW_GRID_CLASS, type ProcessGridResult } from "./process-columns-grid";
+import type { Totals } from "./process-table-totals";
+import { SortableHeader } from "./sortable-header";
+import type { SortDir, SortKey } from "../../../types/system-metrics";
+
+const SEARCH_DEBOUNCE_MS = 150;
+
+export interface ProcessTableToolbarProps {
+  mode: "grouped" | "flat";
+  onModeChange: (mode: "grouped" | "flat") => void;
+  ppmOnly: boolean;
+  onPpmOnlyChange: (v: boolean) => void;
+  onQueryChange: (query: string) => void;
+}
+
+/** Search/mode/PPM controls. Debounces the query locally so typing does not rebuild
+ *  up to 1000 rows on every keystroke. */
+export function ProcessTableToolbar({
+  mode,
+  onModeChange,
+  ppmOnly,
+  onPpmOnlyChange,
+  onQueryChange,
+}: ProcessTableToolbarProps) {
+  const [draft, setDraft] = useState("");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => onQueryChange(draft), SEARCH_DEBOUNCE_MS);
+    return () => {
+      if (timer.current) clearTimeout(timer.current);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- onQueryChange identity may churn; only `draft` should retrigger
+  }, [draft]);
+
+  return (
+    <div className="flex flex-wrap items-center gap-2 p-2 border-b border-border shrink-0">
+      <div className="relative flex-1 min-w-[140px]">
+        <Search className="absolute left-2 top-1/2 -translate-y-1/2 size-3.5 text-text-subtle" />
+        <input
+          type="text"
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+          placeholder="Search processes"
+          aria-label="Search processes"
+          data-testid="sysmon-process-search"
+          className="w-full min-h-11 md:min-h-8 pl-7 pr-2 text-sm rounded-md border border-border bg-transparent focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        />
+      </div>
+      <button
+        type="button"
+        onClick={() => onModeChange(mode === "grouped" ? "flat" : "grouped")}
+        aria-pressed={mode === "flat"}
+        data-testid="sysmon-toggle-flat"
+        className="min-h-11 md:min-h-8 px-3 text-xs rounded-md border border-border hover:bg-surface-hover transition-colors"
+      >
+        {mode === "flat" ? "Flat" : "Grouped"}
+      </button>
+      <button
+        type="button"
+        onClick={() => onPpmOnlyChange(!ppmOnly)}
+        aria-pressed={ppmOnly}
+        data-testid="sysmon-filter-ppm"
+        className={cn(
+          "min-h-11 md:min-h-8 px-3 text-xs rounded-md border transition-colors",
+          ppmOnly ? "border-primary bg-primary/10 text-primary" : "border-border hover:bg-surface-hover",
+        )}
+      >
+        PPM only
+      </button>
+    </div>
+  );
+}
+
+export interface ProcessTableHeaderProps {
+  sortKey: SortKey;
+  sortDir: SortDir;
+  grid: ProcessGridResult;
+  onSort: (field: Exclude<SortKey, null>) => void;
+}
+
+/** Sticky column header row, grid-aligned with the rows below it. Disk/GPU/Net
+ *  headers only render when the host reported that column as measurable
+ *  (`grid.columns.<x>`); below `@lg` only the one currently sorted survives. */
+export function ProcessTableHeader({ sortKey, sortDir, grid, onSort }: ProcessTableHeaderProps) {
+  return (
+    <div
+      role="row"
+      className={cn(
+        "grid gap-1 px-3 py-1.5 text-[11px] text-text-subtle border-b border-border sticky top-0 bg-background z-10",
+        PROCESS_ROW_GRID_CLASS,
+      )}
+    >
+      <SortableHeader
+        label="Process"
+        field="name"
+        activeKey={sortKey}
+        activeDir={sortDir}
+        onClick={onSort}
+        align="left"
+        testId="sysmon-sort-name"
+      />
+      <SortableHeader label="CPU" field="cpu" activeKey={sortKey} activeDir={sortDir} onClick={onSort} testId="sysmon-sort-cpu" />
+      <SortableHeader label="RAM" field="ram" activeKey={sortKey} activeDir={sortDir} onClick={onSort} testId="sysmon-sort-ram" />
+      {grid.columns.disk && (
+        <SortableHeader
+          label="Disk"
+          field="disk"
+          activeKey={sortKey}
+          activeDir={sortDir}
+          onClick={onSort}
+          testId="sysmon-col-disk"
+          className={optionalCellClassName(grid, "disk")}
+        />
+      )}
+      {grid.columns.gpu && (
+        <SortableHeader
+          label="GPU"
+          field="gpu"
+          activeKey={sortKey}
+          activeDir={sortDir}
+          onClick={onSort}
+          testId="sysmon-col-gpu"
+          className={optionalCellClassName(grid, "gpu")}
+        />
+      )}
+      {grid.columns.net && (
+        <SortableHeader
+          label="Net"
+          field="net"
+          activeKey={sortKey}
+          activeDir={sortDir}
+          onClick={onSort}
+          testId="sysmon-col-net"
+          className={optionalCellClassName(grid, "net")}
+        />
+      )}
+      <span className="text-right hidden @lg:block">Trend</span>
+      <span />
+    </div>
+  );
+}
+
+export interface ProcessTableFooterProps {
+  totals: Totals;
+  grid: ProcessGridResult;
+  /** `system.gpus[0]?.utilPercent` — a whole-machine reading, not a sum of the
+   *  visible rows' `gpuPct` (per-process GPU% can double-count shared engines). */
+  gpuUtilPercent?: number;
+}
+
+export function ProcessTableFooter({ totals, grid, gpuUtilPercent }: ProcessTableFooterProps) {
+  return (
+    <div
+      className={cn(
+        "grid gap-1 px-3 py-1.5 text-xs font-medium border-t border-border shrink-0",
+        PROCESS_ROW_GRID_CLASS,
+      )}
+      data-testid="sysmon-total"
+      data-process-count={totals.count}
+    >
+      <span className="truncate">Total ({totals.count} processes)</span>
+      <span className={cn("text-right", cpuColor(totals.cpu))}>{totals.cpu.toFixed(1)}%</span>
+      <span className="text-right text-text-secondary">{formatRam(totals.ramMB)}</span>
+      {grid.columns.disk && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "disk"))}>
+          {formatDiskCell(totals.diskReadBps, totals.diskWriteBps)}
+        </span>
+      )}
+      {grid.columns.gpu && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "gpu"))}>
+          {formatGpuCell(gpuUtilPercent, totals.gpuMemMB)}
+        </span>
+      )}
+      {grid.columns.net && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "net"))}>
+          {formatNetCell(totals.netInBps, totals.netOutBps)}
+        </span>
+      )}
+      <span className="hidden @lg:block" />
+      <span />
+    </div>
+  );
+}

package/src/web/components/system/process-table-totals.ts

@@ -0,0 +1,49 @@
+/** Footer totals accumulator, split out of `process-table-model.ts` to keep
+ *  that file under the repo's 200-line guideline. Pure, no React/I/O. */
+
+export interface Totals {
+  cpu: number;
+  ramMB: number;
+  count: number;
+  /** Sums over rows with a defined value; `undefined` when NO visible row measured
+   *  that metric — mirrors the "undefined = host can't measure" rule on ProcessInfo. */
+  diskReadBps?: number;
+  diskWriteBps?: number;
+  gpuMemMB?: number;
+  netInBps?: number;
+  netOutBps?: number;
+}
+
+export const EMPTY_TOTALS: Totals = { cpu: 0, ramMB: 0, count: 0 };
+
+/** Adds an optional metric into a running total; stays `undefined` until at
+ *  least one contributor has a defined value (mirrors the roll-up rule). */
+function addOptional(sum: number | undefined, value: number | undefined): number | undefined {
+  if (value === undefined) return sum;
+  return (sum ?? 0) + value;
+}
+
+export function accumulateTotals(
+  acc: Totals,
+  item: {
+    cpu: number;
+    ramMB: number;
+    diskReadBps?: number;
+    diskWriteBps?: number;
+    gpuMemMB?: number;
+    netInBps?: number;
+    netOutBps?: number;
+  },
+  countDelta: number,
+): Totals {
+  return {
+    cpu: acc.cpu + item.cpu,
+    ramMB: acc.ramMB + item.ramMB,
+    count: acc.count + countDelta,
+    diskReadBps: addOptional(acc.diskReadBps, item.diskReadBps),
+    diskWriteBps: addOptional(acc.diskWriteBps, item.diskWriteBps),
+    gpuMemMB: addOptional(acc.gpuMemMB, item.gpuMemMB),
+    netInBps: addOptional(acc.netInBps, item.netInBps),
+    netOutBps: addOptional(acc.netOutBps, item.netOutBps),
+  };
+}