@hienlh/ppm 0.18.8 → 0.18.10

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,159 @@
+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, type ColumnResizeHandlers } 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;
+  resize: ColumnResizeHandlers;
+}
+
+/** 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. Every
+ *  fixed-width column carries a drag handle on its right edge. */
+export function ProcessTableHeader({ sortKey, sortDir, grid, onSort, resize }: ProcessTableHeaderProps) {
+  const common = { activeKey: sortKey, activeDir: sortDir, onClick: onSort, resize };
+  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" {...common} resize={undefined} align="left" testId="sysmon-sort-name" />
+      <SortableHeader label="CPU" field="cpu" {...common} resizeKey="cpu" testId="sysmon-sort-cpu" />
+      <SortableHeader label="RAM" field="ram" {...common} resizeKey="ram" testId="sysmon-sort-ram" />
+      {grid.columns.disk && (
+        <SortableHeader label="Disk" field="disk" {...common} resizeKey="disk" testId="sysmon-col-disk" className={optionalCellClassName(grid, "disk")} />
+      )}
+      {grid.columns.gpu && (
+        <SortableHeader label="GPU" field="gpu" {...common} resizeKey="gpu" testId="sysmon-col-gpu" className={optionalCellClassName(grid, "gpu")} />
+      )}
+      {grid.columns.net && (
+        <SortableHeader label="Net" field="net" {...common} resizeKey="net" testId="sysmon-col-net" className={optionalCellClassName(grid, "net")} />
+      )}
+      <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 />
+    </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),
+  };
+}

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

