@progen-labs/spectra 0.0.0-stage → 0.1.0

package/src/components/LongTasks.jsx

@@ -0,0 +1,199 @@
+import { fmtMs } from '../format.js';
+import CodeRef from './CodeRef.jsx';
+
+const CATS = [
+  ['scripting', 'Scripting', 'var(--cat-1)'],
+  ['layout', 'Layout', 'var(--cat-2)'],
+  ['style', 'Style', 'var(--cat-3)'],
+  ['paint', 'Paint', 'var(--cat-4)'],
+  ['gc', 'GC', 'var(--cat-5)'],
+  ['compile', 'Compile', 'var(--cat-6)'],
+  ['parse', 'Parse', 'var(--cat-6)'],
+  ['other', 'Other', 'var(--cat-other)'],
+];
+
+/** Every main-thread task over 8 ms on a time axis; long tasks (>50 ms) stand out. */
+function Timeline({ report }) {
+  const total = Math.max(
+    report.meta.durationMs,
+    ...report.timeline.map(t => t.startMs + t.durMs),
+    1,
+  );
+  const maxDur = Math.max(...report.timeline.map(t => t.durMs), 50);
+  const H = 90;
+  return (
+    <svg
+      className="timeline"
+      viewBox={`0 0 1000 ${H + 18}`}
+      preserveAspectRatio="none"
+      role="img"
+      aria-label="Main-thread tasks over time"
+    >
+      <line
+        x1="0"
+        x2="1000"
+        y1={H - (50 / maxDur) * H}
+        y2={H - (50 / maxDur) * H}
+        className="limit"
+      />
+      {report.timeline.map(t => (
+        <rect
+          key={`${t.startMs}-${t.durMs}`}
+          x={(t.startMs / total) * 1000}
+          width={Math.max((t.durMs / total) * 1000, 1.5)}
+          y={H - (t.durMs / maxDur) * H}
+          height={(t.durMs / maxDur) * H}
+          className={t.durMs >= 50 ? 'task long' : 'task'}
+        >
+          <title>{`${fmtMs(t.durMs)} at ${(t.startMs / 1000).toFixed(2)}s`}</title>
+        </rect>
+      ))}
+      <text x="2" y={H + 13} className="axis">
+        0
+      </text>
+      <text x="998" y={H + 13} className="axis" textAnchor="end">
+        {(total / 1000).toFixed(1)} s
+      </text>
+      <text
+        x="998"
+        y={H - (50 / maxDur) * H - 3}
+        className="axis"
+        textAnchor="end"
+      >
+        50 ms
+      </text>
+    </svg>
+  );
+}
+
+export default function LongTasks({ report, onOpenFile }) {
+  return (
+    <div className="long-tasks">
+      <Timeline report={report} />
+      {report.longTasks.length === 0 ? (
+        <p className="muted pad">No task exceeded 50 ms in this recording.</p>
+      ) : (
+        <ul className="task-list">
+          {report.longTasks.map(t => {
+            const sum =
+              CATS.reduce((s, [k]) => s + (t.breakdown[k] || 0), 0) || 1;
+            return (
+              <li
+                key={t.startMs}
+                className={t.durMs >= 200 ? 'sev-critical' : 'sev-warning'}
+              >
+                <div className="task-head">
+                  <b>{fmtMs(t.durMs)}</b>
+                  <span>at {(t.startMs / 1000).toFixed(2)} s</span>
+                  <span className="chip">{t.trigger.type}</span>
+                  {t.trigger.detail && t.trigger.detail !== t.trigger.type && (
+                    <span className="muted mono">{t.trigger.detail}</span>
+                  )}
+                  {t.thrash && (
+                    <span className="chip chip-warn">layout thrashing</span>
+                  )}
+                  {t.forcedCount > 0 && (
+                    <span className="muted">
+                      {t.forcedCount} forced layouts
+                    </span>
+                  )}
+                </div>
+                <div className="breakdown-bar small">
+                  {CATS.map(([k, label, color]) =>
+                    t.breakdown[k] > 0 ? (
+                      <span
+                        key={k}
+                        style={{
+                          width: `${(t.breakdown[k] / sum) * 100}%`,
+                          background: color,
+                        }}
+                        title={`${label}: ${fmtMs(t.breakdown[k])}`}
+                      />
+                    ) : null,
+                  )}
+                </div>
+                <div className="task-cols">
+                  <div>
+                    <h4>Files</h4>
+                    {t.topFiles.map(f => (
+                      <button
+                        key={f.file}
+                        type="button"
+                        className="link mono row"
+                        onClick={() => onOpenFile(f.file)}
+                      >
+                        <span>{f.file}</span>
+                        <b>{fmtMs(f.ms)}</b>
+                      </button>
+                    ))}
+                  </div>
+                  <div>
+                    <h4>Functions</h4>
+                    {t.topFunctions.map(f => (
+                      <div
+                        key={`${f.name}${f.file}${f.line}`}
+                        className="row mono"
+                      >
+                        <span title={`${f.file}${f.line ? `:${f.line}` : ''}`}>
+                          {f.name}()&nbsp;
+                          <CodeRef
+                            file={f.file}
+                            line={f.line}
+                            lineKind={f.lineKind}
+                            abs={f.abs}
+                            onOpenFile={onOpenFile}
+                          />
+                        </span>
+                        <b>{fmtMs(f.ms)}</b>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+      {report.forcedReflows.length > 0 && (
+        <section className="pad">
+          <h2>
+            Forced reflows{' '}
+            <span className="muted">
+              (layout/style recalculated synchronously by script)
+            </span>
+          </h2>
+          <table className="data">
+            <thead>
+              <tr>
+                <th>Where</th>
+                <th>Kind</th>
+                <th>Count</th>
+                <th>Time</th>
+              </tr>
+            </thead>
+            <tbody>
+              {report.forcedReflows.slice(0, 20).map(f => (
+                <tr key={`${f.kind}${f.file}${f.fn}${f.line}`}>
+                  <td>
+                    <button
+                      type="button"
+                      className="link mono"
+                      onClick={() => f.file && onOpenFile(f.file)}
+                    >
+                      {f.fn && f.fn !== '(anonymous)' ? `${f.fn} — ` : ''}
+                      {f.file || 'unknown'}
+                      {f.line ? `:${f.line}` : ''}
+                    </button>
+                  </td>
+                  <td>{f.kind}</td>
+                  <td className="num">{f.count}</td>
+                  <td className="num">{fmtMs(f.ms)}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </section>
+      )}
+    </div>
+  );
+}

package/src/components/NetworkPanel.jsx

@@ -0,0 +1,98 @@
+import { fmtBytes, fmtMs, fmtNumber } from '../format.js';
+
+function Table({ title, rows, columns }) {
+  if (!rows.length) return null;
+  return (
+    <section>
+      <h2>{title}</h2>
+      <table className="data">
+        <thead>
+          <tr>
+            {columns.map(c => (
+              <th key={c.label}>{c.label}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map(r => (
+            <tr key={`${r.url}${r.startMs}`}>
+              {columns.map(c => (
+                <td
+                  key={c.label}
+                  className={c.num ? 'num' : 'mono'}
+                  title={c.title?.(r)}
+                >
+                  {c.get(r)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+
+export default function NetworkPanel({ report }) {
+  const { network, memory, totals } = report;
+  const cols = [
+    { label: 'Resource', get: r => r.name, title: r => r.url },
+    { label: 'Type', get: r => r.type },
+    { label: 'Time', get: r => fmtMs(r.durMs), num: true },
+    { label: 'Over the wire', get: r => fmtBytes(r.encoded), num: true },
+    { label: 'Decoded', get: r => fmtBytes(r.decoded), num: true },
+  ];
+  return (
+    <div className="network pad">
+      <div className="summary-row">
+        <span>{fmtNumber(network.count)} requests</span>
+        <span>{fmtBytes(network.totalEncoded)} transferred</span>
+        <span>{fmtBytes(network.totalDecoded)} decoded</span>
+        <span>{fmtNumber(memory.domNodes)} DOM nodes</span>
+        <span>{fmtNumber(memory.listeners)} event listeners</span>
+        <span>
+          heap {memory.heapUsedMb} MB ({memory.heapGrowthMb >= 0 ? '+' : ''}
+          {memory.heapGrowthMb} MB)
+        </span>
+        <span>
+          {fmtNumber(totals.layoutCount)} layouts ·{' '}
+          {fmtNumber(totals.styleRecalcCount)} style recalcs
+        </span>
+      </div>
+      <Table title="Slowest requests" rows={network.slow} columns={cols} />
+      <Table title="Largest resources" rows={network.large} columns={cols} />
+      <Table
+        title="Served uncompressed"
+        rows={network.uncompressed}
+        columns={cols}
+      />
+      {network.duplicates.length > 0 && (
+        <section>
+          <h2>Requested repeatedly</h2>
+          <ul>
+            {network.duplicates.map(d => (
+              <li key={d.url} title={d.url}>
+                {d.name} <b>{d.count}×</b>
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+      {report.vitals.shifts.length > 0 && (
+        <section>
+          <h2>Layout shifts</h2>
+          <ul>
+            {report.vitals.shifts.map(s => (
+              <li key={`${s.start}${s.value}`}>
+                <b>{s.value}</b> at {(s.start / 1000).toFixed(2)} s{' '}
+                {s.sources.length > 0 && (
+                  <span className="mono muted">— {s.sources.join(', ')}</span>
+                )}
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+    </div>
+  );
+}

package/src/components/PageMap.jsx

@@ -0,0 +1,329 @@
+import { useMemo, useState } from 'react';
+import { fmtMs, fmtNumber } from '../format.js';
+
+const MAX_PINS = 14;
+const MIN_SELF_MS = 0.5;
+const HUGE_AREA = 0.7;
+
+const REASON_LABELS = {
+  props: 'props changed',
+  state: 'state changed',
+  hooks: 'hook state changed',
+  context: 'context changed',
+  parent: 'parent re-rendered with nothing new',
+};
+
+function buildPins(report, hideVendor) {
+  const { pageView } = report;
+  const byId = new Map((report.react && report.react.components ? report.react.components : []).map(c => [c.id, c]));
+  const viewArea = pageView.width * pageView.height;
+  const candidates = [];
+  for (const entry of pageView.entries) {
+    const c = byId.get(entry.id);
+    if (!c || (hideVendor && c.vendor)) continue;
+    if (c.selfMs < MIN_SELF_MS && !c.wasted) continue;
+    const [x, y, w, h] = entry.rects[0];
+    candidates.push({ c, rect: { x, y, w, h }, count: entry.count });
+  }
+  // Page-sized wrappers say nothing about where the time goes; keep them only
+  // when nothing smaller was found.
+  const focused = candidates.filter(
+    p => (p.rect.w * p.rect.h) / viewArea < HUGE_AREA,
+  );
+  const pool = focused.length ? focused : candidates;
+  return pool
+    .sort((a, b) => b.c.selfMs + b.c.wastedMs - (a.c.selfMs + a.c.wastedMs))
+    .slice(0, MAX_PINS)
+    .map((p, i) => ({ ...p, key: `${p.c.id}`, n: i + 1 }));
+}
+
+function severityOf(c, maxSelf) {
+  if (c.renders && c.wasted / c.renders > 0.5 && c.wasted > 5) return 'warn';
+  return c.selfMs >= maxSelf * 0.5 ? 'hot' : 'mild';
+}
+
+function topReason(c) {
+  const [key, n] =
+    Object.entries(c.reasons).sort((a, b) => b[1] - a[1])[0] || [];
+  return n ? `${n}× ${REASON_LABELS[key]}` : null;
+}
+
+function Details({ pin }) {
+  const { c } = pin;
+  const reason = topReason(c);
+  const unstable = c.unstableProps[0];
+  return (
+    <div className="pin-card-body">
+      <div className="pin-card-title">
+        <span className="pin-num">{pin.n}</span>
+        <b>{c.name}</b>
+      </div>
+      <code className="pin-file">
+        {c.file ? `${c.file}${c.line ? `:${c.line}` : ''}` : 'file unknown'}
+      </code>
+      <dl className="pin-stats">
+        <div>
+          <dt>Self time</dt>
+          <dd>{fmtMs(c.selfMs)}</dd>
+        </div>
+        <div>
+          <dt>Renders</dt>
+          <dd>{fmtNumber(c.renders)}</dd>
+        </div>
+        <div>
+          <dt>Wasted</dt>
+          <dd className={c.wasted ? 'warn' : ''}>{fmtNumber(c.wasted)}</dd>
+        </div>
+        <div>
+          <dt>Slowest</dt>
+          <dd>{fmtMs(c.maxMs)}</dd>
+        </div>
+      </dl>
+      {reason && <p>Mostly {reason}.</p>}
+      {unstable && (
+        <p className="pin-fix">
+          Fix: <code>{unstable.prop}</code> is a new {unstable.kind} on almost
+          every render — memoize it or pass a stable reference.
+        </p>
+      )}
+      {!unstable && c.wasted > 0 && (
+        <p className="pin-fix">
+          Fix: {fmtNumber(c.wasted)} renders changed nothing — wrap in{' '}
+          <code>React.memo</code> or stop the parent re-rendering.
+        </p>
+      )}
+      {pin.count > 1 && (
+        <p className="muted">
+          {pin.count} instances on screen; the largest is outlined.
+        </p>
+      )}
+    </div>
+  );
+}
+
+const GUTTER_RATIO = 0.06;
+const MIN_GUTTER = 56;
+const MARKER_GAP_RATIO = 0.058;
+const ANCHOR_INSET = 8;
+
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+
+/**
+ * Puts each pin's number in the left or right gutter (nearer side), as close as
+ * possible to the element's height but never closer than `gap` to a neighbour,
+ * so numbers never overlap however the elements are nested.
+ */
+function placeMarkers(pins, view, gutter) {
+  const gap = view.height * MARKER_GAP_RATIO;
+  const placed = new Map();
+  ['left', 'right'].forEach(side => {
+    const group = pins
+      .filter(
+        p =>
+          (p.rect.x + p.rect.w / 2 < view.width / 2 ? 'left' : 'right') ===
+          side,
+      )
+      .map(pin => ({ pin, y: pin.rect.y + pin.rect.h / 2 }))
+      .sort((a, b) => a.y - b.y);
+    group.forEach((g, i) => {
+      g.y = Math.max(gap / 2, i ? Math.max(g.y, group[i - 1].y + gap) : g.y);
+    });
+    for (let i = group.length - 1; i >= 0; i -= 1) {
+      const limit =
+        i === group.length - 1 ? view.height - gap / 2 : group[i + 1].y - gap;
+      group[i].y = Math.min(group[i].y, limit);
+    }
+    group.forEach(({ pin, y }) => {
+      const { x, y: top, w, h } = pin.rect;
+      const inset = Math.min(ANCHOR_INSET, w / 4);
+      placed.set(pin.key, {
+        side,
+        markerX: side === 'left' ? gutter / 2 : view.width + gutter * 1.5,
+        markerY: y,
+        anchorX: gutter + (side === 'left' ? x + inset : x + w - inset),
+        anchorY: clamp(y, top + 4, top + h - 4),
+      });
+    });
+  });
+  return placed;
+}
+
+function Callouts({ pins, pageView, active, onActivate, onOpenFile, maxSelf }) {
+  const gutter = Math.max(MIN_GUTTER, pageView.width * GUTTER_RATIO);
+  const totalWidth = pageView.width + gutter * 2;
+  const placed = useMemo(
+    () => placeMarkers(pins, pageView, gutter),
+    [pins, pageView, gutter],
+  );
+  const pctX = v => `${(v / totalWidth) * 100}%`;
+  const pctY = v => `${(v / pageView.height) * 100}%`;
+  const activePlace = active ? placed.get(active.key) : null;
+  return (
+    <div
+      className="page-frame"
+      style={{ aspectRatio: `${totalWidth} / ${pageView.height}` }}
+    >
+      <img
+        src={`/api/reports/${encodeURIComponent(pageView.reportId)}/page.jpg`}
+        alt="The profiled page when recording stopped"
+        style={{ left: pctX(gutter), width: pctX(pageView.width) }}
+        onError={pageView.onImageError}
+      />
+      <svg
+        className="callout-svg"
+        viewBox={`0 0 ${totalWidth} ${pageView.height}`}
+        preserveAspectRatio="none"
+        aria-hidden="true"
+      >
+        {pins.map(pin => {
+          const at = placed.get(pin.key);
+          const { x, y, w, h } = pin.rect;
+          const cls = `sev-${severityOf(pin.c, maxSelf)} ${
+            active?.key === pin.key ? 'active' : ''
+          }`;
+          return (
+            <g key={pin.key} className={`callout ${cls}`}>
+              <rect x={gutter + x} y={y} width={w} height={h} rx="4" />
+              <line
+                x1={at.markerX}
+                y1={at.markerY}
+                x2={at.anchorX}
+                y2={at.anchorY}
+              />
+              <circle cx={at.anchorX} cy={at.anchorY} r="4" />
+            </g>
+          );
+        })}
+      </svg>
+      {pins.map(pin => {
+        const at = placed.get(pin.key);
+        return (
+          <button
+            key={pin.key}
+            type="button"
+            className={`marker sev-${severityOf(pin.c, maxSelf)} ${
+              active?.key === pin.key ? 'active' : ''
+            }`}
+            style={{ left: pctX(at.markerX), top: pctY(at.markerY) }}
+            aria-label={`${pin.n}. ${pin.c.name}, ${fmtMs(pin.c.selfMs)} self time`}
+            onMouseEnter={() => onActivate(pin)}
+            onMouseLeave={() => onActivate(null)}
+            onFocus={() => onActivate(pin)}
+            onBlur={() => onActivate(null)}
+            onClick={() => pin.c.file && onOpenFile(pin.c.file)}
+          >
+            {pin.n}
+          </button>
+        );
+      })}
+      {active && activePlace && (
+        <div
+          className="pin-card"
+          style={{
+            [activePlace.side]: pctX(gutter),
+            ...(activePlace.markerY / pageView.height > 0.55
+              ? {
+                  bottom: `${100 - (activePlace.markerY / pageView.height) * 100}%`,
+                }
+              : { top: pctY(activePlace.markerY) }),
+          }}
+        >
+          <Details pin={active} />
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Screenshot of the page at the moment recording stopped, with the slowest
+ * React components outlined where they sit on screen. Hover or focus a pin for
+ * the file, render counts and a fix; click it to open the source.
+ */
+export default function PageMap({ report, hideVendor, onOpenFile }) {
+  const { pageView } = report;
+  const [activeKey, setActiveKey] = useState(null);
+  const [isImageMissing, setIsImageMissing] = useState(false);
+  const pins = useMemo(
+    () => (pageView ? buildPins(report, hideVendor) : []),
+    [report, pageView, hideVendor],
+  );
+  const maxSelf = Math.max(1, ...pins.map(p => p.c.selfMs));
+  const active = pins.find(p => p.key === activeKey) || null;
+  const frameView = useMemo(
+    () =>
+      pageView && {
+        ...pageView,
+        reportId: report.id,
+        onImageError: () => setIsImageMissing(true),
+      },
+    [pageView, report.id],
+  );
+
+  if (!pageView?.hasImage || isImageMissing)
+    return (
+      <div className="empty">
+        <b>No page map for this report</b>
+        <span>
+          It needs a development build of a React app and a recording made with
+          this version of the profiler. Older reports and production builds have
+          none.
+        </span>
+      </div>
+    );
+  if (!pins.length)
+    return (
+      <div className="empty">
+        <b>No slow components are visible on screen</b>
+        <span>
+          Nothing that rendered during the recording is currently on screen (or
+          everything is hidden by “Hide node_modules”).
+        </span>
+      </div>
+    );
+
+  return (
+    <div className="page-map">
+      <div className="page-stage">
+        <p className="muted page-caption">
+          Screenshot taken when the recording stopped. Numbers in the margins
+          point to the components that spent the most time rendering and are on
+          screen now; hover a number for details.
+        </p>
+        <Callouts
+          pins={pins}
+          pageView={frameView}
+          active={active}
+          maxSelf={maxSelf}
+          onActivate={pin => setActiveKey(pin ? pin.key : null)}
+          onOpenFile={onOpenFile}
+        />
+      </div>
+      <aside className="page-list" aria-label="Components on this page">
+        <h2>Hot spots on this page</h2>
+        <ol>
+          {pins.map(pin => (
+            <li key={pin.key}>
+              <button
+                type="button"
+                className={`hotspot ${active?.key === pin.key ? 'active' : ''}`}
+                onMouseEnter={() => setActiveKey(pin.key)}
+                onFocus={() => setActiveKey(pin.key)}
+                onClick={() => pin.c.file && onOpenFile(pin.c.file)}
+              >
+                <span className="pin-num">{pin.n}</span>
+                <span className="hotspot-main">
+                  <b>{pin.c.name}</b>
+                  <span className="muted mono">
+                    {pin.c.file || 'file unknown'}
+                  </span>
+                </span>
+                <span className="hotspot-time">{fmtMs(pin.c.selfMs)}</span>
+              </button>
+            </li>
+          ))}
+        </ol>
+      </aside>
+    </div>
+  );
+}

package/src/components/Popover.jsx

@@ -0,0 +1,51 @@
+import { useEffect, useId, useRef, useState } from 'react';
+import { ChevronIcon } from './Icons.jsx';
+
+/** A button that opens a small floating panel; closes on outside click or Escape. */
+export default function Popover({ label, icon, align = 'right', children }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const rootRef = useRef(null);
+  const panelId = useId();
+
+  useEffect(() => {
+    if (!isOpen) return undefined;
+    const onPointerDown = e => {
+      if (!rootRef.current?.contains(e.target)) setIsOpen(false);
+    };
+    const onKeyDown = e => {
+      if (e.key === 'Escape') setIsOpen(false);
+    };
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKeyDown);
+    };
+  }, [isOpen]);
+
+  return (
+    <span className="popover" ref={rootRef}>
+      <button
+        type="button"
+        className="ghost"
+        aria-expanded={isOpen}
+        aria-controls={isOpen ? panelId : undefined}
+        onClick={() => setIsOpen(open => !open)}
+      >
+        {icon}
+        <span>{label}</span>
+        <ChevronIcon />
+      </button>
+      {isOpen && (
+        <div
+          id={panelId}
+          className={`popover-panel align-${align}`}
+          role="dialog"
+          aria-label={label}
+        >
+          {children}
+        </div>
+      )}
+    </span>
+  );
+}