@progen-labs/spectra 0.0.0-stage → 0.1.0

package/shared/snapshot.js

@@ -0,0 +1,77 @@
+/**
+ * "Snapshots" are profiler reports exported for comparison. This module knows how
+ * to name them (the commit hash goes in the file name so they are recognisable
+ * once downloaded), check that an uploaded file really is one, and recover the
+ * commit from a file name when the report itself carries no git information.
+ */
+
+/** @returns {{ok: true} | {ok: false, reason: string}} */
+export function validateReport(obj) {
+  if (obj && (Array.isArray(obj) || Array.isArray(obj.traceEvents))) {
+    return {
+      ok: false,
+      reason:
+        'This is a raw Chrome trace (.trace.json). Comparison needs the profiler report: use “Snapshot for comparison” on the report instead — the trace lacks the React and source-file data.',
+    };
+  }
+  const ok =
+    obj &&
+    typeof obj === 'object' &&
+    obj.meta &&
+    obj.vitals &&
+    obj.totals &&
+    obj.memory &&
+    obj.network &&
+    Array.isArray(obj.files) &&
+    Array.isArray(obj.findings);
+  return ok
+    ? { ok: true }
+    : { ok: false, reason: 'This file is not a performance-profiler report.' };
+}
+
+/**
+ * Commit hash from a file name such as `perf_3fa516c_load_20260930-1548.json`.
+ * The segment right after the `perf_` prefix wins; otherwise the first hex-looking
+ * token that contains a letter (so plain dates like 20260930 are never mistaken for a hash).
+ */
+export function hashFromFileName(name) {
+  const base = String(name || '').replace(/\.json$/i, '');
+  const prefixed = /^perf[_-]([0-9a-f]{7,40})(?:[_-]|$)/i.exec(base);
+  if (prefixed) return prefixed[1].toLowerCase();
+  const token = base
+    .split(/[^0-9a-zA-Z]+/)
+    .find(t => /^[0-9a-f]{7,40}$/i.test(t) && /[a-f]/i.test(t));
+  return token ? token.toLowerCase() : '';
+}
+
+const slug = text =>
+  String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+
+export function snapshotFileName(report, git, label) {
+  const hash = (git?.shortHash || git?.hash || '').slice(0, 10) || 'nocommit';
+  const stamp = String(report.createdAt || '')
+    .replace(/[-:]/g, '')
+    .replace(/\..+$/, '')
+    .replace('T', '-')
+    .slice(0, 15); // yyyymmdd-hhmmss: two runs a few seconds apart must not share a name
+  const parts = ['perf', hash, report.meta.mode, stamp, slug(label)].filter(
+    Boolean,
+  );
+  return `${parts.join('_')}.json`;
+}
+
+/** The report with the commit and an optional label recorded in `meta`. */
+export function withCommit(report, git, label) {
+  return {
+    ...report,
+    meta: {
+      ...report.meta,
+      git: git || report.meta.git || null,
+      label: label || report.meta.label || '',
+    },
+  };
+}

package/src/App.jsx

