@hienlh/ppm 0.18.8 → 0.18.9

package/src/web/components/system/overview-cards/net-card.tsx

@@ -0,0 +1,41 @@
+import { formatBps } from "@/lib/format-bytes";
+import { MetricChartCanvas } from "../metric-chart-canvas";
+
+export interface NetCardProps {
+  available: boolean;
+  inBps: number;
+  outBps: number;
+  downSeries: number[];
+  upSeries: number[];
+  /** True while the stream has not yet delivered a second tick — a rate needs two
+   *  samples, so `available:false` here is expected, not a missing collector. */
+  measuring?: boolean;
+}
+
+export function NetCard({ available, inBps, outBps, downSeries, upSeries, measuring }: NetCardProps) {
+  return (
+    <div
+      className="rounded-lg border border-border p-4 space-y-2"
+      data-testid="sysmon-card-net"
+      data-available={available}
+    >
+      <h3 className="text-sm font-medium">Network</h3>
+      {available ? (
+        <>
+          <MetricChartCanvas
+            series={[
+              { data: downSeries, color: "var(--color-primary)" },
+              { data: upSeries, color: "var(--color-warning)" },
+            ]}
+            height={56}
+          />
+          <p className="text-[11px] text-text-subtle">
+            Down {formatBps(inBps)} · Up {formatBps(outBps)}
+          </p>
+        </>
+      ) : (
+        <p className="text-[11px] text-text-subtle">{measuring ? "measuring…" : "n/a"}</p>
+      )}
+    </div>
+  );
+}

package/src/web/components/system/overview-panel.tsx

@@ -0,0 +1,97 @@
+import { useMemo } from "react";
+import type { MetricsHistoryPoint, SystemMetrics } from "../../../types/system-metrics";
+import { CpuCard } from "./overview-cards/cpu-card";
+import { MemCard } from "./overview-cards/mem-card";
+import { DiskCard } from "./overview-cards/disk-card";
+import { NetCard } from "./overview-cards/net-card";
+import { GpuCard } from "./overview-cards/gpu-card";
+
+export interface OverviewPanelProps {
+  system: SystemMetrics;
+  history: MetricsHistoryPoint[];
+}
+
+const SERIES_POINTS = 200;
+
+/** One pass over the recent history window building every card's series together,
+ *  rather than one `.slice(-200).map(...)` per card. */
+function useOverviewSeries(history: MetricsHistoryPoint[]) {
+  return useMemo(() => {
+    const recent = history.slice(-SERIES_POINTS);
+    const cpu: number[] = [];
+    const mem: number[] = [];
+    const diskRead: number[] = [];
+    const diskWrite: number[] = [];
+    const netDown: number[] = [];
+    const netUp: number[] = [];
+    const gpuUtil: number[][] = [];
+
+    for (const point of recent) {
+      cpu.push(point.system.cpu.total);
+      mem.push(point.system.mem.percent);
+      diskRead.push(point.system.disk.available ? point.system.disk.inBps : 0);
+      diskWrite.push(point.system.disk.available ? point.system.disk.outBps : 0);
+      netDown.push(point.system.net.available ? point.system.net.inBps : 0);
+      netUp.push(point.system.net.available ? point.system.net.outBps : 0);
+      point.system.gpus.forEach((g, i) => {
+        (gpuUtil[i] ??= []).push(g.utilPercent);
+      });
+    }
+
+    return { cpu, mem, diskRead, diskWrite, netDown, netUp, gpuUtil };
+  }, [history]);
+}
+
+export function OverviewPanel({ system, history }: OverviewPanelProps) {
+  const series = useOverviewSeries(history);
+  // Disk/net rates need a delta between two samples — `available:false` on the very
+  // first frame(s) is the collector doing exactly what it should, not a missing
+  // source, so the card says so instead of the flat, indistinguishable "n/a".
+  const measuring = history.length <= 1;
+
+  return (
+    <div
+      className="p-4 grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4"
+      data-testid="sysmon-overview"
+    >
+      <CpuCard
+        total={system.cpu.total}
+        cores={system.cpu.cores}
+        model={system.cpu.model}
+        series={series.cpu}
+      />
+      <MemCard
+        usedMB={system.mem.usedMB}
+        totalMB={system.mem.totalMB}
+        percent={system.mem.percent}
+        series={series.mem}
+      />
+      <DiskCard
+        available={system.disk.available}
+        inBps={system.disk.inBps}
+        outBps={system.disk.outBps}
+        readSeries={series.diskRead}
+        writeSeries={series.diskWrite}
+        measuring={measuring}
+      />
+      <NetCard
+        available={system.net.available}
+        inBps={system.net.inBps}
+        outBps={system.net.outBps}
+        downSeries={series.netDown}
+        upSeries={series.netUp}
+        measuring={measuring}
+      />
+      {system.gpus.map((gpu, i) => (
+        <GpuCard
+          key={`${gpu.name}-${i}`}
+          name={gpu.name}
+          utilPercent={gpu.utilPercent}
+          vramUsedMB={gpu.vramUsedMB}
+          vramTotalMB={gpu.vramTotalMB}
+          series={series.gpuUtil[i] ?? []}
+        />
+      ))}
+    </div>
+  );
+}