@@ -0,0 +1,146 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { buildRows, toggleSort } from "./process-table-model";
+import { buildProcessGrid, gridCssVars } from "./process-columns-grid";
+import { ProcessTableToolbar, ProcessTableHeader, ProcessTableFooter } from "./process-table-toolbar";
+import { ProcessGroupRow } from "./process-group-row";
+import { ProcessRow } from "./process-row";
+import { KillConfirmDialog } from "./kill-confirm-dialog";
+import { useProcessKill } from "./use-process-kill";
+import { useColumnWidths } from "./use-column-widths";
+import type { MetricsSnapshot, SortDir, SortKey } from "../../../types/system-metrics";
+
+/** Older cached bundles/snapshots (mid-rollout) predate `processColumns` — default
+ *  every optional column off rather than let a missing field throw. */
+const NO_OPTIONAL_COLUMNS = { disk: false, gpu: false, net: false };
+
+export interface ProcessTableProps {
+  snapshot: MetricsSnapshot;
+}
+
+export function ProcessTable({ snapshot }: ProcessTableProps) {
+  const isMobile = useIsMobile();
+  const parentRef = useRef<HTMLDivElement>(null);
+
+  const [mode, setMode] = useState<"grouped" | "flat">("grouped");
+  const [ppmOnly, setPpmOnly] = useState(false);
+  const [query, setQuery] = useState("");
+  const [sortKey, setSortKey] = useState<SortKey>(null);
+  const [sortDir, setSortDir] = useState<SortDir>("desc");
+  const [expanded, setExpanded] = useState<Set<string>>(() => new Set());
+  const { pendingKill, groupProtected, requestKillProcess, requestKillGroup, confirmKill, cancelKill } =
+    useProcessKill(snapshot);
+  const { widths, begin: onResizeStart, reset: onResizeReset } = useColumnWidths();
+
+  const { rows, totals } = useMemo(
+    () =>
+      buildRows({
+        processes: snapshot.processes,
+        groups: snapshot.groups,
+        mode,
+        ppmOnly,
+        query,
+        sortKey,
+        sortDir,
+        expanded,
+      }),
+    [snapshot.processes, snapshot.groups, mode, ppmOnly, query, sortKey, sortDir, expanded],
+  );
+
+  const columns = snapshot.processColumns ?? NO_OPTIONAL_COLUMNS;
+  const grid = useMemo(() => buildProcessGrid(columns, sortKey, widths), [columns, sortKey, widths]);
+  const gpuUtilPercent = snapshot.system.gpus[0]?.utilPercent;
+
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => (isMobile ? 44 : 28),
+    overscan: 12,
+  });
+
+  const handleSort = useCallback(
+    (field: Exclude<SortKey, null>) => {
+      const [nextKey, nextDir] = toggleSort(sortKey, sortDir, field);
+      setSortKey(nextKey);
+      setSortDir(nextDir);
+    },
+    [sortKey, sortDir],
+  );
+
+  const handleToggleGroup = useCallback((key: string) => {
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }, []);
+
+  // `@container`: the trend/age track is toggled on the table's own width, not the
+  // viewport — a floating window is routinely narrower than the screen it sits on.
+  // `gridCssVars` sets `--sysmon-grid-n`/`--sysmon-grid-w` once here; CSS custom
+  // properties inherit to every row/header/footer below without re-passing style.
+  return (
+    <div
+      className="h-full flex flex-col min-h-0 @container"
+      style={gridCssVars(grid)}
+      data-testid="sysmon-processes"
+      data-row-count={rows.length}
+    >
+      <ProcessTableToolbar
+        mode={mode}
+        onModeChange={setMode}
+        ppmOnly={ppmOnly}
+        onPpmOnlyChange={setPpmOnly}
+        onQueryChange={setQuery}
+      />
+      <ProcessTableHeader
+        sortKey={sortKey}
+        sortDir={sortDir}
+        grid={grid}
+        onSort={handleSort}
+        resize={{ onResizeStart, onResizeReset }}
+      />
+      <div ref={parentRef} className="flex-1 min-h-0 overflow-y-auto">
+        <div style={{ height: virtualizer.getTotalSize(), position: "relative" }}>
+          {virtualizer.getVirtualItems().map((item) => {
+            const row = rows[item.index];
+            if (!row) return null;
+            return (
+              <div
+                key={row.kind === "group" ? row.group.key : `p:${row.proc.pid}`}
+                style={{
+                  position: "absolute",
+                  top: 0,
+                  left: 0,
+                  right: 0,
+                  transform: `translateY(${item.start}px)`,
+                }}
+              >
+                {row.kind === "group" ? (
+                  <ProcessGroupRow
+                    group={row.group}
+                    expanded={row.expanded}
+                    grid={grid}
+                    killProtected={groupProtected.get(row.group.key) ?? true}
+                    onToggle={handleToggleGroup}
+                    onKillClick={requestKillGroup}
+                  />
+                ) : (
+                  <ProcessRow proc={row.proc} indent={row.indent} grid={grid} onKillClick={requestKillProcess} />
+                )}
+              </div>
+            );
+          })}
+        </div>
+      </div>
+      <ProcessTableFooter totals={totals} grid={grid} gpuUtilPercent={gpuUtilPercent} />
+      <KillConfirmDialog
+        target={pendingKill}
+        onConfirm={confirmKill}
+        onCancel={cancelKill}
+      />
+    </div>
+  );
+}

package/src/web/components/system/resolve-open-system-monitor-action.ts

@@ -0,0 +1,29 @@
+/** Pure viewport-routing decision for the System Monitor open-hook — split out from
+ *  `use-open-system-monitor.ts` so it has zero runtime imports (only a type-only one,
+ *  fully erased) and is unit-testable without mounting zustand stores. */
+import type { Tab } from "@/stores/tab-store";
+
+export type OpenSystemMonitorAction =
+  | { kind: "tab"; tab: Omit<Tab, "id"> }
+  | { kind: "window" }
+  | { kind: "focus"; id: string };
+
+/**
+ * There is exactly one machine, so unlike `"explorer"`/`"team-member"` (legitimately
+ * multi-instance — different payload, different folder/teammate), a second
+ * `"system-monitor"` window is never a distinct instance, only a duplicate. When one
+ * is already open, focus it instead of spawning another.
+ */
+export function resolveOpenSystemMonitorAction(
+  isMobile: boolean,
+  existingWindowId: string | null,
+): OpenSystemMonitorAction {
+  if (isMobile) {
+    return {
+      kind: "tab",
+      tab: { type: "system-monitor", title: "System Monitor", projectId: null, closable: true },
+    };
+  }
+  if (existingWindowId) return { kind: "focus", id: existingWindowId };
+  return { kind: "window" };
+}