@@ -0,0 +1,361 @@
+import { useCallback, useEffect, useState } from 'react';
+import { api } from './api.js';
+import AppearanceMenu from './components/AppearanceMenu.jsx';
+import { CallHeatTree, FileHeatTree } from './components/HeatTrees.jsx';
+import ComparePanel from './components/ComparePanel.jsx';
+import ControlBar from './components/ControlBar.jsx';
+import Culprits from './components/Culprits.jsx';
+import EvaluationPanel from './components/EvaluationPanel.jsx';
+import FilePanel from './components/FilePanel.jsx';
+import LongTasks from './components/LongTasks.jsx';
+import NetworkPanel from './components/NetworkPanel.jsx';
+import PageMap from './components/PageMap.jsx';
+import ReactPanel from './components/ReactPanel.jsx';
+import SnapshotButton from './components/SnapshotButton.jsx';
+import TraceButton from './components/TraceButton.jsx';
+import { fmtMs } from './format.js';
+import { useCompare } from './hooks/useCompare.js';
+import { useSession } from './hooks/useSession.js';
+import { useAppearance } from './theme.js';
+
+const TABS = [
+  { id: 'culprits', label: 'Culprits' },
+  { id: 'page', label: 'Page map' },
+  { id: 'files', label: 'File tree' },
+  { id: 'calls', label: 'Call tree' },
+  { id: 'react', label: 'React' },
+  { id: 'tasks', label: 'Long tasks' },
+  { id: 'network', label: 'Network & memory' },
+  { id: 'evaluation', label: 'Golden paths' },
+  { id: 'compare', label: 'Compare commits' },
+];
+
+/** Tabs that don't require a loaded report to be usable. */
+const REPORTLESS_TABS = new Set(['compare', 'evaluation']);
+
+function ReportPicker({ reports, current, onPick, onDelete }) {
+  if (!reports.length)
+    return <span className="muted">No saved reports yet</span>;
+  return (
+    <span className="report-picker">
+      <select
+        aria-label="Saved report"
+        value={current || ''}
+        onChange={e => onPick(e.target.value)}
+      >
+        {!current && <option value="">Open a saved report…</option>}
+        {reports.map(r => (
+          <option key={r.id} value={r.id}>
+            {new Date(r.createdAt).toLocaleString()} · {r.mode} ·{' '}
+            {fmtMs(r.durationMs)} · {r.critical} critical
+          </option>
+        ))}
+      </select>
+      {current && (
+        <button
+          type="button"
+          className="ghost destructive"
+          onClick={() => onDelete(current)}
+          aria-label="Delete this report"
+        >
+          Delete
+        </button>
+      )}
+    </span>
+  );
+}
+
+const STEPS = [
+  {
+    title: 'Start the frontend',
+    body: (
+      <>
+        Run <code>npm run dev-server</code> (usually on port 9000). A{' '}
+        <b>development</b> build gives per-file and per-component results.
+      </>
+    ),
+  },
+  {
+    title: 'Launch Chrome',
+    body: (
+      <>
+        Click <b>Launch Chrome</b>, sign in to the app in the window that opens,
+        and navigate to the page you care about.
+      </>
+    ),
+  },
+  {
+    title: 'Record',
+    body: (
+      <>
+        Press <b>Record interaction</b>, use the page, then <b>Stop</b> — or use{' '}
+        <b>Record page load</b> for startup performance.
+      </>
+    ),
+  },
+];
+
+function Welcome({ onCompare }) {
+  return (
+    <div className="welcome">
+      <div>
+        <h2>Find what makes the frontend slow</h2>
+        <p className="welcome-lead">
+          Ranked culprits, heat trees, React re-renders, long tasks and network
+          findings from a single recording.
+        </p>
+      </div>
+      <ol className="steps">
+        {STEPS.map((step, i) => (
+          <li key={step.title}>
+            <span className="step-num">{i + 1}</span>
+            <h3>{step.title}</h3>
+            <p>{step.body}</p>
+          </li>
+        ))}
+      </ol>
+      <p className="welcome-foot">
+        Reviewing a PR? Use{' '}
+        <button type="button" className="link" onClick={onCompare}>
+          Compare commits
+        </button>{' '}
+        to see what a commit changed.
+      </p>
+    </div>
+  );
+}
+
+export default function App() {
+  const [report, setReport] = useState(null);
+  const [tab, setTab] = useState('culprits');
+  const [selectedFile, setSelectedFile] = useState(null);
+  const [hideVendor, setHideVendor] = useState(false);
+  const [revealTick, setRevealTick] = useState(0);
+  const compare = useCompare();
+  const [appearance, setAppearance] = useAppearance();
+  const [evaluations, setEvaluations] = useState([]);
+
+  useEffect(() => {
+    api
+      .evaluations()
+      .then(setEvaluations)
+      .catch(() => setEvaluations([]));
+  }, []);
+
+  const openReport = useCallback(async id => {
+    const data = await api.report(id);
+    setReport(data);
+    setSelectedFile(null);
+    setTab('culprits');
+  }, []);
+  const { status, reports, error, clearError, run, refreshReports } =
+    useSession({ onReport: openReport });
+
+  // Open the newest saved report on first load so the page is never empty.
+  useEffect(() => {
+    if (!report && reports.length) openReport(reports[0].id);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reports.length]);
+
+  const openFile = useCallback(path => {
+    setSelectedFile(path);
+    setRevealTick(t => t + 1);
+    setTab(t =>
+      t === 'culprits' || t === 'network' || t === 'tasks' ? 'files' : t,
+    );
+  }, []);
+
+  const deleteReport = async id => {
+    await api.deleteReport(id);
+    setReport(null);
+    refreshReports();
+  };
+
+  const showPanel =
+    selectedFile &&
+    report &&
+    ['files', 'calls', 'react', 'culprits', 'tasks', 'page'].includes(tab);
+  const inCompare = tab === 'compare';
+  const inEvaluation = tab === 'evaluation';
+  return (
+    <div className="app">
+      <header className="topbar">
+        <div className="brand">
+          <span className="brand-mark" aria-hidden="true">
+            <svg viewBox="0 0 16 16" width="16" height="16">
+              <path
+                d="M1.5 8.5h3l2-5 3 9 2-4h3"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.7"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+            </svg>
+          </span>
+          <div>
+            <h1>Performance Profiler</h1>
+            <small>{status?.defaultName || 'target-frontend'}</small>
+          </div>
+        </div>
+        <span className="spacer" />
+        <ReportPicker
+          reports={reports}
+          current={report?.id}
+          onPick={openReport}
+          onDelete={deleteReport}
+        />
+        <AppearanceMenu appearance={appearance} onChange={setAppearance} />
+      </header>
+      <ControlBar status={status} run={run} isCompact={Boolean(report)} />
+      {error && (
+        <div className="error" role="alert">
+          <span>{error}</span>
+          <button type="button" onClick={clearError}>
+            Dismiss
+          </button>
+        </div>
+      )}
+      <div className="workspace">
+        {report && !inCompare && !inEvaluation && (
+          <div className="report-bar">
+            <span className="report-title" title={report.meta.url}>
+              {report.meta.title || report.meta.url}
+            </span>
+            <span className="report-meta">
+              <span className="pill">
+                {report.meta.mode === 'load' ? 'Page load' : 'Interaction'}
+              </span>
+              <span className="pill">{fmtMs(report.meta.durationMs)}</span>
+              {report.meta.cpuThrottle > 1 && (
+                <span className="pill warn">
+                  {report.meta.cpuThrottle}× CPU slowdown
+                </span>
+              )}
+              <span className="pill">
+                Attribution: {report.meta.attribution}
+              </span>
+              {report.meta.git && (
+                <span className="pill">
+                  Commit <code>{report.meta.git.shortHash}</code>
+                  {report.meta.git.dirty ? ' · uncommitted changes' : ''}
+                </span>
+              )}
+            </span>
+            <span className="spacer" />
+            <span className="btn-group">
+              <SnapshotButton key={`snap-${report.id}`} report={report} />
+              <TraceButton key={report.id} reportId={report.id} />
+            </span>
+          </div>
+        )}
+        <div className="tabs main-tabs">
+          <div role="tablist" className="tab-list" aria-label="Report views">
+            {TABS.map(t => (
+              <button
+                key={t.id}
+                type="button"
+                role="tab"
+                aria-selected={
+                  tab === t.id && (Boolean(report) || REPORTLESS_TABS.has(t.id))
+                }
+                disabled={!report && !REPORTLESS_TABS.has(t.id)}
+                onClick={() => setTab(t.id)}
+              >
+                {t.label}
+                {t.id === 'culprits' && report && (
+                  <span className="count">{report.findings.length}</span>
+                )}
+              </button>
+            ))}
+          </div>
+          <span className="spacer" />
+          <label className="switch">
+            <input
+              type="checkbox"
+              role="switch"
+              checked={hideVendor}
+              onChange={e => setHideVendor(e.target.checked)}
+            />
+            Hide node_modules
+          </label>
+        </div>
+        {inCompare && (
+          <main className="main">
+            <div className="content">
+              <ComparePanel
+                compare={compare}
+                savedReports={reports}
+                hideVendor={hideVendor}
+              />
+            </div>
+          </main>
+        )}
+        {inEvaluation && (
+          <main className="main">
+            <div className="content">
+              <EvaluationPanel
+                evaluations={evaluations}
+                onOpenReport={openReport}
+              />
+            </div>
+          </main>
+        )}
+        {!inCompare && !inEvaluation && report && (
+          <main className="main">
+            <div className="content">
+              {tab === 'culprits' && (
+                <Culprits
+                  key={report.id}
+                  report={report}
+                  hideVendor={hideVendor}
+                  onOpenFile={openFile}
+                />
+              )}
+              {tab === 'page' && (
+                <PageMap
+                  report={report}
+                  hideVendor={hideVendor}
+                  onOpenFile={openFile}
+                />
+              )}
+              {tab === 'files' && (
+                <FileHeatTree
+                  report={report}
+                  hideVendor={hideVendor}
+                  selectedPath={selectedFile}
+                  revealTick={revealTick}
+                  onSelectFile={setSelectedFile}
+                />
+              )}
+              {tab === 'calls' && (
+                <CallHeatTree report={report} onSelectFile={setSelectedFile} />
+              )}
+              {tab === 'react' && (
+                <ReactPanel
+                  report={report}
+                  hideVendor={hideVendor}
+                  onOpenFile={openFile}
+                />
+              )}
+              {tab === 'tasks' && (
+                <LongTasks report={report} onOpenFile={openFile} />
+              )}
+              {tab === 'network' && <NetworkPanel report={report} />}
+            </div>
+            {showPanel && (
+              <FilePanel
+                report={report}
+                path={selectedFile}
+                onClose={() => setSelectedFile(null)}
+              />
+            )}
+          </main>
+        )}
+        {!inCompare && !inEvaluation && !report && (
+          <Welcome onCompare={() => setTab('compare')} />
+        )}
+      </div>
+    </div>
+  );
+}

