@progen-labs/spectra 0.0.0-stage → 0.1.0

package/src/components/ReactPanel.jsx

@@ -0,0 +1,200 @@
+import { useMemo, useState } from 'react';
+import { fmtMs, fmtNumber, splitPath } from '../format.js';
+
+const COLUMNS = [
+  { id: 'name', label: 'Component', get: c => c.name, text: true },
+  { id: 'renders', label: 'Renders', get: c => c.renders },
+  { id: 'wasted', label: 'Wasted', get: c => c.wasted },
+  {
+    id: 'wastedPct',
+    label: 'Wasted %',
+    get: c => (c.renders ? (c.wasted / c.renders) * 100 : 0),
+  },
+  { id: 'selfMs', label: 'Self time', get: c => c.selfMs },
+  {
+    id: 'avgMs',
+    label: 'Avg / render',
+    get: c => (c.renders ? c.selfMs / c.renders : 0),
+  },
+  { id: 'maxMs', label: 'Slowest', get: c => c.maxMs },
+];
+
+const REASON_LABELS = {
+  props: 'props changed',
+  state: 'state',
+  hooks: 'hook state',
+  context: 'context',
+  parent: 'parent re-render (nothing changed)',
+};
+
+function Detail({ c }) {
+  const reasons = Object.entries(c.reasons).filter(([, n]) => n);
+  return (
+    <tr className="detail">
+      <td colSpan={COLUMNS.length + 1}>
+        <div className="detail-grid">
+          <div>
+            <h4>Why it rendered</h4>
+            <ul>
+              {c.mounts > 0 && <li>{c.mounts}× mounted</li>}
+              {reasons.map(([k, n]) => (
+                <li key={k}>
+                  {n}× {REASON_LABELS[k]}
+                </li>
+              ))}
+              {c.topParent && (
+                <li className="muted">
+                  usually triggered by parent <b>{c.topParent}</b>
+                </li>
+              )}
+            </ul>
+          </div>
+          <div>
+            <h4>Props that changed</h4>
+            {c.changedProps.length === 0 ? (
+              <p className="muted">none</p>
+            ) : (
+              <ul>
+                {c.changedProps.map(p => {
+                  const unstable = c.unstableProps.find(u => u.prop === p.prop);
+                  return (
+                    <li key={p.prop}>
+                      <code>{p.prop}</code> {p.count}×
+                      {unstable && (
+                        <span className="warn">
+                          {' '}
+                          — new{' '}
+                          {unstable.kind === 'function'
+                            ? 'function with identical code'
+                            : 'object with identical contents'}{' '}
+                          each time{' '}
+                          {unstable.kind === 'function'
+                            ? '(useCallback)'
+                            : '(useMemo)'}
+                        </span>
+                      )}
+                    </li>
+                  );
+                })}
+              </ul>
+            )}
+          </div>
+        </div>
+      </td>
+    </tr>
+  );
+}
+
+export default function ReactPanel({ report, hideVendor, onOpenFile }) {
+  const [sort, setSort] = useState({ id: 'selfMs', dir: -1 });
+  const [open, setOpen] = useState(null);
+  const react = report.react || { detected: false, components: [] };
+  const rows = useMemo(() => {
+    const col = COLUMNS.find(c => c.id === sort.id);
+    return react.components
+      .filter(c => !(hideVendor && c.vendor))
+      .sort(
+        (a, b) =>
+          (col.text
+            ? col.get(a).localeCompare(col.get(b))
+            : col.get(a) - col.get(b)) * sort.dir,
+      );
+  }, [react.components, sort, hideVendor]);
+
+  if (!react.detected) {
+    return (
+      <div className="empty">
+        <h3>No React renderer was detected</h3>
+        <p>
+          The probe has to be installed before React loads. Use{' '}
+          <b>Record page load</b>, or reload the tab from this tool and record
+          again.
+        </p>
+      </div>
+    );
+  }
+  return (
+    <div className="react-panel">
+      <div className="summary-row">
+        <span>React {react.version}</span>
+        <span>{fmtNumber(react.commits.count)} commits</span>
+        <span>total render time {fmtMs(react.commits.totalMs)}</span>
+        <span>slowest commit {fmtMs(react.commits.maxMs)}</span>
+        {!react.hasTimings && (
+          <span className="warn">production build: no timings</span>
+        )}
+      </div>
+      <table className="data">
+        <thead>
+          <tr>
+            {COLUMNS.map(c => (
+              <th key={c.id}>
+                <button
+                  type="button"
+                  onClick={() =>
+                    setSort({
+                      id: c.id,
+                      dir: sort.id === c.id ? -sort.dir : -1,
+                    })
+                  }
+                >
+                  {c.label} {sort.id === c.id ? (sort.dir < 0 ? '↓' : '↑') : ''}
+                </button>
+              </th>
+            ))}
+            <th>File</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.slice(0, 300).map(c => {
+            const key = `${c.name}|${c.file}|${c.line}`;
+            return [
+              <tr key={key} className={open === key ? 'open' : ''}>
+                <td>
+                  <button
+                    type="button"
+                    className="link"
+                    onClick={() => setOpen(open === key ? null : key)}
+                  >
+                    {open === key ? '▾' : '▸'} {c.name}
+                  </button>
+                </td>
+                <td className="num">{fmtNumber(c.renders)}</td>
+                <td className={`num ${c.wasted ? 'warn' : ''}`}>
+                  {fmtNumber(c.wasted)}
+                </td>
+                <td className="num">
+                  {c.renders ? Math.round((c.wasted / c.renders) * 100) : 0}%
+                </td>
+                <td className="num">{fmtMs(c.selfMs)}</td>
+                <td className="num">
+                  {fmtMs(c.renders ? c.selfMs / c.renders : 0)}
+                </td>
+                <td className="num">{fmtMs(c.maxMs)}</td>
+                <td>
+                  {c.file ? (
+                    <button
+                      type="button"
+                      className="link mono"
+                      onClick={() => onOpenFile(c.file)}
+                      title={c.file}
+                    >
+                      <span className="muted">
+                        {splitPath(c.file).dir.slice(-28)}
+                      </span>
+                      {splitPath(c.file).name}
+                      {c.line ? `:${c.line}` : ''}
+                    </button>
+                  ) : (
+                    <span className="muted">unknown</span>
+                  )}
+                </td>
+              </tr>,
+              open === key && <Detail key={`${key}-detail`} c={c} />,
+            ];
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/src/components/SidePicker.jsx

@@ -0,0 +1,207 @@
+import { useRef, useState } from 'react';
+import { fmtMs } from '../format.js';
+
+function CommitFacts({ git, runsCommit }) {
+  if (!git)
+    return (
+      <p className="muted">
+        No commit information yet: enter a hash and press Look up, or upload
+        snapshots that carry one.
+      </p>
+    );
+  const date = git.date
+    ? new Date(git.date).toLocaleString(undefined, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+      })
+    : '';
+  return (
+    <dl className="git-facts">
+      <dt>Commit</dt>
+      <dd className="mono">{git.shortHash || git.hash?.slice(0, 10)}</dd>
+      <dt>Author</dt>
+      <dd>{git.author || <span className="muted">unknown</span>}</dd>
+      {date && (
+        <>
+          <dt>Date</dt>
+          <dd>{date}</dd>
+        </>
+      )}
+      {git.subject && (
+        <>
+          <dt>Message</dt>
+          <dd>{git.subject}</dd>
+        </>
+      )}
+      {git.branch && (
+        <>
+          <dt>Branch</dt>
+          <dd>{git.branch}</dd>
+        </>
+      )}
+      {runsCommit && runsCommit !== git.shortHash && (
+        <>
+          <dt>Runs say</dt>
+          <dd className="mono">{runsCommit}</dd>
+        </>
+      )}
+    </dl>
+  );
+}
+
+/** One side of the comparison: commit details plus the recordings (snapshots) taken on that commit. */
+export default function SidePicker({
+  title,
+  hint,
+  side,
+  saved,
+  onFiles,
+  onSaved,
+  onRemove,
+  onLabel,
+  onLookup,
+}) {
+  const input = useRef(null);
+  const [isDragging, setIsDragging] = useState(false);
+  const [hash, setHash] = useState(null);
+  const git = side.git || side.runs[0]?.report.meta.git || null;
+  const hashValue = hash ?? (side.hashInput || git?.shortHash || '');
+  const addable = saved.filter(r => !side.runs.some(x => x.report.id === r.id));
+
+  const drop = e => {
+    e.preventDefault();
+    setIsDragging(false);
+    if (e.dataTransfer.files.length) onFiles(e.dataTransfer.files);
+  };
+
+  return (
+    <section className="side-picker" aria-label={title}>
+      <h3>
+        {title} <span className="muted">{hint}</span>
+      </h3>
+
+      <label className="field">
+        <span>Commit hash</span>
+        <span className="field-row">
+          <input
+            value={hashValue}
+            onChange={e => setHash(e.target.value)}
+            onKeyDown={e => e.key === 'Enter' && onLookup(hashValue)}
+            placeholder="e.g. 3fa516c"
+            spellCheck={false}
+          />
+          <button
+            type="button"
+            onClick={() => {
+              onLookup(hashValue);
+              setHash(null);
+            }}
+            disabled={side.lookup.status === 'working'}
+          >
+            {side.lookup.status === 'working' ? 'Looking up…' : 'Look up'}
+          </button>
+        </span>
+      </label>
+      <CommitFacts
+        git={git}
+        runsCommit={side.runs[0]?.report.meta.git?.shortHash}
+      />
+      {git?.dirty && (
+        <p className="warn">
+          This snapshot was recorded with uncommitted changes.
+        </p>
+      )}
+      {side.lookup.status === 'error' && (
+        <p className="warn">{side.lookup.message}</p>
+      )}
+
+      <label className="field">
+        <span>
+          Scenario <span className="muted">(optional)</span>
+        </span>
+        <input
+          value={side.label}
+          onChange={e => onLabel(e.target.value)}
+          placeholder={
+            side.runs[0]?.report.meta.title || 'e.g. dashboard 579, page load'
+          }
+        />
+      </label>
+
+      <div
+        className={`dropzone ${isDragging ? 'dragging' : ''}`}
+        onDragOver={e => {
+          e.preventDefault();
+          setIsDragging(true);
+        }}
+        onDragLeave={() => setIsDragging(false)}
+        onDrop={drop}
+      >
+        <input
+          ref={input}
+          type="file"
+          accept=".json,application/json"
+          multiple
+          hidden
+          onChange={e => {
+            onFiles(e.target.files);
+            e.target.value = '';
+          }}
+        />
+        <button
+          type="button"
+          className="primary"
+          onClick={() => input.current.click()}
+        >
+          Upload snapshot(s)
+        </button>
+        <span className="muted">
+          or drop <code>perf_*.json</code> files here. Several runs of the same
+          commit are welcome: medians are used.
+        </span>
+      </div>
+      {addable.length > 0 && (
+        <select
+          aria-label={`Add a saved report to ${title}`}
+          value=""
+          onChange={e => e.target.value && onSaved(e.target.value)}
+        >
+          <option value="">…or add a report recorded on this machine</option>
+          {addable.map(r => (
+            <option key={r.id} value={r.id}>
+              {new Date(r.createdAt).toLocaleString()} · {r.mode} ·{' '}
+              {fmtMs(r.durationMs)}
+            </option>
+          ))}
+        </select>
+      )}
+
+      {side.problems.map(p => (
+        <p key={p} className="warn" role="alert">
+          {p}
+        </p>
+      ))}
+      <ul className="run-chips">
+        {side.runs.map(({ report, fileName }) => (
+          <li key={report.id}>
+            <span className="mono" title={fileName}>
+              {fileName.replace(/^reports\//, '')}
+            </span>
+            <span className="muted">
+              {report.meta.mode === 'load' ? 'load' : 'interaction'} ·{' '}
+              {fmtMs(report.meta.durationMs)}
+            </span>
+            <button
+              type="button"
+              aria-label={`Remove ${fileName}`}
+              onClick={() => onRemove(report.id)}
+            >
+              ×
+            </button>
+          </li>
+        ))}
+        {!side.runs.length && <li className="muted">No recordings yet.</li>}
+      </ul>
+    </section>
+  );
+}

package/src/components/SnapshotButton.jsx

@@ -0,0 +1,140 @@
+import { useState } from 'react';
+import { snapshotFileName, withCommit } from '../../shared/snapshot.js';
+import { api } from '../api.js';
+import { downloadJson } from '../download.js';
+import { DownloadIcon } from './Icons.jsx';
+
+/**
+ * Exports the open report as a snapshot named after its commit, for the Compare tab:
+ * `perf_<commit>_<mode>_<time>[_<label>].json`. The commit is whatever git had
+ * checked out when the recording was made, and can be corrected here.
+ */
+export default function SnapshotButton({ report }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [hash, setHash] = useState(report.meta.git?.hash || '');
+  const [git, setGit] = useState(report.meta.git || null);
+  const [label, setLabel] = useState(report.meta.label || '');
+  const [state, setState] = useState({ status: 'idle', message: '' });
+
+  const lookup = async () => {
+    setState({ status: 'working', message: '' });
+    try {
+      const info = await api.gitCommit(hash.trim() || 'HEAD');
+      setGit(info);
+      setHash(info.hash);
+      setState({ status: 'ok', message: '' });
+      return info;
+    } catch (err) {
+      setState({ status: 'error', message: err.message });
+      return null;
+    }
+  };
+
+  const download = async () => {
+    let commit = git;
+    // A hash typed but never looked up: resolve it so the author is included.
+    if (hash.trim() && hash.trim() !== git?.hash) commit = await lookup();
+    if (!commit && hash.trim())
+      commit = {
+        hash: hash.trim(),
+        shortHash: hash.trim().slice(0, 10),
+        author: '',
+      };
+    downloadJson(
+      withCommit(report, commit, label),
+      snapshotFileName(report, commit, label),
+    );
+  };
+
+  return (
+    <span className="trace-button">
+      <button
+        type="button"
+        onClick={() => setIsOpen(open => !open)}
+        aria-expanded={isOpen}
+      >
+        <DownloadIcon /> Snapshot for comparison
+      </button>
+      {isOpen && (
+        <div
+          className="trace-note snapshot"
+          role="dialog"
+          aria-label="Snapshot for comparison"
+        >
+          <button
+            type="button"
+            className="close"
+            aria-label="Close"
+            onClick={() => setIsOpen(false)}
+          >
+            ×
+          </button>
+          <p>
+            Saves this report as <code>perf_&lt;commit&gt;_…json</code>. Upload
+            two of these in the <b>Compare</b> tab to see what a commit changed.
+          </p>
+          <label className="field">
+            <span>Commit</span>
+            <span className="field-row">
+              <input
+                value={hash}
+                onChange={e => setHash(e.target.value)}
+                placeholder="commit hash (blank = current HEAD)"
+                spellCheck={false}
+              />
+              <button
+                type="button"
+                onClick={lookup}
+                disabled={state.status === 'working'}
+              >
+                Look up
+              </button>
+            </span>
+          </label>
+          {git && (
+            <dl className="git-facts">
+              <dt>Commit</dt>
+              <dd className="mono">{git.shortHash}</dd>
+              <dt>Author</dt>
+              <dd>{git.author || 'unknown'}</dd>
+              <dt>Message</dt>
+              <dd>{git.subject || '–'}</dd>
+              {git.branch && (
+                <>
+                  <dt>Branch</dt>
+                  <dd>{git.branch}</dd>
+                </>
+              )}
+            </dl>
+          )}
+          {git?.dirty && (
+            <p className="warn">
+              The working tree had uncommitted changes when this was recorded,
+              so the commit may not describe exactly what was measured.
+            </p>
+          )}
+          {!git && (
+            <p className="muted">
+              No commit was recorded with this report (it predates commit
+              tracking). Enter the hash it was taken at.
+            </p>
+          )}
+          {state.status === 'error' && <p className="warn">{state.message}</p>}
+          <label className="field">
+            <span>
+              Scenario label <span className="muted">(optional)</span>
+            </span>
+            <input
+              value={label}
+              onChange={e => setLabel(e.target.value)}
+              placeholder="e.g. dashboard 579, page load"
+            />
+          </label>
+          <button type="button" className="primary" onClick={download}>
+            Download snapshot
+          </button>
+        </div>
+      )}
+    </span>
+  );
+}

package/src/components/TimeBreakdown.jsx

@@ -0,0 +1,45 @@
+import { fmtMs } from '../format.js';
+
+const PARTS = [
+  { key: 'scriptingMs', label: 'Scripting', color: 'var(--cat-1)' },
+  { key: 'layoutMs', label: 'Layout', color: 'var(--cat-2)' },
+  { key: 'styleMs', label: 'Style', color: 'var(--cat-3)' },
+  { key: 'paintMs', label: 'Paint', color: 'var(--cat-4)' },
+  { key: 'gcMs', label: 'Garbage collection', color: 'var(--cat-5)' },
+  { key: 'compileMs', label: 'Compile/parse', color: 'var(--cat-6)' },
+  { key: 'otherMs', label: 'Other', color: 'var(--cat-other)' },
+];
+
+/** Where main-thread time went, as one stacked bar with a labelled legend. */
+export default function TimeBreakdown({ totals }) {
+  const parts = PARTS.map(p => ({ ...p, value: totals[p.key] || 0 })).filter(
+    p => p.value > 0,
+  );
+  const sum = parts.reduce((s, p) => s + p.value, 0) || 1;
+  return (
+    <div className="breakdown">
+      <div
+        className="breakdown-bar"
+        role="img"
+        aria-label="Main-thread time breakdown"
+      >
+        {parts.map(p => (
+          <span
+            key={p.key}
+            style={{ width: `${(p.value / sum) * 100}%`, background: p.color }}
+            title={`${p.label}: ${fmtMs(p.value)}`}
+          />
+        ))}
+      </div>
+      <ul className="breakdown-legend">
+        {parts.map(p => (
+          <li key={p.key}>
+            <i style={{ background: p.color }} />
+            {p.label} <b>{fmtMs(p.value)}</b>{' '}
+            <span className="muted">{Math.round((p.value / sum) * 100)}%</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

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