package/src/web/components/system/process-columns-grid.ts

@@ -0,0 +1,93 @@
+/** Pure grid-template builder for the process table. No React, so the visibility
+ *  rules (which optional columns exist, which one survives below `@lg`) are
+ *  unit-testable without mounting a component.
+ *
+ *  Two responsive templates are computed up front and switched via CSS custom
+ *  properties + a `@lg:` Tailwind class (see `PROCESS_ROW_GRID_CLASS` below) —
+ *  Tailwind's arbitrary-value scan only needs the class NAME to be a static
+ *  string; the var() value itself can vary at runtime. This mirrors the fixed
+ *  two-template approach the process table already used for the trend/age
+ *  track, just parameterised by which optional columns the host can measure. */
+import type { CSSProperties } from "react";
+import type { ProcessColumnAvailability, SortKey } from "../../../types/system-metrics";
+
+export type OptionalColumnKey = "disk" | "gpu" | "net";
+
+/** Alias kept local so call sites don't need to know the exact server-contract
+ *  type name — this module only cares about the three boolean flags. */
+export type ProcessColumnsFlags = ProcessColumnAvailability;
+
+const OPTIONAL_COLUMN_ORDER: OptionalColumnKey[] = ["disk", "gpu", "net"];
+
+/** Disk/Net cells show two values ("↓ read ↑ write"); GPU shows one composite
+ *  ("12% · 1.1 GB") and fits narrower. */
+const OPTIONAL_COLUMN_WIDTH: Record<OptionalColumnKey, string> = {
+  disk: "120px",
+  gpu: "90px",
+  net: "120px",
+};
+
+/** Fixed tracks that exist regardless of optional columns: Process name (flexible),
+ *  CPU, RAM at the start; the trend/age track (wide only) and the kill button at
+ *  the end. */
+const NAME_CPU_RAM = ["minmax(0,1fr)", "64px", "80px"];
+const TREND_TRACK = "130px";
+const KILL_TRACK = "44px";
+
+export interface ProcessGridResult {
+  /** Grid template for `@lg` and up: Name/CPU/RAM + every enabled optional column
+   *  in a fixed order + the trend/age track + kill button. */
+  wideTemplate: string;
+  /** Grid template below `@lg`: Name/CPU/RAM + AT MOST the one optional column
+   *  currently sorted by (if enabled) + kill button. No trend/age track. */
+  narrowTemplate: string;
+  /** Which optional columns are enabled at all (host can measure them). */
+  columns: ProcessColumnsFlags;
+  /** The single optional column visible below `@lg`, or null when the current
+   *  sort isn't on an optional column (or that column isn't enabled). */
+  narrowExtra: OptionalColumnKey | null;
+}
+
+function isOptionalColumnKey(key: SortKey): key is OptionalColumnKey {
+  return key === "disk" || key === "gpu" || key === "net";
+}
+
+export function buildProcessGrid(columns: ProcessColumnsFlags, sortKey: SortKey): ProcessGridResult {
+  const enabled = OPTIONAL_COLUMN_ORDER.filter((k) => columns[k]);
+  const narrowExtra = isOptionalColumnKey(sortKey) && columns[sortKey] ? sortKey : null;
+
+  const wideTemplate = [
+    ...NAME_CPU_RAM,
+    ...enabled.map((k) => OPTIONAL_COLUMN_WIDTH[k]),
+    TREND_TRACK,
+    KILL_TRACK,
+  ].join(" ");
+
+  const narrowTemplate = [
+    ...NAME_CPU_RAM,
+    ...(narrowExtra ? [OPTIONAL_COLUMN_WIDTH[narrowExtra]] : []),
+    KILL_TRACK,
+  ].join(" ");
+
+  return { wideTemplate, narrowTemplate, columns, narrowExtra };
+}
+
+/** Static class names (Tailwind can see both arbitrary-value strings at build
+ *  time); the actual template text is supplied per-render via the two CSS
+ *  custom properties in `gridCssVars`. */
+export const PROCESS_ROW_GRID_CLASS = "grid-cols-[var(--sysmon-grid-n)] @lg:grid-cols-[var(--sysmon-grid-w)]";
+
+export function gridCssVars(grid: ProcessGridResult): CSSProperties {
+  return {
+    "--sysmon-grid-n": grid.narrowTemplate,
+    "--sysmon-grid-w": grid.wideTemplate,
+  } as CSSProperties;
+}
+
+/** Visibility className for an optional column's cell: always visible when it is
+ *  the narrow-mode survivor, otherwise hidden below `@lg` and shown at `@lg`+.
+ *  Caller must only render the cell at all when `columns[key]` is true — when
+ *  disabled, the column has no track in either template. */
+export function optionalCellClassName(grid: ProcessGridResult, key: OptionalColumnKey): string {
+  return grid.narrowExtra === key ? "block" : "hidden @lg:block";
+}

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