package/src/api.js

@@ -0,0 +1,51 @@
+async function request(method, url, body) {
+  const res = await fetch(url, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error || `${method} ${url}: ${res.status}`);
+  return data;
+}
+
+export const api = {
+  status: () => request('GET', '/api/status'),
+  connect: options => request('POST', '/api/connect', options),
+  disconnect: () => request('POST', '/api/disconnect', {}),
+  selectPage: id => request('POST', '/api/select-page', { id }),
+  navigate: (url, signIn) => request('POST', '/api/navigate', { url, signIn }),
+  reload: () => request('POST', '/api/reload', {}),
+  start: options => request('POST', '/api/record/start', options),
+  stop: () => request('POST', '/api/record/stop', {}),
+  reports: () => request('GET', '/api/reports'),
+  report: id => request('GET', `/api/reports/${encodeURIComponent(id)}`),
+  evaluations: () => request('GET', '/api/evaluations'),
+  evaluation: id =>
+    request('GET', `/api/evaluations/${encodeURIComponent(id)}`),
+  saveTrace: id =>
+    request('POST', `/api/reports/${encodeURIComponent(id)}/trace`, {}),
+  gitCommit: rev =>
+    request('GET', `/api/git/commit?rev=${encodeURIComponent(rev)}`),
+  /** @returns {Promise<{blob: Blob, name: string}>} */
+  comparePdf: async (comparison, kind) => {
+    const res = await fetch('/api/compare/pdf', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ comparison, kind }),
+    });
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({}));
+      throw new Error(data.error || `PDF export failed (${res.status})`);
+    }
+    const disposition = res.headers.get('content-disposition') || '';
+    return {
+      blob: await res.blob(),
+      name: /filename="([^"]+)"/.exec(disposition)?.[1] || 'comparison.pdf',
+    };
+  },
+  deleteReport: id =>
+    request('DELETE', `/api/reports/${encodeURIComponent(id)}`),
+  source: path =>
+    request('GET', `/api/source?path=${encodeURIComponent(path)}`),
+};

