@progen-labs/spectra 0.1.0 → 0.1.1

package/dist/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Performance Profiler</title>
     <link rel="icon" href="data:," />
-    <script type="module" crossorigin src="/assets/index-BvBsPok5.js"></script>
+    <script type="module" crossorigin src="/assets/index-D0Lxrmdt.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Da3Le5Px.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progen-labs/spectra",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Spectra — a Chrome DevTools Protocol profiler that identifies the files, functions and components causing frontend slowness, across React, Vue, Svelte, Angular and Next.js builds.",
   "type": "module",
   "bin": {

package/server/analysis/findings.js

@@ -226,9 +226,28 @@ export function buildFindings(report) {
     });
   }
 
-  // ----- React ------------------------------------------------------------
+  // ----- Components (React / Vue / …) -------------------------------------
   const componentCulprit = (c, ms, note) =>
     culprit(c.name, c.file, c.line, c.lineKind, c.abs, ms, note);
+  const fw = react.framework || 'react';
+  const CAT =
+    fw === 'vue'
+      ? 'Vue'
+      : fw === 'svelte'
+        ? 'Svelte'
+        : fw === 'angular'
+          ? 'Angular'
+          : 'React';
+  const slowFix =
+    fw === 'vue'
+      ? 'Move expensive work into a computed property, use v-memo/v-once for static subtrees, and virtualise long lists.'
+      : fw === 'react' || fw === 'next'
+        ? 'Move expensive calculations into useMemo, virtualise long lists, and avoid deriving large data structures inside render.'
+        : 'Memoize expensive work, virtualise long lists, and avoid building large data structures during render.';
+  const frequentFix =
+    fw === 'vue'
+      ? 'Find the reactive dependency that changes this often (a ref/store/timer), narrow it, and use v-memo to skip unchanged subtrees.'
+      : 'Find what updates this often (a timer, a store subscription, a scroll handler) and throttle it or narrow the selector/subscription.';
   if (react.detected && react.hasTimings) {
     react.components
       .filter(c => c.wasted >= 5 && c.wasted / c.renders >= 0.3)
@@ -240,7 +259,7 @@ export function buildFindings(report) {
           id: `wasted-${c.name}-${c.file}`,
           severity:
             c.wastedMs >= 30 || c.wasted >= 100 ? 'critical' : 'warning',
-          category: 'React',
+          category: CAT,
           title: `${c.name} re-rendered ${c.renders}× — ${c.wasted} with nothing changed (${Math.round((c.wasted / c.renders) * 100)}%)`,
           detail:
             `${where(c.file, c.line)}. ${fmt(c.wastedMs)} spent on renders whose props, state and context were identical.` +
@@ -272,7 +291,7 @@ export function buildFindings(report) {
         add({
           id: `unstable-${c.name}-${p.prop}`,
           severity: 'warning',
-          category: 'React',
+          category: CAT,
           title: `${c.name} gets a new ${p.kind === 'function' ? 'function' : 'object'} for “${p.prop}” on every render (${p.count}×)`,
           detail: `${where(c.file, c.line)}. The value is recreated with ${p.kind === 'function' ? 'identical code' : 'identical contents'} but a new identity, which defeats React.memo and re-triggers effects that depend on it. Look at where ${c.topParent || 'the parent'} passes “${p.prop}”.`,
           file: c.file,
@@ -300,13 +319,13 @@ export function buildFindings(report) {
         add({
           id: `slow-component-${c.name}-${c.file}`,
           severity: c.selfMs >= 300 ? 'critical' : 'warning',
-          category: 'React',
+          category: CAT,
           title: `${c.name} is slow to render: ${fmt(c.selfMs)} total, ${fmt(c.selfMs / c.renders)} per render (${c.renders}×)`,
           detail: `${where(c.file, c.line)}. Self time excludes its children.`,
           file: c.file,
           culprits: [componentCulprit(c, c.selfMs, 'slow render')],
           impactMs: c.selfMs,
-          fix: 'Move expensive calculations into useMemo, virtualise long lists, and avoid deriving large data structures inside render.',
+          fix: slowFix,
         });
       });
     react.components
@@ -321,7 +340,7 @@ export function buildFindings(report) {
         add({
           id: `frequent-${c.name}-${c.file}`,
           severity: 'warning',
-          category: 'React',
+          category: CAT,
           title: `${c.name} rendered ${c.renders}× (${(c.renders / (report.meta.durationMs / 1000)).toFixed(0)}/s)`,
           detail: `${where(c.file, c.line)}. Reasons: ${
             Object.entries(c.reasons)
@@ -332,7 +351,7 @@ export function buildFindings(report) {
           file: c.file,
           culprits: [componentCulprit(c, c.selfMs, 'renders very often')],
           impactMs: c.selfMs,
-          fix: 'Find what updates this often (a timer, a store subscription, a scroll handler) and throttle it or narrow the selector/subscription.',
+          fix: frequentFix,
         });
       });
     react.slowCommits.slice(0, 3).forEach((c, i) => {
@@ -340,8 +359,8 @@ export function buildFindings(report) {
       add({
         id: `commit-${i}`,
         severity: c.dur >= 100 ? 'critical' : 'warning',
-        category: 'React',
-        title: `React commit took ${fmt(c.dur)} (${c.rendered} components rendered, ${c.wasted} wasted)`,
+        category: CAT,
+        title: `${CAT} commit took ${fmt(c.dur)} (${c.rendered} components rendered, ${c.wasted} wasted)`,
         detail: `At ${(c.tMs / 1000).toFixed(2)}s.`,
         culprits: react.components
           .slice(0, 3)
@@ -356,20 +375,20 @@ export function buildFindings(report) {
     add({
       id: 'react-prod',
       severity: 'info',
-      category: 'React',
-      title: 'React is a production build: render timings are unavailable',
+      category: CAT,
+      title: `${CAT} is a production build: render timings are unavailable`,
       detail:
         'Render counts and reasons are still collected where possible, but durations need a development or profiling build.',
-      fix: 'Profile against the dev server (npm run start / webpack-dev-server).',
+      fix: 'Profile against the dev server (npm run dev / start).',
     });
   } else if (!react.detected) {
     add({
       id: 'react-missing',
       severity: 'info',
-      category: 'React',
-      title: 'No React renderer was seen on this page',
+      category: CAT,
+      title: `No ${CAT === 'React' ? 'React renderer' : CAT + ' app'} was seen on this page`,
       detail:
-        'The probe must be installed before React loads. Use “Reload & record” (or Reload after connecting) so it is injected first.',
+        'The probe must be installed before the framework loads (use “Reload & record”), and component-level timings need a development build.',
       fix: 'Click “Record page load”, or reload the tab from this tool.',
     });
   }

package/server/analysis/report.js

@@ -19,8 +19,21 @@ import {
   findMainThread,
 } from './trace.js';
 import { packageOf } from './sources.js';
+import path from 'node:path';
+import { FRONTEND_ROOT } from '../config.js';
 
 const round = (n, d = 2) => Math.round(n * 10 ** d) / 10 ** d;
+
+/** Turn an absolute component file (e.g. Vue SFC __file) into a project path. */
+function toProjectRelative(abs) {
+  try {
+    if (!abs || !path.isAbsolute(abs)) return abs || '';
+    const rel = path.relative(FRONTEND_ROOT, abs);
+    return rel.startsWith('..') ? abs : rel;
+  } catch {
+    return abs || '';
+  }
+}
 const ms = us => us / 1000;
 
 function newFile(path, vendor, pkg) {
@@ -635,6 +648,7 @@ function summarizeReact(
 ) {
   const empty = {
     detected: false,
+    framework: probe?.info?.framework || '',
     hasTimings: false,
     version: '',
     components: [],
@@ -642,12 +656,22 @@ function summarizeReact(
     slowCommits: [],
     commitSeries: [],
   };
-  if (!probe || !probe.info?.react) return empty;
+  if (!probe || !probe.info?.detected) return empty;
   const originMs = probe.since || 0;
   const components = probe.components
     .map(c => {
       let loc;
-      if (locations.has(c.id)) {
+      if (c.file) {
+        // Adapters that know the component's source file directly (e.g. Vue SFCs).
+        const rel = toProjectRelative(c.file);
+        loc = {
+          file: rel,
+          line: c.line || null,
+          vendor: /(^|\/)node_modules\//.test(rel),
+          pkg: null,
+          exact: false,
+        };
+      } else if (locations.has(c.id)) {
         const l = locations.get(c.id);
         const script = resolver.scripts.get(String(l.scriptId));
         loc = resolver.resolve(
@@ -722,6 +746,7 @@ function summarizeReact(
   const sorted = [...commits].sort((a, b) => b.dur - a.dur);
   return {
     detected: true,
+    framework: probe.info.framework || 'react',
     hasTimings: probe.info.timings,
     version: probe.info.version,
     components: components.slice(0, 600),

package/server/probe.browser.js

@@ -15,7 +15,11 @@
   if (window.__PERF_PROBE__) return;
   // Runtime hint injected by the profiler: { framework, bundler, isSSR }
   var SPECTRA_FRAMEWORK = typeof window.__SPECTRA_FRAMEWORK__ !== 'undefined' ? window.__SPECTRA_FRAMEWORK__ : null;
-  var WANT_REACT = !SPECTRA_FRAMEWORK || SPECTRA_FRAMEWORK.framework === 'react' || SPECTRA_FRAMEWORK.framework === 'unknown';
+  var WANT_REACT =
+    !SPECTRA_FRAMEWORK ||
+    SPECTRA_FRAMEWORK.framework === 'react' ||
+    SPECTRA_FRAMEWORK.framework === 'next' ||
+    SPECTRA_FRAMEWORK.framework === 'unknown';
 
   var PERFORMED_WORK = 1;
   var TAG_FUNCTION = 0;
@@ -521,9 +525,14 @@
   };
 
   probe.info = function () {
+    var fw =
+      probe.frameworkName ||
+      (probe.renderers > 0 ? 'react' : (SPECTRA_FRAMEWORK && SPECTRA_FRAMEWORK.framework) || '');
     return {
       react: probe.renderers > 0,
-      version: probe.reactVersion,
+      framework: fw,
+      detected: probe.renderers > 0 || !!probe.frameworkDetected,
+      version: probe.reactVersion || probe.frameworkVersion || '',
       active: probe.active,
       timings: probe.sawTimings,
     };
@@ -584,6 +593,134 @@
     // Fail silently: probe should still collect vitals even if hooking fails.
   }
 
+  // ------------------------------------------------ Vue adapter
+  // Uses Vue's devtools global hook (dev builds). component:added / :updated
+  // give per-component mount/update counts and names, and perf:start / perf:end
+  // give real per-component render time. Component source files come straight
+  // from the SFC compiler (type.__file), so no source-map step is needed.
+  function installVueAdapter() {
+    var vueIds = new Map();
+    var nextId = 0;
+    var perfStart = {};
+
+    function getStat(instance) {
+      if (!instance || !instance.type) return null;
+      var type = instance.type;
+      var id = vueIds.get(type);
+      if (id === undefined) {
+        id = nextId++;
+        vueIds.set(type, id);
+      }
+      var stat = probe.stats[id];
+      if (!stat) {
+        stat = probe.stats[id] = {
+          id: id,
+          name: type.__name || type.name || type.__file && baseName(type.__file) || 'Anonymous',
+          kind: 'vue',
+          renders: 0,
+          mounts: 0,
+          wasted: 0,
+          selfMs: 0,
+          totalMs: 0,
+          maxMs: 0,
+          reasons: { props: 0, state: 0, hooks: 0, context: 0, parent: 0 },
+          props: {},
+          parents: {},
+          file: type.__file || '',
+        };
+      }
+      return stat;
+    }
+
+    function baseName(p) {
+      var parts = String(p).split(/[\\/]/);
+      return parts[parts.length - 1].replace(/\.\w+$/, '');
+    }
+
+    function recordParent(stat, instance) {
+      var p = instance && instance.parent;
+      var name = p && p.type && (p.type.__name || p.type.name);
+      if (name) stat.parents[name] = (stat.parents[name] || 0) + 1;
+    }
+
+    function bumpCommit(dur) {
+      probe.commits.push({ t: performance.now(), dur: dur || 0, rendered: 1, wasted: 0 });
+      probe.commitCount = (probe.commitCount || 0) + 1;
+    }
+
+    function handle(evt, args) {
+      if (evt === 'app:init') {
+        probe.frameworkName = 'vue';
+        probe.frameworkDetected = true;
+        probe.frameworkVersion = args[1] || '';
+        return;
+      }
+      if (!probe.active) return;
+      if (evt === 'component:added') {
+        var stat = getStat(args[3]);
+        if (stat) {
+          stat.mounts++;
+          stat.renders++;
+          recordParent(stat, args[3]);
+          bumpCommit();
+        }
+        return;
+      }
+      if (evt === 'component:updated') {
+        var s2 = getStat(args[3]);
+        if (s2) {
+          s2.renders++;
+          recordParent(s2, args[3]);
+          bumpCommit();
+        }
+        return;
+      }
+      if (evt === 'perf:start' || evt === 'perf:end') {
+        var uid = args[1];
+        var inst = args[2];
+        var phase = args[3];
+        var time = args[4];
+        var key = uid + ':' + phase;
+        if (evt === 'perf:start') {
+          perfStart[key] = time;
+          return;
+        }
+        var start = perfStart[key];
+        if (start === undefined) return;
+        delete perfStart[key];
+        var dur = Math.max(0, time - start);
+        var st = getStat(inst);
+        if (!st) return;
+        if (phase === 'render') {
+          st.selfMs += dur;
+          st.totalMs += dur;
+          if (dur > st.maxMs) st.maxMs = dur;
+          probe.sawTimings = true;
+        } else if (phase === 'patch') {
+          st.totalMs += dur;
+        }
+      }
+    }
+
+    var existing = window.__VUE_DEVTOOLS_GLOBAL_HOOK__;
+    var hook = existing || {};
+    hook.enabled = true;
+    hook.apps = hook.apps || [];
+    hook.store = hook.store || {};
+    var prevEmit = typeof hook.emit === 'function' ? hook.emit.bind(hook) : null;
+    hook.on = hook.on || function () {};
+    hook.once = hook.once || function () {};
+    hook.off = hook.off || function () {};
+    hook.emit = function (evt) {
+      try {
+        handle(evt, Array.prototype.slice.call(arguments, 1));
+      } catch (e) {}
+      if (prevEmit) try { prevEmit.apply(null, arguments); } catch (e) {}
+    };
+    window.__VUE_DEVTOOLS_GLOBAL_HOOK__ = hook;
+    probe.frameworkName = 'vue';
+  }
+
   // ------------------------------------------------ Framework fallbacks
   // Provide lightweight probes for Vue, Svelte and Angular when React is not detected.
   function installFrameworkProbes() {
@@ -683,7 +820,9 @@
   }
 
   try {
-    if (!WANT_REACT) installFrameworkProbes();
+    var fwHint = SPECTRA_FRAMEWORK && SPECTRA_FRAMEWORK.framework;
+    if (fwHint === 'vue') installVueAdapter();
+    else if (!WANT_REACT) installFrameworkProbes(); // svelte/angular: heuristic for now
   } catch (e) {}
   installObservers();
 })();

package/src/App.jsx

@@ -23,7 +23,7 @@ const TABS = [
   { id: 'page', label: 'Page map' },
   { id: 'files', label: 'File tree' },
   { id: 'calls', label: 'Call tree' },
-  { id: 'react', label: 'React' },
+  { id: 'react', label: 'Components' },
   { id: 'tasks', label: 'Long tasks' },
   { id: 'network', label: 'Network & memory' },
   { id: 'evaluation', label: 'Golden paths' },

package/src/components/Culprits.jsx

@@ -5,6 +5,7 @@ import CulpritsHero from './CulpritsHero.jsx';
 import FindingsList from './FindingsList.jsx';
 import TimeBreakdown from './TimeBreakdown.jsx';
 import Vitals from './Vitals.jsx';
+import SpectraCulprits from './SpectraCulprits.jsx';
 
 function HotFunctions({ report, hideVendor, onOpenFile }) {
   const rows = (report.hotFunctions || [])
@@ -73,6 +74,7 @@ export default function Culprits({ report, hideVendor, onOpenFile }) {
         onJump={id => setFocus(prev => ({ id, tick: (prev?.tick || 0) + 1 }))}
       />
       <Vitals report={report} />
+      <SpectraCulprits report={report} onOpenFile={onOpenFile} />
       <section>
         <h2>Where main-thread time went</h2>
         <TimeBreakdown totals={report.totals} />

package/src/components/ReactPanel.jsx

@@ -101,14 +101,18 @@ export default function ReactPanel({ report, hideVendor, onOpenFile }) {
       );
   }, [react.components, sort, hideVendor]);
 
+  const fwLabel =
+    { vue: 'Vue', svelte: 'Svelte', angular: 'Angular', next: 'React' }[
+      react.framework
+    ] || 'React';
   if (!react.detected) {
     return (
       <div className="empty">
-        <h3>No React renderer was detected</h3>
+        <h3>No component framework was detected</h3>
         <p>
-          The probe has to be installed before React loads. Use{' '}
+          The probe has to be installed before the framework loads. Use{' '}
           <b>Record page load</b>, or reload the tab from this tool and record
-          again.
+          again. Component timings need a development build.
         </p>
       </div>
     );
@@ -116,7 +120,9 @@ export default function ReactPanel({ report, hideVendor, onOpenFile }) {
   return (
     <div className="react-panel">
       <div className="summary-row">
-        <span>React {react.version}</span>
+        <span>
+          {fwLabel} {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>

package/src/components/SpectraCulprits.jsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import CodeRef from './CodeRef.jsx';
+
+export default function SpectraCulprits({ report, onOpenFile }) {
+  const culprits = report.spectra?.culprits || [];
+  if (!culprits || !culprits.length) return null;
+  return (
+    <section>
+      <h2>Spectra SDK Culprits</h2>
+      <p className="muted">Suggestions from the embedded Spectra core SDK.</p>
+      <table className="data spectra-culprits">
+        <thead>
+          <tr>
+            <th>#</th>
+            <th>Component</th>
+            <th>File</th>
+            <th>Time</th>
+          </tr>
+        </thead>
+        <tbody>
+          {culprits.map((c, i) => (
+            <tr key={`${c.filePath}|${c.componentName}|${i}`}>
+              <td className="num">{i + 1}</td>
+              <td>{c.componentName}</td>
+              <td>
+                <CodeRef
+                  file={c.filePath}
+                  line={c.lineNumber}
+                  onOpenFile={onOpenFile}
+                />
+              </td>
+              <td className="num">{c.durationMs ? `${Math.round(c.durationMs)}ms` : '-'}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}