package/src/web/components/system/resource-status-bar.tsx

@@ -1,9 +1,9 @@
 import { memo } from "react";
 import { Cpu } from "lucide-react";
 import { useResourceMonitor } from "@/hooks/use-resource-monitor";
-import { useTabStore } from "@/stores/tab-store";
 import { useIsMobile } from "@/hooks/use-is-mobile";
 import { cn } from "@/lib/utils";
+import { useOpenSystemMonitor } from "./use-open-system-monitor";
 
 function cpuColor(cpu: number) {
   if (cpu > 80) return "text-error";
@@ -11,26 +11,21 @@ function cpuColor(cpu: number) {
   return "text-success";
 }
 
-/** `compact` renders inline for the 22px status bar (no full-width button, CPU+MEM only). */
+/** `compact` renders inline for the 22px status bar (no full-width button, CPU+MEM only).
+ *  Stays on the light SSE tier — never opts into `{processes:true}` — so it never pays
+ *  for the full collector just to render two numbers. */
 export const ResourceStatusBar = memo(function ResourceStatusBar({ compact = false }: { compact?: boolean }) {
   const { latest, isConnected } = useResourceMonitor();
-  const openTab = useTabStore((s) => s.openTab);
+  const openSystemMonitor = useOpenSystemMonitor();
   const isMobile = useIsMobile();
 
-  const handleClick = () => {
-    openTab({
-      type: "system-monitor",
-      title: "System Monitor",
-      projectId: null,
-      closable: true,
-    });
-  };
-
   if (!isConnected || !latest) {
     if (compact) return null; // stay silent in the status bar until connected
     return (
       <button
-        onClick={handleClick}
+        onClick={openSystemMonitor}
+        data-testid="status-bar-resources"
+        aria-label="Open System Monitor"
         className="flex items-center gap-1.5 px-2 py-1 text-[10px] text-text-subtle hover:text-text-secondary transition-colors w-full"
       >
         <Cpu className="size-3 opacity-50" />
@@ -39,14 +34,18 @@ export const ResourceStatusBar = memo(function ResourceStatusBar({ compact = fal
     );
   }
 
-  const { cpu, ramMB, processCount } = latest.total;
+  const cpu = latest.system.cpu.total;
+  const ramMB = latest.system.mem.usedMB;
+  const processCount = latest.system.processCount;
   const mem = ramMB < 1024 ? `${ramMB.toFixed(0)}M` : `${(ramMB / 1024).toFixed(1)}G`;
 
   if (compact) {
     // Inline segment for the 22px status bar: CPU % · MEM (handoff B2 right cluster).
     return (
       <button
-        onClick={handleClick}
+        onClick={openSystemMonitor}
+        data-testid="status-bar-resources"
+        aria-label="Open System Monitor"
         className="flex items-center gap-2 px-1 rounded-sm hover:bg-accent/15 transition-colors cursor-pointer"
         title="Open System Monitor"
       >
@@ -58,7 +57,9 @@ export const ResourceStatusBar = memo(function ResourceStatusBar({ compact = fal
 
   return (
     <button
-      onClick={handleClick}
+      onClick={openSystemMonitor}
+      data-testid="status-bar-resources"
+      aria-label="Open System Monitor"
       className="flex items-center gap-1.5 px-2 py-1 text-[10px] hover:bg-surface-hover transition-colors w-full cursor-pointer"
       title="Open System Monitor"
     >

package/src/web/components/system/sortable-header.tsx

@@ -0,0 +1,90 @@
+import { ArrowUp, ArrowDown } from "lucide-react";
+import { cn } from "@/lib/utils";
+import type { SortDir, SortKey } from "../../../types/system-metrics";
+import type { ResizableColumnKey } from "./process-columns-grid";
+
+export interface ColumnResizeHandlers {
+  onResizeStart: (key: ResizableColumnKey, e: { clientX: number; preventDefault: () => void }) => void;
+  onResizeReset: (key: ResizableColumnKey) => void;
+}
+
+/** Sortable column header shared by the process table toolbar. Renders as a
+ *  `columnheader` `<div>`, not a `<th>` — the parent row is a CSS-grid
+ *  `<div role="row">`, and a `<th>` inside a non-table ancestor both triggers React's
+ *  DOM-nesting warning and makes `aria-sort` meaningless to assistive tech outside
+ *  an actual table. */
+export function SortableHeader({
+  label,
+  field,
+  activeKey,
+  activeDir,
+  onClick,
+  align = "right",
+  testId,
+  className,
+  resizeKey,
+  resize,
+}: {
+  label: string;
+  field: Exclude<SortKey, null>;
+  activeKey: SortKey;
+  activeDir: SortDir;
+  onClick: (field: Exclude<SortKey, null>) => void;
+  /** Text/justify alignment — the "Process" column is left-aligned over the name
+   *  cell, every numeric column stays right-aligned. */
+  align?: "left" | "right";
+  testId?: string;
+  /** Extra classes on the outer `columnheader` — e.g. the `hidden @lg:block`
+   *  visibility rule an optional (Disk/GPU/Net) column needs below `@lg`. */
+  className?: string;
+  /** Present for fixed-width columns: renders the drag handle on the right edge. */
+  resizeKey?: ResizableColumnKey;
+  resize?: ColumnResizeHandlers;
+}) {
+  const isActive = activeKey === field;
+  const Arrow = isActive ? (activeDir === "asc" ? ArrowUp : ArrowDown) : null;
+  const ariaSort = isActive ? (activeDir === "asc" ? "ascending" : "descending") : "none";
+
+  return (
+    <div
+      role="columnheader"
+      aria-sort={ariaSort}
+      className={cn(
+        "relative py-1.5 px-2 font-medium select-none",
+        align === "left" ? "text-left" : "text-right",
+        className,
+      )}
+    >
+      {/* The test id sits on the interactive element: a synthetic `click()` on the
+          wrapper never reaches the button (events bubble up, not down), so a harness
+          targeting the div would silently not sort. */}
+      <button
+        type="button"
+        data-testid={testId}
+        onClick={() => onClick(field)}
+        className={cn(
+          "flex items-center gap-0.5 w-full min-h-11 md:min-h-0 cursor-pointer hover:text-text-primary transition-colors",
+          align === "left" ? "justify-start" : "justify-end",
+          isActive && "text-text-primary",
+        )}
+      >
+        <span className="truncate">{label}</span>
+        {Arrow && <Arrow className="size-3 shrink-0" />}
+      </button>
+      {/* Drag handle: pointer-only (hidden below `md`, where the table is a
+          single narrow column set and there is nothing worth resizing). Double-click
+          returns the column to its default width. */}
+      {resizeKey && resize && (
+        <div
+          role="separator"
+          aria-orientation="vertical"
+          aria-label={`Resize ${label} column`}
+          data-testid={testId ? `${testId}-resize` : undefined}
+          onPointerDown={(e) => resize.onResizeStart(resizeKey, e)}
+          onDoubleClick={() => resize.onResizeReset(resizeKey)}
+          className="hidden md:block absolute top-0 -right-1 h-full w-2 cursor-col-resize hover:bg-primary/40 active:bg-primary/60"
+        />
+      )}
+    </div>
+  );
+}