package/src/components/AppearanceMenu.jsx

@@ -0,0 +1,76 @@
+import { MODES, STYLES } from '../theme.js';
+import Popover from './Popover.jsx';
+
+const PaletteIcon = () => (
+  <svg
+    className="icon"
+    viewBox="0 0 16 16"
+    width="14"
+    height="14"
+    aria-hidden="true"
+  >
+    <path
+      fill="currentColor"
+      d="M8 1a7 7 0 1 0 0 14c1 0 1.5-.7 1.5-1.4 0-.9-.6-1.1-.6-1.9 0-.7.6-1.2 1.3-1.2H12a3 3 0 0 0 3-3C15 3.6 11.9 1 8 1Zm-4 7a1 1 0 1 1 0-2 1 1 0 0 1 0 2Zm2-3a1 1 0 1 1 0-2 1 1 0 0 1 0 2Zm4 0a1 1 0 1 1 0-2 1 1 0 0 1 0 2Zm2 3a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"
+    />
+  </svg>
+);
+
+function ChoiceGroup({ name, legend, options, value, onChange, variant }) {
+  return (
+    <fieldset className="choice-group">
+      <legend>{legend}</legend>
+      <div className={variant}>
+        {options.map(option => (
+          <label
+            key={option.id}
+            className={value === option.id ? 'choice selected' : 'choice'}
+          >
+            <input
+              type="radio"
+              name={name}
+              value={option.id}
+              checked={value === option.id}
+              onChange={() => onChange(option.id)}
+            />
+            {variant === 'theme-cards' && (
+              <span className={`swatch swatch-${option.id}`} aria-hidden="true">
+                <i />
+                <i />
+              </span>
+            )}
+            <span className="choice-label">{option.label}</span>
+            {option.description && (
+              <small className="muted">{option.description}</small>
+            )}
+          </label>
+        ))}
+      </div>
+    </fieldset>
+  );
+}
+
+export default function AppearanceMenu({ appearance, onChange }) {
+  return (
+    <Popover label="Appearance" icon={<PaletteIcon />}>
+      <div className="appearance">
+        <ChoiceGroup
+          name="theme-style"
+          legend="Theme"
+          options={STYLES}
+          value={appearance.style}
+          onChange={style => onChange({ style })}
+          variant="theme-cards"
+        />
+        <ChoiceGroup
+          name="theme-mode"
+          legend="Mode"
+          options={MODES}
+          value={appearance.mode}
+          onChange={mode => onChange({ mode })}
+          variant="segmented-control"
+        />
+      </div>
+    </Popover>
+  );
+}

