@progen-labs/spectra 0.0.0-stage → 0.1.0

package/src/components/ControlBar.jsx

@@ -0,0 +1,336 @@
+import { useEffect, useState } from 'react';
+import { api } from '../api.js';
+import { ChevronIcon, PageLoadIcon, RecordIcon, StopIcon } from './Icons.jsx';
+import Popover from './Popover.jsx';
+
+const URL_KEY = 'perf-profiler:url';
+const SIGNIN_KEY = 'perf-profiler:sign-in';
+const readSignIn = () => localStorage.getItem(SIGNIN_KEY) || '';
+
+function Elapsed({ startedAt }) {
+  const [now, setNow] = useState(Date.now());
+  useEffect(() => {
+    // Ticks the on-screen recording timer; cleared on unmount.
+    const id = setInterval(() => setNow(Date.now()), 250);
+    return () => clearInterval(id);
+  }, []);
+  return (
+    <span className="elapsed">{((now - startedAt) / 1000).toFixed(1)} s</span>
+  );
+}
+
+function ProbePill({ probe }) {
+  if (!probe) return null;
+  if (probe.react) {
+    return (
+      <span
+        className="pill ok"
+        title="React was detected; per-component render data will be recorded."
+      >
+        ✓ React {probe.version}
+        {probe.timings ? '' : ' · no timings (production build)'}
+      </span>
+    );
+  }
+  // If a non-React framework was detected, show that instead of the reload hint
+  if (probe.framework && probe.framework.name) {
+    return (
+      <span className="pill ok" title={`Detected ${probe.framework.name}`}>
+        ✓ {probe.framework.name} {probe.framework.version || ''}
+      </span>
+    );
+  }
+  return (
+    <span
+      className="pill warn"
+      title="The probe must load before React. Use Reload, or “Record page load”."
+    >
+      ! No React seen — reload
+    </span>
+  );
+}
+
+function Connect({ status, run, isCompact }) {
+  const [url, setUrl] = useState(
+    () => localStorage.getItem(URL_KEY) || status.defaultUrl || '',
+  );
+  const [headless, setHeadless] = useState(false);
+  const [browserURL, setBrowserURL] = useState('http://127.0.0.1:9222');
+  const [busy, setBusy] = useState(false);
+  const [signIn, setSignIn] = useState(readSignIn);
+  const [isAdvancedOpen, setIsAdvancedOpen] = useState(false);
+  const go = async options => {
+    if (options.url) localStorage.setItem(URL_KEY, options.url);
+    localStorage.setItem(SIGNIN_KEY, signIn);
+    setBusy(true);
+    await run(() => api.connect(options));
+    setBusy(false);
+  };
+  return (
+    <div className="connect">
+      {!isCompact && (
+        <div className="connect-head">
+          <h2>Connect to a browser</h2>
+          <p className="muted">
+            Launch a fresh Chrome window, sign in, and open the page you want to
+            profile.
+          </p>
+        </div>
+      )}
+      <div className="connect-main">
+        <label className="field">
+          Page to profile
+          <input
+            type="url"
+            value={url}
+            onChange={e => setUrl(e.target.value)}
+            placeholder="http://localhost:3000/"
+          />
+        </label>
+        <button
+          type="button"
+          className="primary"
+          disabled={busy}
+          onClick={() => go({ mode: 'launch', url, headless, signIn })}
+        >
+          {busy ? 'Starting Chrome…' : 'Launch Chrome'}
+        </button>
+        <button
+          type="button"
+          className="ghost"
+          aria-expanded={isAdvancedOpen}
+          onClick={() => setIsAdvancedOpen(open => !open)}
+        >
+          Advanced <ChevronIcon isUp={isAdvancedOpen} />
+        </button>
+      </div>
+      {isAdvancedOpen && (
+        <div className="advanced">
+          <div className="advanced-section">
+            <div className="advanced-row">
+              <label
+                className="field"
+                title="Used automatically when the page fails to load or lands on a login screen. {url} is replaced with the page above. Do not put tokens in it."
+              >
+                Sign-in URL <span className="muted">(optional)</span>
+                <input
+                  value={signIn}
+                  onChange={e => setSignIn(e.target.value)}
+                  placeholder="http://localhost:3000/login/?redirect={url}"
+                />
+              </label>
+              <label className="switch">
+                <input
+                  type="checkbox"
+                  role="switch"
+                  checked={headless}
+                  onChange={e => setHeadless(e.target.checked)}
+                />
+                Headless
+              </label>
+            </div>
+            <span className="muted">
+              The Chrome window starts signed out every time, so give it your
+              app’s login URL once; {'{url}'} is where the page to profile goes.
+            </span>
+          </div>
+          <div className="advanced-section">
+            <div className="advanced-row">
+              <label className="field">
+                Attach to a running Chrome
+                <input
+                  value={browserURL}
+                  onChange={e => setBrowserURL(e.target.value)}
+                />
+              </label>
+              <button
+                type="button"
+                disabled={busy}
+                onClick={() => go({ mode: 'attach', browserURL })}
+              >
+                Attach
+              </button>
+            </div>
+            <span className="muted">
+              Start it with <code>--remote-debugging-port=9222</code>
+            </span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function RecordingOptions({ throttle, setThrottle, saveTrace, setSaveTrace }) {
+  return (
+    <Popover label="Options" align="left">
+      <div className="options-list">
+        <label className="field">
+          <span className="field-label">CPU throttling</span>
+          <select
+            value={throttle}
+            onChange={e => setThrottle(Number(e.target.value))}
+          >
+            <option value={1}>No throttling</option>
+            <option value={4}>4× slowdown</option>
+            <option value={6}>6× slowdown</option>
+          </select>
+        </label>
+        <label className="switch">
+          <input
+            type="checkbox"
+            role="switch"
+            checked={saveTrace}
+            onChange={e => setSaveTrace(e.target.checked)}
+          />
+          Save raw trace for DevTools
+        </label>
+      </div>
+    </Popover>
+  );
+}
+
+function RecordRow({ status, run }) {
+  const [throttle, setThrottle] = useState(1);
+  const [saveTrace, setSaveTrace] = useState(false);
+  const { state } = status;
+  const options = mode => ({ mode, cpuThrottle: throttle, saveTrace });
+  if (state === 'recording')
+    return (
+      <div className="rec-strip recording">
+        <span className="rec">
+          <i /> Recording
+          {status.recording?.mode === 'load' ? ' page load' : ''}{' '}
+          <Elapsed startedAt={status.recording.startedAt} />
+        </span>
+        <span className="muted">
+          {status.recording?.mode === 'load'
+            ? 'Stops on its own a few seconds after the page finishes loading.'
+            : 'Use the page now — click, scroll, type — then stop.'}
+        </span>
+        <span className="spacer" />
+        <button type="button" className="danger" onClick={() => run(api.stop)}>
+          <StopIcon /> Stop &amp; analyse
+        </button>
+      </div>
+    );
+  if (state === 'analyzing')
+    return (
+      <div className="rec-strip">
+        <span className="rec">
+          <i className="spin" /> Analysing trace, CPU samples and source maps…
+        </span>
+      </div>
+    );
+  return (
+    <div className="rec-strip">
+      <button
+        type="button"
+        className="primary"
+        onClick={() => run(() => api.start(options('live')))}
+      >
+        <RecordIcon /> Record interaction
+      </button>
+      <button
+        type="button"
+        onClick={() => run(() => api.start(options('load')))}
+      >
+        <PageLoadIcon /> Record page load
+      </button>
+      <RecordingOptions
+        throttle={throttle}
+        setThrottle={setThrottle}
+        saveTrace={saveTrace}
+        setSaveTrace={setSaveTrace}
+      />
+      {throttle > 1 && (
+        <span className="pill warn">{throttle}× CPU slowdown</span>
+      )}
+    </div>
+  );
+}
+
+export default function ControlBar({ status, run, isCompact }) {
+  const [address, setAddress] = useState('');
+  useEffect(() => {
+    if (status?.pageUrl) setAddress(status.pageUrl);
+  }, [status?.pageUrl]);
+
+  if (!status)
+    return (
+      <section className="session">
+        <span className="muted">Connecting to the profiler server…</span>
+      </section>
+    );
+  if (!status.connected)
+    return (
+      <section className="session">
+        <Connect status={status} run={run} isCompact={isCompact} />
+      </section>
+    );
+
+  const failed =
+    status.navigation && status.navigation.status >= 400
+      ? status.navigation
+      : null;
+  const idle = status.state === 'idle';
+  return (
+    <section className="session" aria-label="Browser session">
+      {failed && (
+        <div className="error" role="alert">
+          <span>
+            The page answered <b>HTTP {failed.status}</b> ({failed.url}). You
+            are probably not signed in. Press Go to retry (the saved Sign-in URL
+            is applied automatically), or sign in by hand in the Chrome window.
+            If no Sign-in URL was saved, close Chrome and launch again with one.
+          </span>
+        </div>
+      )}
+      <div className="session-row">
+        <select
+          aria-label="Browser tab"
+          value={status.pages.find(p => p.selected)?.id ?? ''}
+          disabled={!idle}
+          onChange={e => run(() => api.selectPage(Number(e.target.value)))}
+        >
+          {status.pages.map(p => (
+            <option key={p.id} value={p.id}>
+              {p.title || p.url}
+            </option>
+          ))}
+        </select>
+        <input
+          className="address"
+          aria-label="Page URL"
+          value={address}
+          disabled={!idle}
+          onChange={e => setAddress(e.target.value)}
+          onKeyDown={e =>
+            e.key === 'Enter' && run(() => api.navigate(address, readSignIn()))
+          }
+        />
+        <button
+          type="button"
+          disabled={!idle}
+          onClick={() => run(() => api.navigate(address, readSignIn()))}
+        >
+          Go
+        </button>
+        <button type="button" disabled={!idle} onClick={() => run(api.reload)}>
+          Reload
+        </button>
+            <ProbePill probe={status.probe} />
+        <button
+          type="button"
+          className="ghost destructive"
+          onClick={() => run(api.disconnect)}
+        >
+          {status.launched ? 'Close Chrome' : 'Detach'}
+        </button>
+      </div>
+      <div className="session-row">
+        <RecordRow status={status} run={run} />
+      </div>
+    </section>
+  );
+}

package/src/components/CulpritSphere.jsx

@@ -0,0 +1,218 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { fmtMs } from '../format.js';
+
+const FOV = 3;
+const RADIUS = 0.8;
+const AUTO_SPIN = 0.00035;
+const DRAG_SPEED = 0.008;
+const MAX_TILT = 1.2;
+const LAT_DEG = [-60, -30, 0, 30, 60];
+const MERIDIANS = 6;
+const RING_POINTS = 48;
+const MAX_NAME = 20;
+
+// Evenly spread points on a unit sphere (Fibonacci lattice).
+function latticePoints(n) {
+  const golden = Math.PI * (3 - Math.sqrt(5));
+  return Array.from({ length: n }, (_, i) => {
+    const y = n === 1 ? 0 : 1 - (2 * (i + 0.5)) / n;
+    const r = Math.sqrt(Math.max(0, 1 - y * y));
+    return [Math.cos(i * golden) * r, y, Math.sin(i * golden) * r];
+  });
+}
+
+function rotate([x, y, z], ax, ay) {
+  const cy = Math.cos(ay);
+  const sy = Math.sin(ay);
+  const x1 = x * cy + z * sy;
+  const z1 = -x * sy + z * cy;
+  const cx = Math.cos(ax);
+  const sx = Math.sin(ax);
+  return [x1, y * cx - z1 * sx, y * sx + z1 * cx];
+}
+
+// Perspective: nearer points are bigger and further from the centre.
+function project(p, ax, ay) {
+  const [x, y, z] = rotate(p, ax, ay);
+  const k = FOV / (FOV - z);
+  return { x: x * k * RADIUS, y: y * k * RADIUS, z, k };
+}
+
+function ringPoints(fn) {
+  return Array.from({ length: RING_POINTS + 1 }, (_, i) =>
+    fn((i / RING_POINTS) * Math.PI * 2),
+  );
+}
+
+const WIREFRAME = [
+  ...LAT_DEG.map(deg => {
+    const lat = (deg * Math.PI) / 180;
+    return ringPoints(t => [
+      Math.cos(lat) * Math.cos(t),
+      Math.sin(lat),
+      Math.cos(lat) * Math.sin(t),
+    ]);
+  }),
+  ...Array.from({ length: MERIDIANS }, (_, m) => {
+    const lon = (m / MERIDIANS) * Math.PI;
+    return ringPoints(t => [
+      Math.cos(t) * Math.cos(lon),
+      Math.sin(t),
+      Math.cos(t) * Math.sin(lon),
+    ]);
+  }),
+];
+
+const shortName = name =>
+  name.length > MAX_NAME ? `${name.slice(0, MAX_NAME - 1)}…` : name;
+
+/**
+ * Culprits as labels on a slowly rotating sphere. Drag to spin it; hovering a
+ * label pauses it. The motion is driven straight onto the DOM nodes (no React
+ * render per frame) and is off entirely for people who ask for reduced motion.
+ */
+export default function CulpritSphere({
+  items,
+  activeKey,
+  highlightKey,
+  onActivate,
+  onSelect,
+}) {
+  const points = useMemo(() => latticePoints(items.length), [items.length]);
+  const maxMs = Math.max(1, ...items.map(i => i.ms));
+  const labelRefs = useRef([]);
+  const pathRefs = useRef([]);
+  const motion = useRef({
+    ax: -0.35,
+    ay: 0,
+    vy: 0,
+    vx: 0,
+    isDragging: false,
+    isPaused: false,
+  });
+  const drag = useRef({ x: 0, y: 0 });
+
+  useEffect(() => {
+    motion.current.isPaused = Boolean(activeKey);
+  }, [activeKey]);
+
+  useEffect(() => {
+    const reduced = window.matchMedia(
+      '(prefers-reduced-motion: reduce)',
+    ).matches;
+    const paint = () => {
+      const { ax, ay } = motion.current;
+      points.forEach((p, i) => {
+        const el = labelRefs.current[i];
+        if (!el) return;
+        const q = project(p, ax, ay);
+        const depth = (q.z + 1) / 2;
+        el.style.left = `${50 + q.x * 50}%`;
+        el.style.top = `${50 + q.y * 50}%`;
+        el.style.transform = `translate(-50%, -50%) scale(${0.7 + depth * 0.45})`;
+        el.style.opacity = String(0.16 + depth * 0.84);
+        el.style.zIndex = String(Math.round(depth * 100));
+        el.style.pointerEvents = q.z > -0.35 ? 'auto' : 'none';
+      });
+      WIREFRAME.forEach((ring, i) => {
+        const path = pathRefs.current[i];
+        if (!path) return;
+        path.setAttribute(
+          'd',
+          ring
+            .map((p, j) => {
+              const q = project(p, ax, ay);
+              return `${j ? 'L' : 'M'}${q.x.toFixed(3)} ${q.y.toFixed(3)}`;
+            })
+            .join(''),
+        );
+      });
+    };
+    paint();
+    // requestAnimationFrame: this is a continuous animation with no event to hook into.
+    let frame = 0;
+    let last = performance.now();
+    const tick = now => {
+      const m = motion.current;
+      const dt = Math.min(64, now - last);
+      last = now;
+      const isSpinning = !reduced && !m.isPaused && !m.isDragging;
+      const isCoasting = Math.abs(m.vy) > 1e-4 || Math.abs(m.vx) > 1e-4;
+      if (isSpinning || isCoasting) {
+        m.ay += (isSpinning ? AUTO_SPIN * dt : 0) + m.vy;
+        m.ax = Math.max(-MAX_TILT, Math.min(MAX_TILT, m.ax + m.vx));
+        if (!m.isDragging) {
+          m.vy *= 0.94;
+          m.vx *= 0.94;
+        }
+        paint();
+      }
+      frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+  }, [points]);
+
+  const handlePointerDown = e => {
+    if (e.target.closest('button')) return;
+    e.currentTarget.setPointerCapture(e.pointerId);
+    motion.current.isDragging = true;
+    drag.current = { x: e.clientX, y: e.clientY };
+  };
+  const handlePointerMove = e => {
+    const m = motion.current;
+    if (!m.isDragging) return;
+    m.vy = (e.clientX - drag.current.x) * DRAG_SPEED;
+    m.vx = -(e.clientY - drag.current.y) * DRAG_SPEED;
+    drag.current = { x: e.clientX, y: e.clientY };
+    m.ay += m.vy;
+    m.ax = Math.max(-MAX_TILT, Math.min(MAX_TILT, m.ax + m.vx));
+  };
+  const handlePointerUp = () => {
+    motion.current.isDragging = false;
+  };
+
+  return (
+    <div
+      className="sphere"
+      role="group"
+      aria-label="Top culprits on a rotating sphere. Drag to rotate."
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onPointerCancel={handlePointerUp}
+    >
+      <div className="sphere-glow" aria-hidden="true" />
+      <svg className="sphere-wire" viewBox="-1 -1 2 2" aria-hidden="true">
+        {WIREFRAME.map((_, i) => (
+          <path
+            key={i}
+            ref={el => {
+              pathRefs.current[i] = el;
+            }}
+          />
+        ))}
+      </svg>
+      {items.map((item, i) => (
+        <button
+          key={item.key}
+          ref={el => {
+            labelRefs.current[i] = el;
+          }}
+          type="button"
+          className={`orb sev-${item.severity} ${highlightKey === item.key ? 'active' : ''}`}
+          style={{ fontSize: `${0.7 + 0.28 * Math.sqrt(item.ms / maxMs)}rem` }}
+          title={item.name}
+          onMouseEnter={() => onActivate(item.key)}
+          onMouseLeave={() => onActivate(null)}
+          onFocus={() => onActivate(item.key)}
+          onBlur={() => onActivate(null)}
+          onClick={() => onSelect(item.key)}
+        >
+          <span className="orb-name">{shortName(item.name)}</span>
+          <span className="orb-ms">{fmtMs(item.ms)}</span>
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/components/Culprits.jsx

@@ -0,0 +1,118 @@
+import { useState } from 'react';
+import { fmtMs } from '../format.js';
+import CodeRef from './CodeRef.jsx';
+import CulpritsHero from './CulpritsHero.jsx';
+import FindingsList from './FindingsList.jsx';
+import TimeBreakdown from './TimeBreakdown.jsx';
+import Vitals from './Vitals.jsx';
+
+function HotFunctions({ report, hideVendor, onOpenFile }) {
+  const rows = (report.hotFunctions || [])
+    .filter(f => !(hideVendor && f.vendor))
+    .slice(0, 15);
+  if (!rows.length) return null;
+  return (
+    <section>
+      <h2>
+        Slowest functions{' '}
+        <span className="muted">(by time spent in the function itself)</span>
+      </h2>
+      <table className="data hot-functions">
+        <thead>
+          <tr>
+            <th>#</th>
+            <th>Function</th>
+            <th>File</th>
+            <th>Self</th>
+            <th>With callees</th>
+            <th>% of CPU</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((f, i) => (
+            <tr
+              key={`${f.file}|${f.name}|${f.bundleLine}`}
+              className={f.vendor ? 'vendor-row' : ''}
+            >
+              <td className="num">{i + 1}</td>
+              <td>
+                <code className="fn">{f.name}()</code>
+              </td>
+              <td>
+                <CodeRef
+                  file={f.file}
+                  line={f.line}
+                  lineKind={f.lineKind}
+                  abs={f.abs}
+                  onOpenFile={onOpenFile}
+                />
+              </td>
+              <td className="num">{fmtMs(f.selfMs)}</td>
+              <td className="num">{fmtMs(f.totalMs)}</td>
+              <td className="num">{f.share}%</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+
+export default function Culprits({ report, hideVendor, onOpenFile }) {
+  const [focus, setFocus] = useState(null);
+  const counts = report.findings.reduce(
+    (acc, f) => ({ ...acc, [f.severity]: (acc[f.severity] || 0) + 1 }),
+    {},
+  );
+  return (
+    <div className="culprits">
+      <CulpritsHero
+        report={report}
+        hideVendor={hideVendor}
+        onOpenFile={onOpenFile}
+        onJump={id => setFocus(prev => ({ id, tick: (prev?.tick || 0) + 1 }))}
+      />
+      <Vitals report={report} />
+      <section>
+        <h2>Where main-thread time went</h2>
+        <TimeBreakdown totals={report.totals} />
+      </section>
+      <HotFunctions
+        report={report}
+        hideVendor={hideVendor}
+        onOpenFile={onOpenFile}
+      />
+      <section>
+        <h2>
+          Findings{' '}
+          <span className="muted">
+            {counts.critical || 0} critical · {counts.warning || 0} warnings ·{' '}
+            {counts.info || 0} notes
+          </span>
+        </h2>
+        {report.findings.length === 0 ? (
+          <p className="muted">
+            Nothing stood out in this recording. Try a longer or more demanding
+            interaction.
+          </p>
+        ) : (
+          <FindingsList
+            findings={report.findings}
+            onOpenFile={onOpenFile}
+            focus={focus}
+          />
+        )}
+      </section>
+      {report.notes.length > 0 && (
+        <section>
+          <h2>Notes</h2>
+          <ul>
+            {report.notes.map(n => (
+              <li key={n}>{n}</li>
+            ))}
+          </ul>
+        </section>
+      )}
+    </div>
+  );
+}