@tonyclaw/llm-inspector 1.11.8 → 1.13.0

package/src/components/proxy-viewer/CompareDrawer.tsx

@@ -0,0 +1,388 @@
+import { useEffect, useMemo, useState } from "react";
+import type { JSX } from "react";
+import { ChevronRight, X } from "lucide-react";
+import { cn, formatTokens } from "../../lib/utils";
+import type { CapturedLog } from "../../proxy/schemas";
+import { parseRequest } from "../../proxy/schemas";
+import {
+  type DiffOp,
+  type JsonNode,
+  diffTrees,
+  normalizeRequest,
+  previewNode,
+} from "./requestDiff";
+import { getConversationId } from "./ConversationHeader";
+import { JsonViewerFromString } from "../ui/json-viewer";
+import { Badge } from "../ui/badge";
+
+export type CompareDrawerProps = {
+  /** Log selected first (shown on the left). */
+  left: CapturedLog;
+  /** Log selected second (shown on the right). */
+  right: CapturedLog;
+  onClose: () => void;
+};
+
+type EqualOp = Extract<DiffOp, { kind: "equal" }>;
+type AddedOp = Extract<DiffOp, { kind: "added" }>;
+type RemovedOp = Extract<DiffOp, { kind: "removed" }>;
+type ChangedOp = Extract<DiffOp, { kind: "changed" }>;
+
+/** Walk the JsonNode tree and pretty-print it back to a JSON string for the
+ *  expanded-equal-subtree view. The node is a plain object structure so
+ *  `JSON.stringify` produces correct output. */
+function nodeToJsonString(node: JsonNode, indent = 2): string {
+  return JSON.stringify(nodeToJsonValue(node), null, indent);
+}
+
+function nodeToJsonValue(node: JsonNode): unknown {
+  switch (node.kind) {
+    case "primitive":
+      return node.value;
+    case "array":
+      return node.value.map(nodeToJsonValue);
+    case "object": {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(node.value)) {
+        out[k] = nodeToJsonValue(v);
+      }
+      return out;
+    }
+  }
+}
+
+/** The parent path of a JSON path string. E.g. `messages[3].content` →
+ *  `messages[3]`, `messages[3]` → `messages`, `messages` → `""`. */
+function parentPath(path: string): string {
+  if (path === "") return "";
+  for (let i = path.length - 1; i >= 0; i--) {
+    const ch = path[i];
+    if (ch === "." || ch === "[") {
+      return path.substring(0, i);
+    }
+  }
+  return "";
+}
+
+/** Group contiguous deep-equal ops (object/array, not primitive) that share
+ *  a common parent into a single collapsed row, so an unchanged block of N
+ *  sibling subtrees renders as one row instead of N. Primitive equals
+ *  always render as their own row (they're 1 line each). */
+type GroupedOp = { kind: "single"; op: DiffOp } | { kind: "equal-run"; ops: EqualOp[] };
+
+function isDeepEqual(op: DiffOp): op is EqualOp {
+  return op.kind === "equal" && (op.value.kind === "object" || op.value.kind === "array");
+}
+
+function groupContiguousEquals(ops: DiffOp[]): GroupedOp[] {
+  const out: GroupedOp[] = [];
+  let i = 0;
+  while (i < ops.length) {
+    const op = ops[i];
+    if (op !== undefined && isDeepEqual(op)) {
+      const startParent = parentPath(op.path);
+      let j = i + 1;
+      while (j < ops.length) {
+        const next = ops[j];
+        if (next === undefined) break;
+        if (!isDeepEqual(next)) break;
+        if (parentPath(next.path) !== startParent) break;
+        j++;
+      }
+      if (j - i > 1) {
+        const equalOps: EqualOp[] = [];
+        for (let k = i; k < j; k++) {
+          const eop = ops[k];
+          if (eop !== undefined && eop.kind === "equal") {
+            equalOps.push(eop);
+          }
+        }
+        out.push({ kind: "equal-run", ops: equalOps });
+        i = j;
+        continue;
+      }
+    }
+    if (op !== undefined) {
+      out.push({ kind: "single", op });
+    }
+    i++;
+  }
+  return out;
+}
+
+function EqualRunRow({
+  ops,
+  expanded,
+  onToggle,
+}: {
+  ops: EqualOp[];
+  expanded: boolean;
+  onToggle: () => void;
+}): JSX.Element {
+  const first = ops[0];
+  const last = ops[ops.length - 1];
+  if (first === undefined || last === undefined) {
+    return <div className="col-span-3 text-muted-foreground/40 text-xs">—</div>;
+  }
+  const firstPath = first.path;
+  const lastPath = last.path;
+  const label = ops.length === 1 ? firstPath : `${firstPath} … ${lastPath}`;
+  const summary =
+    first.value.kind === "array"
+      ? `${ops.length} equal arrays`
+      : first.value.kind === "object"
+        ? `${ops.length} equal objects`
+        : "equal";
+
+  return (
+    <div className="col-span-3">
+      <button
+        type="button"
+        onClick={onToggle}
+        className="w-full text-left flex items-center gap-2 px-2 py-1 text-xs text-muted-foreground hover:bg-muted/40 rounded cursor-pointer"
+      >
+        <ChevronRight
+          className={cn("size-3 transition-transform shrink-0", expanded && "rotate-90")}
+        />
+        <span className="font-mono truncate flex-1">{label}</span>
+        <span className="text-muted-foreground/60 shrink-0">({summary})</span>
+      </button>
+      {expanded && (
+        <div className="ml-5 mt-1 mb-2 space-y-2">
+          {ops.map((op) => (
+            <div key={op.path} className="border border-border/50 rounded p-2 bg-muted/20">
+              <div className="font-mono text-xs text-muted-foreground mb-1">{op.path}</div>
+              <JsonViewerFromString text={nodeToJsonString(op.value)} defaultExpandDepth={2} />
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function AddOrRemoveRow({
+  op,
+  kind,
+}: {
+  op: AddedOp | RemovedOp;
+  kind: "added" | "removed";
+}): JSX.Element {
+  const accent =
+    kind === "added"
+      ? "border-l-2 border-l-emerald-400/70 bg-emerald-500/5"
+      : "border-l-2 border-l-rose-400/70 bg-rose-500/5";
+  return (
+    <div className={cn("col-span-3 px-2 py-1 rounded text-xs", accent)}>
+      <div className="font-mono text-xs text-muted-foreground mb-0.5">{op.path}</div>
+      <div className="font-mono break-all">
+        {kind === "added" ? (
+          <span className="text-emerald-300/90">+ {previewNode(op.value, 400)}</span>
+        ) : (
+          <span className="text-rose-300/90 line-through">- {previewNode(op.value, 400)}</span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function ChangedRow({ op }: { op: ChangedOp }): JSX.Element {
+  return (
+    <div className="col-span-3 px-2 py-1 rounded text-xs border-l-2 border-l-amber-400/70 bg-amber-500/5">
+      <div className="font-mono text-xs text-muted-foreground mb-1">{op.path}</div>
+      <div className="grid grid-cols-2 gap-2">
+        <div className="font-mono text-rose-300/90 break-all line-through">
+          {previewNode(op.left, 400)}
+        </div>
+        <div className="font-mono text-emerald-300/90 break-all">{previewNode(op.right, 400)}</div>
+      </div>
+    </div>
+  );
+}
+
+function SideSummary({ log, side }: { log: CapturedLog; side: "left" | "right" }): JSX.Element {
+  const conversationId = getConversationId(log);
+  return (
+    <div className="flex-1 min-w-0 space-y-1 text-xs">
+      <div className="flex items-center gap-2">
+        <Badge
+          variant="outline"
+          className={cn(
+            "text-[10px] px-1.5 py-0 h-5 font-mono shrink-0",
+            side === "left"
+              ? "border-rose-500/40 text-rose-400"
+              : "border-emerald-500/40 text-emerald-400",
+          )}
+        >
+          {side === "left" ? "← Left" : "Right →"}
+        </Badge>
+        <span className="font-mono text-blue-400/80">#{log.id}</span>
+        {log.model !== null && (
+          <span className="font-mono text-muted-foreground truncate">{log.model}</span>
+        )}
+      </div>
+      <div className="flex items-center gap-3 text-muted-foreground font-mono">
+        {log.cacheCreationInputTokens !== null && log.cacheCreationInputTokens > 0 && (
+          <span className="text-emerald-400">
+            Cache +{formatTokens(log.cacheCreationInputTokens)}
+          </span>
+        )}
+        {log.cacheReadInputTokens !== null && log.cacheReadInputTokens > 0 && (
+          <span className="text-purple-400">Cache ~{formatTokens(log.cacheReadInputTokens)}</span>
+        )}
+        <span className="truncate" title={log.timestamp}>
+          {log.timestamp}
+        </span>
+      </div>
+      <div className="text-muted-foreground/70 font-mono truncate" title={conversationId}>
+        session: {conversationId}
+      </div>
+    </div>
+  );
+}
+
+export function CompareDrawer({ left, right, onClose }: CompareDrawerProps): JSX.Element {
+  // Memoize the diff so re-renders (e.g. parent re-renders) don't recompute.
+  const ops = useMemo<DiffOp[]>(() => {
+    const l = normalizeRequest(parseRequest(left.rawRequestBody) ?? left.rawRequestBody);
+    const r = normalizeRequest(parseRequest(right.rawRequestBody) ?? right.rawRequestBody);
+    return diffTrees(l, r);
+  }, [left.rawRequestBody, right.rawRequestBody]);
+
+  const grouped = useMemo(() => groupContiguousEquals(ops), [ops]);
+
+  // Track which collapsed equal runs are expanded.
+  const [expandedRuns, setExpandedRuns] = useState<Set<number>>(new Set());
+  const toggleRun = (idx: number) => {
+    setExpandedRuns((prev) => {
+      const next = new Set(prev);
+      if (next.has(idx)) next.delete(idx);
+      else next.add(idx);
+      return next;
+    });
+  };
+
+  // Esc keybinding + body scroll lock while the drawer is open.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    document.addEventListener("keydown", onKey);
+    const prevOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = prevOverflow;
+    };
+  }, [onClose]);
+
+  const sameSession = getConversationId(left) === getConversationId(right);
+  const allEqual = ops.length === 1 && ops[0]?.kind === "equal";
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex justify-end"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Compare two log requests"
+    >
+      {/* Backdrop */}
+      <button
+        type="button"
+        onClick={onClose}
+        aria-label="Close compare drawer"
+        className="absolute inset-0 bg-black/40 cursor-default"
+        tabIndex={-1}
+      />
+
+      {/* Drawer panel */}
+      <div
+        className={cn(
+          "relative bg-background border-l border-border shadow-xl",
+          "w-full md:w-[70vw] max-w-[1100px] flex flex-col h-full",
+        )}
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => e.stopPropagation()}
+      >
+        {/* Header */}
+        <div className="flex items-start gap-4 px-4 py-3 border-b border-border">
+          <div className="flex-1 flex gap-4 min-w-0">
+            <SideSummary log={left} side="left" />
+            <SideSummary log={right} side="right" />
+          </div>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close"
+            className="shrink-0 p-1 rounded text-muted-foreground hover:text-foreground hover:bg-muted cursor-pointer"
+          >
+            <X className="size-4" />
+          </button>
+        </div>
+
+        {!sameSession && (
+          <div className="px-4 py-1.5 text-xs text-amber-400 bg-amber-500/10 border-b border-border">
+            Heads up: the two selected logs are from different sessions.
+          </div>
+        )}
+
+        {/* Body: path-aligned two-pane diff */}
+        <div className="flex-1 min-h-0 overflow-y-auto">
+          {allEqual ? (
+            <div className="px-4 py-12 text-center text-muted-foreground text-sm">
+              The two Request payloads are identical.
+            </div>
+          ) : (
+            <div className="grid grid-cols-[200px_1fr_1fr] gap-x-2 gap-y-0.5 px-3 py-2 text-xs">
+              {/* Column headers */}
+              <div className="col-span-3 grid grid-cols-[200px_1fr_1fr] gap-x-2 pb-2 mb-2 border-b border-border text-[10px] uppercase tracking-wider text-muted-foreground">
+                <span>Path</span>
+                <span>Left (Log #{left.id})</span>
+                <span>Right (Log #{right.id})</span>
+              </div>
+
+              {grouped.map((g, i) => {
+                if (g.kind === "equal-run") {
+                  return (
+                    <EqualRunRow
+                      key={`r${i}`}
+                      ops={g.ops}
+                      expanded={expandedRuns.has(i)}
+                      onToggle={() => toggleRun(i)}
+                    />
+                  );
+                }
+                const op = g.op;
+                if (op.kind === "equal") {
+                  return (
+                    <div
+                      key={`e${i}`}
+                      className="col-span-3 grid grid-cols-[200px_1fr_1fr] gap-x-2 px-2 py-0.5 text-muted-foreground"
+                    >
+                      <span className="font-mono text-xs truncate" title={op.path}>
+                        {op.path}
+                      </span>
+                      <span className="font-mono text-xs break-all opacity-60">
+                        {previewNode(op.value, 200)}
+                      </span>
+                      <span className="font-mono text-xs break-all opacity-60">
+                        {previewNode(op.value, 200)}
+                      </span>
+                    </div>
+                  );
+                }
+                if (op.kind === "added") {
+                  return <AddOrRemoveRow key={`a${i}`} op={op} kind="added" />;
+                }
+                if (op.kind === "removed") {
+                  return <AddOrRemoveRow key={`r${i}`} op={op} kind="removed" />;
+                }
+                return <ChangedRow key={`c${i}`} op={op} />;
+              })}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/proxy-viewer/ConversationGroup.tsx

@@ -9,12 +9,22 @@ import {
   type ConversationGroupData,
 } from "./ConversationHeader";
 import { LogEntry } from "./LogEntry";
+import type { CacheTrendEntry } from "./cacheTrend";
 
 export type ConversationGroupProps = {
   group: ConversationGroupData;
   viewMode?: "simple" | "full";
   /** Live strip-Claude-Code-billing-header flag from the viewer container. */
   strip: boolean;
+  /**
+   * Pre-computed per-log cache token trend map (keyed by `log.id`) shared
+   * across the whole viewer. Each `LogEntry` looks up its own entry.
+   */
+  cacheTrends?: Map<number, CacheTrendEntry>;
+  /** Set of log ids currently marked for comparison. Forwarded to each `LogEntry`. */
+  selectedSet: Set<number>;
+  /** Toggle a log in/out of the comparison selection. */
+  onToggleSelect: (logId: number) => void;
 };
 
 function computeStats(logs: CapturedLog[]): {
@@ -34,6 +44,9 @@ export const ConversationGroup = memo(function ({
   group,
   viewMode = "simple",
   strip,
+  cacheTrends,
+  selectedSet,
+  onToggleSelect,
 }: ConversationGroupProps): JSX.Element {
   const [expanded, setExpanded] = useState(false);
 
@@ -73,6 +86,9 @@ export const ConversationGroup = memo(function ({
               viewMode={viewMode}
               suppressApiFormatBadge={!mixed}
               strip={strip}
+              cacheTrend={cacheTrends?.get(log.id) ?? null}
+              isSelected={selectedSet.has(log.id)}
+              onToggleSelect={onToggleSelect}
             />
           ))}
         </div>

package/src/components/proxy-viewer/LogEntry.tsx

@@ -12,6 +12,7 @@ import { LogEntryHeader } from "./LogEntryHeader";
 import { ReplayDialog } from "./ReplayDialog";
 import { ResponseView } from "./ResponseView";
 import { StreamingChunkSequence } from "./StreamingChunkSequence";
+import type { CacheTrendEntry } from "./cacheTrend";
 
 export type LogEntryProps = {
   log: CapturedLog;
@@ -25,6 +26,15 @@ export type LogEntryProps = {
    * cost).
    */
   strip: boolean;
+  /**
+   * Per-log cache token trend, looked up in the viewer-level trend map.
+   * `null` (or absent) means the header should render with no arrows.
+   */
+  cacheTrend?: CacheTrendEntry | null;
+  /** Whether this log is currently marked for comparison. */
+  isSelected?: boolean;
+  /** Toggle this log in/out of the comparison selection. */
+  onToggleSelect?: (logId: number) => void;
 };
 
 /**
@@ -131,6 +141,9 @@ export const LogEntry = memo(function ({
   viewMode = "simple",
   suppressApiFormatBadge = false,
   strip,
+  cacheTrend = null,
+  isSelected = false,
+  onToggleSelect,
 }: LogEntryProps): JSX.Element {
   const [expanded, setExpanded] = useState<boolean>(false);
   const [requestCopied, setRequestCopied] = useState<boolean>(false);
@@ -186,13 +199,21 @@ export const LogEntry = memo(function ({
 
   return (
     <>
-      <div className={cn("border border-border rounded-lg mb-3 overflow-hidden")}>
+      <div
+        className={cn(
+          "border border-border rounded-lg mb-3 overflow-hidden",
+          isSelected && "border-l-2 border-l-amber-400",
+        )}
+      >
         <LogEntryHeader
           log={log}
           parsedRequest={parsedRequest}
           expanded={expanded}
           onToggle={() => setExpanded(!expanded)}
           suppressApiFormatBadge={suppressApiFormatBadge}
+          cacheTrend={cacheTrend}
+          isSelected={isSelected}
+          onToggleSelect={onToggleSelect}
         />
 
         {expanded && (

package/src/components/proxy-viewer/LogEntryHeader.tsx

@@ -1,4 +1,7 @@
 import {
+  ArrowDown,
+  ArrowUp,
+  Check,
   ChevronDown,
   ChevronRight,
   Clock,
@@ -17,6 +20,7 @@ import { cn, formatTokens, getStatusCategory, type StatusCategory } from "../../
 import type { CapturedLog, InspectorRequest } from "../../proxy/schemas";
 import { Badge } from "../ui/badge";
 import { ProviderLogo, detectProvider } from "../providers/ProviderLogo";
+import type { CacheTrend } from "./cacheTrend";
 
 function formatElapsed(ms: number): string {
   if (ms < 1000) return `${ms}ms`;
@@ -30,6 +34,26 @@ const STATUS_BADGE_CLASSES: Record<StatusCategory, string> = {
   pending: "bg-muted text-muted-foreground border-border",
 };
 
+/**
+ * Inline trend indicator: small arrow (green up / red down) plus the absolute
+ * delta in compact form. Returns `null` when there is no trend to display.
+ */
+function CacheTrendIndicator({ trend }: { trend: CacheTrend | null }): JSX.Element | null {
+  if (trend === null) return null;
+  const isUp = trend.direction === "up";
+  const Icon = isUp ? ArrowUp : ArrowDown;
+  const sign = isUp ? "+" : "-";
+  return (
+    <span className="flex items-center gap-0.5 text-muted-foreground tabular-nums">
+      <Icon className={isUp ? "size-3 text-emerald-400" : "size-3 text-rose-400"} />
+      <span className="font-mono">
+        {sign}
+        {formatTokens(trend.delta)}
+      </span>
+    </span>
+  );
+}
+
 export type LogEntryHeaderProps = {
   log: CapturedLog;
   parsedRequest: InspectorRequest | null;
@@ -37,6 +61,16 @@ export type LogEntryHeaderProps = {
   onToggle: () => void;
   /** Suppress the API format badge when log is displayed within a group */
   suppressApiFormatBadge?: boolean;
+  /**
+   * Per-log cache token trend (creation + read) relative to the previous log
+   * in the same conversation group. When `undefined` or a field is `null`,
+   * the corresponding cache span renders as it did before — no arrow.
+   */
+  cacheTrend?: { creation: CacheTrend | null; read: CacheTrend | null } | null;
+  /** Whether this log is currently marked for comparison. */
+  isSelected?: boolean;
+  /** Toggle this log in/out of the comparison selection. */
+  onToggleSelect?: (logId: number) => void;
 };
 
 export const LogEntryHeader = memo(function ({
@@ -45,6 +79,9 @@ export const LogEntryHeader = memo(function ({
   expanded,
   onToggle,
   suppressApiFormatBadge = false,
+  cacheTrend = null,
+  isSelected = false,
+  onToggleSelect,
 }: LogEntryHeaderProps): JSX.Element {
   const statusCategory = getStatusCategory(log.responseStatus);
 
@@ -74,6 +111,27 @@ export const LogEntryHeader = memo(function ({
         }
       }}
     >
+      {/* Selection checkbox (for log-request comparison) */}
+      {onToggleSelect !== undefined && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            onToggleSelect(log.id);
+          }}
+          aria-label={isSelected ? "Deselect for comparison" : "Select for comparison"}
+          aria-pressed={isSelected}
+          className={cn(
+            "shrink-0 size-4 rounded-sm border flex items-center justify-center transition-colors cursor-pointer",
+            isSelected
+              ? "bg-amber-400 border-amber-400 text-amber-950"
+              : "border-muted-foreground/40 hover:border-amber-400 hover:bg-amber-400/10",
+          )}
+        >
+          {isSelected && <Check className="size-3" strokeWidth={3} />}
+        </button>
+      )}
+
       {/* Request ID */}
       <span className="text-blue-400/80 font-mono text-xs font-semibold tabular-nums shrink-0">
         #{log.id}
@@ -163,6 +221,7 @@ export const LogEntryHeader = memo(function ({
       {/* Cache tokens */}
       {log.cacheCreationInputTokens !== null && log.cacheCreationInputTokens > 0 && (
         <span className="flex items-center gap-1 text-xs shrink-0">
+          <CacheTrendIndicator trend={cacheTrend?.creation ?? null} />
           <span className="font-mono tabular-nums text-emerald-400">
             Cache +{formatTokens(log.cacheCreationInputTokens)}
           </span>
@@ -170,6 +229,7 @@ export const LogEntryHeader = memo(function ({
       )}
       {log.cacheReadInputTokens !== null && log.cacheReadInputTokens > 0 && (
         <span className="flex items-center gap-1 text-xs shrink-0">
+          <CacheTrendIndicator trend={cacheTrend?.read ?? null} />
           <span className="font-mono tabular-nums text-purple-400">
             Cache ~{formatTokens(log.cacheReadInputTokens)}
           </span>

package/src/components/proxy-viewer/cacheTrend.ts

@@ -0,0 +1,50 @@
+import type { ConversationGroupData } from "./ConversationHeader";
+
+/**
+ * Trend direction for a single cache token field, comparing the current log
+ * to the previous log in the same conversation group.
+ */
+export type CacheTrend = { direction: "up" | "down"; delta: number };
+
+/**
+ * Per-log trend entry. `creation` covers `cacheCreationInputTokens`,
+ * `read` covers `cacheReadInputTokens`. Each field is `null` when there is
+ * no previous log to compare against, when the current log has no value for
+ * the field, or when the values are equal (no visual change).
+ */
+export type CacheTrendEntry = { creation: CacheTrend | null; read: CacheTrend | null };
+
+/**
+ * Build a `logId -> CacheTrendEntry` map for every log that has a previous
+ * log in its conversation group. Pure: does not mutate `groups`. Walks each
+ * group in array order (which is the timestamp-sorted order produced by
+ * `groupLogsByConversation`), so "previous log" is the adjacent entry in
+ * that order.
+ */
+export function computeCacheTrends(groups: ConversationGroupData[]): Map<number, CacheTrendEntry> {
+  const result = new Map<number, CacheTrendEntry>();
+
+  for (const group of groups) {
+    const logs = group.logs;
+    for (let i = 1; i < logs.length; i++) {
+      const prev = logs[i - 1];
+      const curr = logs[i];
+      if (prev === undefined || curr === undefined) continue;
+
+      result.set(curr.id, {
+        creation: compareField(prev.cacheCreationInputTokens, curr.cacheCreationInputTokens),
+        read: compareField(prev.cacheReadInputTokens, curr.cacheReadInputTokens),
+      });
+    }
+  }
+
+  return result;
+}
+
+function compareField(previous: number | null, current: number | null): CacheTrend | null {
+  if (current === null) return null;
+  if (previous === null) return null;
+  if (current > previous) return { direction: "up", delta: current - previous };
+  if (current < previous) return { direction: "down", delta: previous - current };
+  return null;
+}