@progen-labs/spectra 0.0.0-stage → 0.1.0

package/src/components/TreeView.jsx

@@ -0,0 +1,173 @@
+import { select, zoom, zoomIdentity } from 'd3';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { ROW_HEIGHT } from '../layout.js';
+
+const CULL_MARGIN = 200;
+
+function linkPath(link) {
+  const sx = link.source.px + link.source.labelWidth - 10;
+  const sy = link.source.py;
+  const tx = link.target.px;
+  const ty = link.target.py;
+  const mid = (sx + tx) / 2;
+  return `M${sx},${sy}C${mid},${sy} ${mid},${ty} ${tx},${ty}`;
+}
+
+function TreeNode({ node, isSelected, onActivate, onToggle }) {
+  const view = node.view;
+  const hasChildren = view.expandable;
+  const heat = Math.max(0, Math.min(1, view.heat || 0));
+  const cls = [
+    'node',
+    view.isDir ? 'dir' : 'file',
+    view.vendor ? 'vendor' : '',
+    isSelected ? 'selected' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+  const r = view.r || 5;
+  return (
+    <g className={cls} transform={`translate(${node.px},${node.py})`}>
+      <title>{view.tooltip || node.label}</title>
+      <rect
+        className="node-hit"
+        x={-r}
+        y={-ROW_HEIGHT / 2 + 1}
+        width={node.labelWidth}
+        height={ROW_HEIGHT - 2}
+        rx={4}
+      />
+      <circle
+        className="node-dot"
+        r={r}
+        style={{ '--heat-pct': `${Math.round(12 + heat * 88)}%` }}
+        onClick={() => (hasChildren ? onToggle(node) : onActivate(node))}
+      />
+      {hasChildren && (
+        <text className="node-glyph" y={3.5} textAnchor="middle">
+          {node.children ? '−' : '+'}
+        </text>
+      )}
+      <text
+        className="node-label"
+        x={r + 6}
+        y={4}
+        role="button"
+        tabIndex={0}
+        onClick={() => onActivate(node)}
+        onKeyDown={e => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            onActivate(node);
+          }
+        }}
+      >
+        {node.label}
+      </text>
+    </g>
+  );
+}
+
+/** Pan/zoomable node-link tree. Wheel scrolls, ctrl/cmd + wheel zooms. */
+export default function TreeView({
+  layout,
+  selectedKey,
+  centerKey,
+  centerTick,
+  anchor = 0.12,
+  onActivate,
+  onToggle,
+}) {
+  const svgRef = useRef(null);
+  const zoomRef = useRef(null);
+  const sizeRef = useRef({ width: 800, height: 600 });
+  const [size, setSize] = useState(sizeRef.current);
+  const [transform, setTransform] = useState(zoomIdentity);
+
+  useEffect(() => {
+    const svg = svgRef.current;
+    const behavior = zoom()
+      .scaleExtent([0.25, 2.5])
+      .filter(e => (e.type === 'wheel' ? e.ctrlKey || e.metaKey : !e.button))
+      .on('zoom', e => setTransform(e.transform));
+    zoomRef.current = behavior;
+    select(svg).call(behavior).on('dblclick.zoom', null);
+    const onWheel = e => {
+      if (e.ctrlKey || e.metaKey) return;
+      e.preventDefault();
+      select(svg).call(behavior.translateBy, -e.deltaX, -e.deltaY);
+    };
+    svg.addEventListener('wheel', onWheel, { passive: false });
+    const observer = new ResizeObserver(([entry]) => {
+      sizeRef.current = {
+        width: entry.contentRect.width,
+        height: entry.contentRect.height,
+      };
+      setSize(sizeRef.current);
+    });
+    observer.observe(svg);
+    return () => {
+      svg.removeEventListener('wheel', onWheel);
+      observer.disconnect();
+      select(svg).on('.zoom', null);
+    };
+  }, []);
+
+  // Re-centre on an explicit request (new report, search, list click) only.
+  useEffect(() => {
+    const node = layout.byKey.get(centerKey) || layout.root;
+    const { width, height } = sizeRef.current;
+    const target = zoomIdentity.translate(
+      Math.max(60, width * anchor) - node.px,
+      height / 2 - node.py,
+    );
+    select(svgRef.current)
+      .transition()
+      .duration(centerTick > 0 ? 300 : 0)
+      .call(zoomRef.current.transform, target);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [centerTick]);
+
+  const visible = useMemo(() => {
+    const top = (-transform.y - CULL_MARGIN) / transform.k;
+    const bottom = (size.height - transform.y + CULL_MARGIN) / transform.k;
+    const inView = n => n.py >= top && n.py <= bottom;
+    return {
+      nodes: layout.nodes.filter(inView),
+      links: layout.links.filter(l => inView(l.source) || inView(l.target)),
+    };
+  }, [layout, transform, size.height]);
+
+  return (
+    <svg
+      ref={svgRef}
+      className="tree-svg"
+      role="tree"
+      aria-label="Performance heat tree"
+    >
+      <g
+        transform={`translate(${transform.x},${transform.y}) scale(${transform.k})`}
+      >
+        <g className="tree-links">
+          {visible.links.map(l => (
+            <path
+              key={`${l.source.data.id}>${l.target.data.id}`}
+              d={linkPath(l)}
+            />
+          ))}
+        </g>
+        <g>
+          {visible.nodes.map(n => (
+            <TreeNode
+              key={n.data.id}
+              node={n}
+              isSelected={n.data.id === selectedKey}
+              onActivate={onActivate}
+              onToggle={onToggle}
+            />
+          ))}
+        </g>
+      </g>
+    </svg>
+  );
+}

package/src/components/Vitals.jsx

@@ -0,0 +1,163 @@
+import { fmtMs, fmtNumber } from '../format.js';
+
+// Web-vitals style thresholds: [good, poor]. `hero` ones get a full card.
+const RATINGS = [
+  {
+    key: 'tbt',
+    label: 'Total blocking time',
+    get: r => r.vitals.tbtMs,
+    limits: [200, 600],
+    fmt: fmtMs,
+    hero: true,
+  },
+  {
+    key: 'long',
+    label: 'Longest task',
+    get: r => r.vitals.maxLongTaskMs,
+    limits: [50, 200],
+    fmt: fmtMs,
+    hero: true,
+  },
+  {
+    key: 'inp',
+    label: 'Slowest interaction',
+    get: r => r.vitals.inpMs,
+    limits: [200, 500],
+    fmt: fmtMs,
+    hero: true,
+  },
+  {
+    key: 'wasted',
+    label: 'Wasted React renders',
+    get: r =>
+      r.react.detected
+          ? (r.react && r.react.components ? r.react.components.reduce((s, c) => s + c.wasted, 0) : 0)
+        : null,
+    limits: [20, 200],
+    fmt: fmtNumber,
+    hero: true,
+  },
+  {
+    key: 'lcp',
+    label: 'Largest paint',
+    get: r => r.vitals.lcpMs,
+    limits: [2500, 4000],
+    fmt: fmtMs,
+  },
+  {
+    key: 'fcp',
+    label: 'First paint',
+    get: r => r.vitals.fcpMs,
+    limits: [1800, 3000],
+    fmt: fmtMs,
+  },
+  {
+    key: 'cls',
+    label: 'Layout shift',
+    get: r => r.vitals.cls,
+    limits: [0.1, 0.25],
+    fmt: v => v.toFixed(3),
+  },
+  {
+    key: 'dom',
+    label: 'DOM nodes',
+    get: r => r.memory.domNodes,
+    limits: [1500, 3000],
+    fmt: fmtNumber,
+  },
+  {
+    key: 'heap',
+    label: 'Heap growth',
+    get: r => r.memory.heapGrowthMb,
+    limits: [30, 100],
+    fmt: v => `${v.toFixed(1)} MB`,
+  },
+  {
+    key: 'forced',
+    label: 'Forced reflows',
+    get: r => r.totals.forcedLayoutCount + r.totals.forcedStyleCount,
+    limits: [10, 100],
+    fmt: fmtNumber,
+  },
+];
+
+const LABELS = { good: 'Good', warn: 'Needs work', poor: 'Poor', none: 'n/a' };
+const ICONS = { good: '✓', warn: '!', poor: '✕', none: '–' };
+const GAUGE_HEADROOM = 1.5;
+
+function rate(value, [good, poor]) {
+  if (value == null) return 'none';
+  if (value <= good) return 'good';
+  return value >= poor ? 'poor' : 'warn';
+}
+
+function Gauge({ value, limits }) {
+  const max = limits[1] * GAUGE_HEADROOM;
+  const pct = n => `${Math.min(100, (n / max) * 100)}%`;
+  return (
+    <div
+      className="gauge"
+      aria-hidden="true"
+      style={{ '--g': pct(limits[0]), '--p': pct(limits[1]) }}
+    >
+      <span className="gauge-needle" style={{ left: pct(value) }} />
+    </div>
+  );
+}
+
+function HeroCard({ vital, value, rating }) {
+  const [good, poor] = vital.limits;
+  return (
+    <div className={`vital-hero rating-${rating}`}>
+      <div className="vital-label">{vital.label}</div>
+      <div className="vital-value">
+        {value == null ? '–' : vital.fmt(value)}
+      </div>
+      <div className="vital-rating">
+        <span aria-hidden="true">{ICONS[rating]}</span> {LABELS[rating]}
+      </div>
+      {value != null && <Gauge value={value} limits={vital.limits} />}
+      <div className="vital-target muted">
+        Good ≤ {vital.fmt(good)} · Poor ≥ {vital.fmt(poor)}
+      </div>
+    </div>
+  );
+}
+
+function Chip({ vital, value, rating }) {
+  return (
+    <div className={`vital-chip rating-${rating}`}>
+      <span className="vital-chip-icon" aria-hidden="true">
+        {ICONS[rating]}
+      </span>
+      <span className="vital-chip-label">{vital.label}</span>
+      <b>{value == null ? '–' : vital.fmt(value)}</b>
+      <span className="visually-hidden">{LABELS[rating]}</span>
+    </div>
+  );
+}
+
+export default function Vitals({ report }) {
+  const rows = RATINGS.map(v => {
+    const value = v.get(report);
+    return { vital: v, value, rating: rate(value, v.limits) };
+  });
+  return (
+    <div className="vitals-block">
+      <div className="vitals-hero">
+        {rows
+          .filter(r => r.vital.hero)
+          .map(r => (
+            <HeroCard key={r.vital.key} {...r} />
+          ))}
+      </div>
+      <div className="vitals-secondary">
+        {rows
+          .filter(r => !r.vital.hero)
+          .map(r => (
+            <Chip key={r.vital.key} {...r} />
+          ))}
+      </div>
+    </div>
+  );
+}

package/src/culprits.js

@@ -0,0 +1,127 @@
+export const SEVERITY_RANK = { critical: 3, warning: 2, info: 1 };
+
+export const SEVERITY = {
+  critical: { label: 'Critical', icon: '✕' },
+  warning: { label: 'Warning', icon: '!' },
+  info: { label: 'Note', icon: 'i' },
+};
+
+const isVendorFile = file => file.includes('node_modules/');
+const higher = (a, b) => (SEVERITY_RANK[b] > SEVERITY_RANK[a] ? b : a);
+
+export const culpritKey = c => `${c.fn || c.name}|${c.file}`;
+
+/** The finding to quote a fix from: most severe, then biggest impact. */
+function leadFinding(findings) {
+  return [...findings].sort(
+    (a, b) =>
+      SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] ||
+      b.impactMs - a.impactMs,
+  )[0];
+}
+
+/**
+ * The functions behind the report, merged across findings: one entry per
+ * function with its worst severity, the time it cost and the findings it
+ * appears in. Time is the largest figure seen (not a sum) because the same
+ * work is counted again by the total-blocking-time finding.
+ */
+export function topCulprits(report, hideVendor, limit = 12) {
+  const map = new Map();
+  const entryFor = (key, base) => {
+    let e = map.get(key);
+    if (!e) {
+      e = {
+        ...base,
+        key,
+        ms: 0,
+        severity: 'info',
+        findings: [],
+        categories: new Set(),
+      };
+      map.set(key, e);
+    }
+    return e;
+  };
+  for (const f of report.findings) {
+    for (const c of f.culprits || []) {
+      if (!c.file || (hideVendor && isVendorFile(c.file))) continue;
+      const e = entryFor(culpritKey(c), {
+        name: c.fn || '(unknown)',
+        file: c.file,
+        line: c.line,
+        lineKind: c.lineKind,
+        abs: c.abs,
+      });
+      e.ms = Math.max(e.ms, c.ms || 0);
+      e.severity = higher(e.severity, f.severity);
+      e.findings.push(f);
+      e.categories.add(f.category);
+    }
+  }
+  for (const h of report.hotFunctions || []) {
+    if (!h.file || (hideVendor && h.vendor)) continue;
+    const e = entryFor(culpritKey({ fn: h.name, file: h.file }), {
+      name: h.name,
+      file: h.file,
+      line: h.line,
+      lineKind: h.lineKind,
+      abs: h.abs,
+    });
+    e.ms = Math.max(e.ms, h.selfMs || 0);
+    if (!e.findings.length && h.share >= 10) e.severity = 'warning';
+  }
+  return [...map.values()]
+    .sort((a, b) => b.ms - a.ms)
+    .slice(0, limit)
+    .map(e => ({
+      ...e,
+      categories: [...e.categories],
+      lead: e.findings.length ? leadFinding(e.findings) : null,
+    }));
+}
+
+/**
+ * Collapses findings that blame the same function (typically a dozen long
+ * tasks all caused by one library call) into one group, so the list shows
+ * root causes instead of repeating them.
+ */
+export function groupFindings(findings) {
+  const buckets = new Map();
+  const order = [];
+  for (const f of findings) {
+    const first = f.culprits?.[0];
+    const key = first?.file ? culpritKey(first) : `solo:${f.id}`;
+    if (!buckets.has(key)) {
+      buckets.set(key, []);
+      order.push(key);
+    }
+    buckets.get(key).push(f);
+  }
+  const items = order.map(key => {
+    const members = buckets.get(key);
+    if (members.length === 1)
+      return {
+        kind: 'single',
+        id: members[0].id,
+        severity: members[0].severity,
+        impactMs: members[0].impactMs,
+        finding: members[0],
+      };
+    const lead = leadFinding(members);
+    return {
+      kind: 'group',
+      id: `group:${key}`,
+      severity: members.reduce((s, m) => higher(s, m.severity), 'info'),
+      impactMs: Math.max(...members.map(m => m.impactMs)),
+      culprit: lead.culprits[0],
+      lead,
+      members: [...members].sort((a, b) => b.impactMs - a.impactMs),
+    };
+  });
+  return items.sort(
+    (a, b) =>
+      SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] ||
+      b.impactMs - a.impactMs,
+  );
+}