package/src/components/CodeRef.jsx

@@ -0,0 +1,48 @@
+import { splitPath } from '../format.js';
+
+/** `file:line` as a link that opens the file in the tool, plus an “open in editor” link. */
+export default function CodeRef({ file, line, lineKind, abs, onOpenFile }) {
+  if (!file) return <span className="muted">unknown file</span>;
+  const { dir, name } = splitPath(file);
+  const label = `${line ? `${lineKind === 'located' ? '≈' : ''}${line}` : ''}`;
+  return (
+    <span className="code-ref">
+      {onOpenFile ? (
+        <button
+          type="button"
+          className="link mono"
+          onClick={() => onOpenFile(file)}
+          title={file}
+        >
+          <span className="muted">{dir}</span>
+          <b>{name}</b>
+          {label && <span>:{label}</span>}
+        </button>
+      ) : (
+        <span className="mono" title={file}>
+          <span className="muted">{dir}</span>
+          <b>{name}</b>
+          {label && <span>:{label}</span>}
+        </span>
+      )}
+      {abs && (
+        <a
+          className="editor-link"
+          href={`vscode://file/${abs}${line ? `:${line}` : ''}`}
+          title="Open in VS Code"
+        >
+          ↗ editor
+        </a>
+      )}
+      {lineKind === 'located' && (
+        <span
+          className="muted"
+          title="Webpack dev bundles have no source map, so the line was found by searching the file for this function's definition."
+        >
+          {' '}
+          (line found by name)
+        </span>
+      )}
+    </span>
+  );
+}