@@ -0,0 +1,71 @@
+import { ChevronRight, ChevronDown } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { formatRam } from "@/lib/format-bytes";
+import { cpuColor, formatDiskCell, formatGpuCell, formatNetCell, sumOptionalBps } from "./process-row-format";
+import { optionalCellClassName, type ProcessGridResult } from "./process-columns-grid";
+import { SparklineCanvas } from "./sparkline-canvas";
+import type { ProcessGroup } from "../../../types/system-metrics";
+
+export interface ProcessGroupRowProps {
+  group: ProcessGroup;
+  expanded: boolean;
+  spark: number[];
+  grid: ProcessGridResult;
+  onToggle: (key: string) => void;
+}
+
+export function ProcessGroupRow({ group, expanded, spark, grid, onToggle }: ProcessGroupRowProps) {
+  const Chevron = expanded ? ChevronDown : ChevronRight;
+
+  return (
+    <div
+      className="grid items-center gap-1 min-h-11 md:min-h-7 px-3 text-xs cursor-pointer hover:bg-surface-hover transition-colors grid-cols-[var(--sysmon-grid-n)] @lg:grid-cols-[var(--sysmon-grid-w)]"
+      onClick={() => onToggle(group.key)}
+      data-testid="sysmon-group-row"
+      data-group-key={group.key}
+      data-count={group.count}
+      data-disk-bps={sumOptionalBps(group.diskReadBps, group.diskWriteBps)}
+      data-gpu-pct={group.gpuPct}
+      data-net-bps={sumOptionalBps(group.netInBps, group.netOutBps)}
+    >
+      <div className="flex items-center gap-1.5 min-w-0">
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            onToggle(group.key);
+          }}
+          aria-expanded={expanded}
+          aria-label={`${expanded ? "Collapse" : "Expand"} ${group.label}`}
+          data-testid="sysmon-group-expand"
+          className="flex items-center justify-center size-11 md:size-7 -ml-2 shrink-0"
+        >
+          <Chevron className="size-3.5 text-text-subtle" />
+        </button>
+        <span className="truncate font-medium">{group.label}</span>
+        <span className="text-text-subtle shrink-0">({group.count})</span>
+      </div>
+      <span className={cn("text-right", cpuColor(group.cpu))}>{group.cpu.toFixed(1)}%</span>
+      <span className="text-right text-text-secondary">{formatRam(group.ramMB)}</span>
+      {grid.columns.disk && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "disk"))}>
+          {formatDiskCell(group.diskReadBps, group.diskWriteBps)}
+        </span>
+      )}
+      {grid.columns.gpu && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "gpu"))}>
+          {formatGpuCell(group.gpuPct, group.gpuMemMB)}
+        </span>
+      )}
+      {grid.columns.net && (
+        <span className={cn("text-right text-text-secondary tabular-nums truncate", optionalCellClassName(grid, "net"))}>
+          {formatNetCell(group.netInBps, group.netOutBps)}
+        </span>
+      )}
+      <div className="hidden @lg:flex items-center justify-end">
+        {spark.length > 1 && <SparklineCanvas data={spark} width={120} height={20} maxValue={100} />}
+      </div>
+      <div className="hidden @lg:block" />
+    </div>
+  );
+}

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;
+  });
+}