@progen-labs/spectra 0.0.0-stage → 0.1.1

package/src/components/TraceButton.jsx

@@ -0,0 +1,76 @@
+import { useState } from 'react';
+import { api } from '../api.js';
+import { fmtBytes } from '../format.js';
+import { DownloadIcon } from './Icons.jsx';
+
+/**
+ * Writes the recording's raw trace to reports/<id>.trace.json so it can be opened
+ * in Chrome DevTools → Performance → Load profile. (The report JSON itself is this
+ * tool's own format and cannot be loaded there.)
+ */
+export default function TraceButton({ reportId }) {
+  const [state, setState] = useState({ status: 'idle' });
+
+  const save = async () => {
+    setState({ status: 'working' });
+    try {
+      const result = await api.saveTrace(reportId);
+      setState({ status: 'done', ...result });
+    } catch (err) {
+      setState({ status: 'error', message: err.message });
+    }
+  };
+
+  return (
+    <span className="trace-button">
+      <button
+        type="button"
+        onClick={save}
+        disabled={state.status === 'working'}
+      >
+        {state.status === 'working' ? (
+          'Preparing…'
+        ) : (
+          <>
+            <DownloadIcon /> Trace for Chrome DevTools
+          </>
+        )}
+      </button>
+      {state.status !== 'idle' && state.status !== 'working' && (
+        <div className={`trace-note ${state.status}`} role="status">
+          <button
+            type="button"
+            className="close"
+            aria-label="Dismiss"
+            onClick={() => setState({ status: 'idle' })}
+          >
+            ×
+          </button>
+          {state.status === 'error' ? (
+            state.message
+          ) : (
+            <>
+              <b>Saved</b> <code>{state.path}</code> ({fmtBytes(state.size)}).
+              <ol>
+                <li>
+                  In Chrome open DevTools (<kbd>F12</kbd>) → <b>Performance</b>.
+                </li>
+                <li>
+                  Click <b>Load profile…</b> (the ↑ icon) and choose that file —
+                  or{' '}
+                  <a
+                    href={`/api/reports/${encodeURIComponent(reportId)}/trace`}
+                    download
+                  >
+                    download it
+                  </a>{' '}
+                  first.
+                </li>
+              </ol>
+            </>
+          )}
+        </div>
+      )}
+    </span>
+  );
+}

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