package/src/download.js

@@ -0,0 +1,18 @@
+/** Saves a Blob through the browser's download mechanism. */
+export function downloadBlob(blob, filename) {
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  // The download starts asynchronously; releasing the URL immediately can cancel it.
+  setTimeout(() => URL.revokeObjectURL(url), 30_000);
+}
+
+export const downloadJson = (value, filename) =>
+  downloadBlob(
+    new Blob([JSON.stringify(value)], { type: 'application/json' }),
+    filename,
+  );

package/src/format.js

@@ -0,0 +1,26 @@
+export function fmtMs(ms) {
+  if (ms == null) return '–';
+  if (ms >= 1000) return `${(ms / 1000).toFixed(2)} s`;
+  if (ms >= 100) return `${Math.round(ms)} ms`;
+  if (ms >= 1) return `${ms.toFixed(1)} ms`;
+  return `${ms.toFixed(2)} ms`;
+}
+
+export function fmtBytes(n) {
+  if (n == null) return '–';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+export function fmtNumber(n) {
+  return n == null ? '–' : Number(n).toLocaleString();
+}
+
+export function splitPath(path) {
+  const slash = path.lastIndexOf('/');
+  return {
+    dir: slash < 0 ? '' : path.slice(0, slash + 1),
+    name: path.slice(slash + 1),
+  };
+}

package/src/heat.js

@@ -0,0 +1,177 @@
+import { fmtMs, fmtNumber } from './format.js';
+
+export const FILE_METRICS = [
+  {
+    id: 'selfMs',
+    label: 'CPU self time',
+    unit: 'ms',
+    hint: 'JavaScript executed by functions in this file (excluding callees).',
+  },
+  {
+    id: 'blockMs',
+    label: 'Main-thread blocking',
+    unit: 'ms',
+    hint: 'Self time inside long tasks (>50 ms): what made the page unresponsive.',
+  },
+  {
+    id: 'reactMs',
+    label: 'React render time',
+    unit: 'ms',
+    hint: 'Time React spent rendering components defined in this file (self time).',
+  },
+  {
+    id: 'wasted',
+    label: 'Wasted re-renders',
+    unit: '',
+    hint: 'Renders where props, state and context were identical.',
+  },
+  {
+    id: 'renders',
+    label: 'React renders',
+    unit: '',
+    hint: 'How many times components in this file rendered.',
+  },
+  {
+    id: 'forcedCount',
+    label: 'Forced reflows',
+    unit: '',
+    hint: 'Synchronous layouts/style recalcs triggered by code in this file.',
+  },
+];
+
+export const formatMetric = (metric, value) =>
+  metric.unit === 'ms' ? fmtMs(value) : fmtNumber(Math.round(value));
+
+/**
+ * Directory tree of the profiled files, aggregated by `metric` and sorted
+ * hottest first. Single-child directory chains are merged.
+ */
+export function buildFileTree(files, metric, { hideVendor, rootName = 'target-frontend' } = {}) {
+  const root = {
+    id: '',
+    name: rootName,
+    isDir: true,
+    children: [],
+    parent: null,
+    value: 0,
+  };
+  const dirs = new Map([['', root]]);
+  const dirFor = dirPath => {
+    let node = dirs.get(dirPath);
+    if (node) return node;
+    const slash = dirPath.lastIndexOf('/');
+    const parent = dirFor(slash < 0 ? '' : dirPath.slice(0, slash));
+    node = {
+      id: dirPath,
+      name: dirPath.slice(slash + 1),
+      isDir: true,
+      children: [],
+      parent,
+      value: 0,
+    };
+    parent.children.push(node);
+    dirs.set(dirPath, node);
+    return node;
+  };
+  for (const file of files) {
+    if (hideVendor && file.vendor) continue;
+    const value = file[metric.id] || 0;
+    if (value <= 0) continue;
+    const slash = file.path.lastIndexOf('/');
+    const parent = dirFor(slash < 0 ? '' : file.path.slice(0, slash));
+    parent.children.push({
+      id: file.path,
+      name: file.path.slice(slash + 1),
+      isDir: false,
+      file,
+      vendor: file.vendor,
+      value,
+      parent,
+      children: [],
+    });
+  }
+  const finish = node => {
+    if (!node.isDir) return node.value;
+    node.value = node.children.reduce((sum, c) => sum + finish(c), 0);
+    node.children.sort((a, b) => b.value - a.value);
+    while (
+      node.parent &&
+      node.children.length === 1 &&
+      node.children[0].isDir
+    ) {
+      const only = node.children[0];
+      node.id = only.id;
+      node.name = `${node.name}/${only.name}`;
+      node.children = only.children;
+      node.children.forEach(c => {
+        c.parent = node;
+      });
+    }
+    return node.value;
+  };
+  finish(root);
+  const byId = new Map();
+  const index = node => {
+    byId.set(node.id, node);
+    node.children.forEach(index);
+  };
+  index(root);
+  return { root, byId, total: root.value };
+}
+
+/** Expand the root and the paths leading to the hottest leaves. */
+export function defaultExpanded(tree, topLeaves = 6) {
+  const leaves = [...tree.byId.values()]
+    .filter(n => !n.isDir)
+    .sort((a, b) => b.value - a.value)
+    .slice(0, topLeaves);
+  const set = new Set([tree.root.id]);
+  for (const leaf of leaves)
+    for (let n = leaf.parent; n; n = n.parent) set.add(n.id);
+  return set;
+}
+
+export function ancestorIds(tree, path) {
+  const ids = [];
+  for (let n = tree.byId.get(path)?.parent; n; n = n.parent) ids.push(n.id);
+  return ids;
+}
+
+/** Turn an aggregated node into the shape TreeView renders. */
+export function decorateFileNode(node, tree, metric) {
+  const heat = tree.total ? Math.sqrt(node.value / tree.total) : 0;
+  return {
+    isDir: node.isDir,
+    vendor: node.vendor,
+    expandable: node.isDir && node.children.length > 0,
+    heat,
+    r: 4 + heat * 7,
+    tooltip: `${node.id || tree.root.name}\n${metric.label}: ${formatMetric(metric, node.value)} (${tree.total ? Math.round((node.value / tree.total) * 100) : 0}% of total)`,
+  };
+}
+
+/** Heat + label data for the top-down call tree. */
+export function decorateCallNode(node, total) {
+  const share = total ? node.totalMs / total : 0;
+  const selfShare = total ? node.selfMs / total : 0;
+  return {
+    isDir: false,
+    vendor: node.vendor,
+    expandable: node.children.length > 0,
+    heat: Math.min(1, Math.sqrt(selfShare) * 1.6),
+    r: 4 + Math.sqrt(share) * 6,
+    tooltip: `${node.name}\n${node.file}${node.line ? `:${node.line}` : ''}\nself ${fmtMs(node.selfMs)} · total ${fmtMs(node.totalMs)}`,
+  };
+}
+
+export function defaultCallExpanded(root) {
+  const set = new Set();
+  const limit = root.totalMs * 0.08;
+  const walk = node => {
+    if (node.totalMs < limit || !node.children.length) return;
+    set.add(node.id);
+    node.children.forEach(walk);
+  };
+  walk(root);
+  return set;
+}