@progen-labs/spectra 0.4.1 → 0.6.0

package/server/cli.js

@@ -17,6 +17,7 @@ import { PerfSession, readReport } from './recorder.js';
 import { REPORTS_DIR, TARGET_NAME } from './config.js';
 import { intOption, parseArgs } from './args.js';
 import { loadProjectConfig } from './project-config.js';
+import { SIGN_IN_HELP, logSignIn, signInFromOptions } from './signin.js';
 import { EXIT, SPECTRA_VERSION, exitAfterFlush, fmt, printBudgets, reportFile, writeResult } from './output.js';
 import { buildProfileResult } from '../shared/result.js';
 
@@ -25,7 +26,8 @@ const { opt, flag } = parseArgs(process.argv.slice(2));
 const url = opt('url');
 if (!url || flag('help')) {
   console.error(
-    'usage: npm run profile -- --url <page> [--mode live|load] [--runs n] [--duration seconds] [--throttle 4] [--scenario file.mjs] [--json] [--out file.json] [--config spectra.config.json] [--headed] [--save-trace] [--sign-in "http://host/login/?redirect={url}"]',
+    'usage: npm run profile -- --url <page> [--mode live|load] [--runs n] [--duration seconds] [--throttle 4] [--scenario file.mjs] [--json] [--out file.json] [--config spectra.config.json] [--headed] [--save-trace] [sign-in options]\n\n' +
+      SIGN_IN_HELP,
   );
   process.exit(url ? EXIT.OK : EXIT.ERROR);
 }
@@ -36,7 +38,7 @@ const out = opt('out');
 const log = json ? console.error : console.log;
 const sleep = ms => new Promise(r => setTimeout(r, ms));
 
-let mode, runs, duration, cpuThrottle, config, scenario;
+let mode, runs, duration, cpuThrottle, config, scenario, signIn;
 try {
   mode = opt('mode', 'live');
   if (!['live', 'load'].includes(mode)) throw new Error(`--mode must be live or load (got ${mode}).`);
@@ -44,6 +46,7 @@ try {
   duration = Number(opt('duration', 8)) * 1000;
   cpuThrottle = Number(opt('throttle', 1));
   config = loadProjectConfig(opt('config'));
+  signIn = signInFromOptions(opt, config.signIn);
   const scenarioFile = opt('scenario');
   if (scenarioFile) scenario = (await import(pathToFileURL(path.resolve(scenarioFile)).href)).default;
 } catch (err) {
@@ -82,7 +85,7 @@ async function recordOnce(session, index) {
   if (mode === 'load') return recordLoad(session, startOpts);
   // live: every run starts from the same freshly loaded page
   if (index > 0) {
-    await session.navigate(url, opt('sign-in'));
+    await session.navigate(url, signIn);
     await sleep(800);
   }
   await session.start(startOpts);
@@ -128,10 +131,13 @@ function printProfile(result, reports) {
 }
 
 const session = new PerfSession();
+logSignIn(session);
 const reports = [];
 let code = EXIT.OK;
 try {
-  await session.connect({ mode: 'launch', url, headless: !flag('headed'), signIn: opt('sign-in') });
+  // signing in yourself needs the window, so it shows Chrome even without --headed
+  await session.connect({ mode: 'launch', url, headless: !flag('headed') && signIn?.method !== 'manual', signIn });
+  if (session.signedIn) console.error('spectra: signed in');
   await sleep(1500);
   await session.reload(); // make sure the probe was installed before the app loaded
   await sleep(1000);

package/server/explore/evaluate-cli.js

@@ -13,6 +13,7 @@ import { readReport } from '../recorder.js';
 import { REPORTS_DIR, TARGET_NAME } from '../config.js';
 import { parseArgs } from '../args.js';
 import { loadProjectConfig } from '../project-config.js';
+import { signInFromOptions } from '../signin.js';
 import { EXIT, SPECTRA_VERSION, exitAfterFlush, printBudgets, reportFile, writeResult } from '../output.js';
 import { buildEvaluationResult } from '../../shared/result.js';
 
@@ -28,9 +29,10 @@ const out = opt('out');
 // In --json mode stdout carries only the result; people still see the matrix.
 const log = json ? console.error : console.log;
 
-let config;
+let config, signIn;
 try {
   config = loadProjectConfig(opt('config'));
+  signIn = signInFromOptions(opt, config.signIn);
 } catch (err) {
   console.error(`spectra: ${err.message}`);
   process.exit(EXIT.ERROR);
@@ -84,11 +86,19 @@ let result;
 try {
   result = await runEvaluation({
     url,
-    headless: !flag('headed'),
+    // signing in yourself needs the window, so it shows Chrome even without --headed
+    headless: !flag('headed') && signIn?.method !== 'manual',
     limit: Number(opt('paths', 12)),
-    signIn: opt('sign-in'),
+    signIn,
     onProgress: ev => {
-      if (ev.phase === 'baseline') console.error('spectra: recording baseline page load …');
+      if (ev.phase === 'sign-in')
+        console.error(
+          ev.method === 'manual'
+            ? 'spectra: sign in in the Chrome window (any way the app asks); Spectra carries on once you are in …'
+            : 'spectra: signing in through the login form …',
+        );
+      else if (ev.phase === 'signed-in') console.error('spectra: signed in');
+      else if (ev.phase === 'baseline') console.error('spectra: recording baseline page load …');
       else if (ev.phase === 'discover') console.error('spectra: discovering actionable elements …');
       else if (ev.phase === 'synthesized')
         console.error(

package/server/explore/evaluate.js

@@ -65,7 +65,7 @@ function recordBaseline(session) {
  * @param {boolean} [opts.headless]    default true
  * @param {number} [opts.limit]        max golden paths (default 12)
  * @param {string[]} [opts.allow]      selectors of destructive actions to permit
- * @param {string} [opts.signIn]       sign-in URL template
+ * @param {string|object} [opts.signIn] how to sign in (signin.js normalizeSignIn)
  * @param {(ev:object)=>void} [opts.onProgress]
  */
 export async function runEvaluation({
@@ -78,9 +78,11 @@ export async function runEvaluation({
 } = {}) {
   const log = onProgress || (() => {});
   const session = new PerfSession();
+  session.on('state', s => s.state === 'signing-in' && log({ phase: 'sign-in', method: s.method }));
   const results = [];
   try {
     await session.connect({ mode: 'launch', url, headless, signIn });
+    if (session.signedIn) log({ phase: 'signed-in' });
     // Auto-dismiss alert/confirm/beforeunload dialogs so a journey can't hang.
     if (session.page) {
       session.page.on('dialog', d => d.dismiss().catch(() => {}));

package/server/pdf/template.js

@@ -356,7 +356,7 @@ function methodology() {
   ).join('');
   return `<h2>Methodology</h2>
     <div class="callout">
-      <p><b>What is compared.</b> Profiler reports recorded in Chrome through the DevTools Protocol (tracing, V8 CPU sampling and an in-page React probe). When a side has several runs, each metric is the <b>median</b> of its runs.</p>
+      <p><b>What is compared.</b> Profiler reports recorded in Chrome through the DevTools Protocol (tracing, V8 CPU sampling and an in-page probe for React, Vue and Angular components). When a side has several runs, each metric is the <b>median</b> of its runs.</p>
       <p><b>What counts as a change.</b> A metric is “improved” or “degraded” only when the difference exceeds <b>all three</b> of: its absolute floor, its relative floor (both in the table below) and the <b>run-to-run spread</b> seen on either side. Everything else is “unchanged”. For every metric listed here <b>lower is better</b>.</p>
       <p><b>Overall verdict.</b> Decided only by the <i>key</i> metrics: improved if some improved and none degraded; regressed if some degraded and none improved; mixed if both; otherwise no significant change.</p>
       <p><b>Limits.</b> A single run per side cannot separate a real change from noise: record each side at least three times, on the same page, in the same mode, with the same CPU setting. Interaction recordings are only comparable if the same actions were performed. Dev builds are slower than production: trust direction and ranking more than absolute numbers.</p>
@@ -396,7 +396,7 @@ function detailedBody(cmp) {
     <h2>Highlights</h2>${headlines(cmp)}
     <h2>Comparability</h2>${checksList(cmp, { onlyProblems: false })}
     <h2 class="pagebreak">All metrics</h2>${metricsTable(cmp.metrics, { grouped: true })}
-    <div class="pagebreak"></div>${entitySection('React components', 'components', cmp, { vendor: false })}
+    <div class="pagebreak"></div>${entitySection('Components', 'components', cmp, { vendor: false })}
     <div class="pagebreak"></div>${entitySection('Files', 'files', cmp, { vendor: false })}
     <div class="pagebreak"></div>${entitySection('Functions', 'functions', cmp, { vendor: false })}
     <div class="pagebreak"></div><h2>Problems found</h2>${findingsSection(cmp, { limit: 0 })}

package/server/postinstall.js

@@ -0,0 +1,20 @@
+/**
+ * After `npm install @progen-labs/spectra`: teaches the AI agents this project
+ * or machine uses about Spectra (server/agents.js), so they can run its
+ * commands when asked in plain words. It never fails an install, never runs in
+ * CI, for global installs or for `npx`, and is off with SPECTRA_AGENT_DOCS=0
+ * or `"agentDocs": false` in spectra.config.json. `npx spectra agents` does the
+ * same by hand (for package managers that skip install scripts), and
+ * `npx spectra agents --remove` takes it all back out.
+ */
+try {
+  const { installAgentDocs, postinstallPlan } = await import('./agents.js');
+  const plan = postinstallPlan();
+  if (!plan.skip) {
+    const changed = installAgentDocs({ root: plan.root, targets: plan.targets }).filter(r => r.result === 'created' || r.result === 'updated');
+    if (changed.length)
+      console.error(`spectra: taught your AI agents about Spectra (${changed.map(r => r.file).join(', ')}). Undo: npx spectra agents --remove`);
+  }
+} catch {
+  // an install must never fail because of this
+}

package/server/probe.browser.js

@@ -13,13 +13,11 @@
  */
 (function () {
   if (window.__PERF_PROBE__) return;
-  // Runtime hint injected by the profiler: { framework, bundler, isSSR }
+  // What the project's package.json suggests: { framework, bundler, isSSR }. Only
+  // a hint: the page itself decides (every adapter below waits for its own
+  // framework to show up), so an Angular app is profiled as Angular even when
+  // Spectra runs from another folder, a monorepo root or an editor.
   var SPECTRA_FRAMEWORK = typeof window.__SPECTRA_FRAMEWORK__ !== 'undefined' ? window.__SPECTRA_FRAMEWORK__ : null;
-  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;
@@ -482,11 +480,77 @@
     ];
   }
 
+  // The box an element occupies, clipped to the viewport. A component host that
+  // is an inline wrapper (Angular's <app-x>, Vue fragments) can have no box of
+  // its own, so it falls back to the union of its children's boxes.
+  function elementRect(el, vw, vh, depth) {
+    var left = Infinity;
+    var top = Infinity;
+    var right = -Infinity;
+    var bottom = -Infinity;
+    var r = el.getBoundingClientRect();
+    if (r.width > 0 && r.height > 0) {
+      left = r.left;
+      top = r.top;
+      right = r.right;
+      bottom = r.bottom;
+    } else if ((depth || 0) < 3) {
+      for (var c = el.firstElementChild; c; c = c.nextElementSibling) {
+        var cr = elementRect(c, Infinity, Infinity, (depth || 0) + 1);
+        if (!cr) continue;
+        left = Math.min(left, cr[0]);
+        top = Math.min(top, cr[1]);
+        right = Math.max(right, cr[0] + cr[2]);
+        bottom = Math.max(bottom, cr[1] + cr[3]);
+      }
+    }
+    if (left === Infinity) return null;
+    left = Math.max(0, left);
+    top = Math.max(0, top);
+    right = Math.min(vw, right);
+    bottom = Math.min(vh, bottom);
+    if (vw !== Infinity && (right - left < 16 || bottom - top < 16)) return null;
+    return [Math.round(left), Math.round(top), Math.round(right - left), Math.round(bottom - top)];
+  }
+
+  // Angular (development mode) and Vue: find each component's element in the DOM.
+  // Angular: ng.getComponent(host) is the component an element hosts. Vue 3: an
+  // element's __vueParentComponent is the component that rendered it, and it is
+  // that component's root element when the component's subTree points back at it.
+  function frameworkLayout(byId, vw, vh) {
+    var ng = window.ng;
+    var useNg = probe.ngIds && ng && typeof ng.getComponent === 'function';
+    var useVue = !!probe.vueIds;
+    if (!useNg && !useVue) return;
+    var els = document.querySelectorAll('*');
+    for (var i = 0; i < els.length; i++) {
+      var el = els[i];
+      var id = undefined; // var is function-scoped: reset it for every element
+      if (useNg) {
+        var inst = null;
+        try {
+          inst = ng.getComponent(el);
+        } catch (e) {}
+        if (inst) id = probe.ngIds.get(inst.constructor);
+      }
+      if (id === undefined && useVue) {
+        var vc = el.__vueParentComponent;
+        if (vc && ((vc.subTree && vc.subTree.el === el) || (vc.vnode && vc.vnode.el === el))) id = probe.vueIds.get(vc.type);
+      }
+      if (id === undefined || !probe.stats[id]) continue;
+      var rect = elementRect(el, vw, vh);
+      if (rect) (byId[id] = byId[id] || []).push(rect);
+    }
+  }
+
   // Where every component that rendered during the recording sits in the viewport.
   probe.layout = function () {
     var vw = window.innerWidth;
     var vh = window.innerHeight;
     var byId = {};
+    try {
+      frameworkLayout(byId, vw, vh);
+    } catch (e) {}
     probe.roots.forEach(function (root) {
       var stack = [root.current];
       while (stack.length) {
@@ -586,9 +650,9 @@
   };
 
   window.__PERF_PROBE__ = probe;
-  // Only attempt to hook into React when the runtime hint allows it.
+  // React's hook is ignored by every other framework, so it is always there.
   try {
-    if (WANT_REACT) installHook();
+    installHook();
   } catch (e) {
     // Fail silently: probe should still collect vitals even if hooking fails.
   }
@@ -600,6 +664,7 @@
   // from the SFC compiler (type.__file), so no source-map step is needed.
   function installVueAdapter() {
     var vueIds = new Map();
+    probe.vueIds = vueIds; // for the page map: component type -> stat id
     var nextId = 0;
     var perfStart = {};
 
@@ -718,7 +783,6 @@
       if (prevEmit) try { prevEmit.apply(null, arguments); } catch (e) {}
     };
     window.__VUE_DEVTOOLS_GLOBAL_HOOK__ = hook;
-    probe.frameworkName = 'vue';
   }
 
   // ------------------------------------------------ Angular adapter
@@ -729,6 +793,7 @@
   // like React/Vue. The ng global appears only after bootstrap, so we poll.
   function installAngularAdapter() {
     var ngIds = new Map();
+    probe.ngIds = ngIds; // for the page map: component class -> stat id
     var nextId = 100000; // keep clear of other adapters' id space
     var stack = [];
 
@@ -825,11 +890,12 @@
       return false;
     }
     if (!register()) {
+      // poll for up to 30 s, and stop as soon as another framework shows up
       var tries = 0;
       var iv = setInterval(function () {
         tries++;
-        if (register() || tries > 200) clearInterval(iv); // poll up to ~8s
-      }, 40);
+        if (register() || probe.renderers > 0 || probe.frameworkName === 'vue' || tries > 300) clearInterval(iv);
+      }, 100);
     }
   }
 
@@ -931,11 +997,16 @@
     } catch (e) {}
   }
 
+  // Vue and Angular too, whatever the hint says: each wakes up only for its own app
+  try {
+    installVueAdapter();
+  } catch (e) {}
+  try {
+    installAngularAdapter();
+  } catch (e) {}
   try {
     var fwHint = SPECTRA_FRAMEWORK && SPECTRA_FRAMEWORK.framework;
-    if (fwHint === 'vue') installVueAdapter();
-    else if (fwHint === 'angular') installAngularAdapter();
-    else if (!WANT_REACT) installFrameworkProbes(); // svelte: heuristic for now
+    if (fwHint === 'svelte') installFrameworkProbes(); // svelte: heuristic for now
   } catch (e) {}
   installObservers();
 })();

package/server/project-config.js

@@ -1,22 +1,28 @@
 /**
  * Per-project settings: spectra.config.json in the profiled project's root
- * (or the file passed with --config). Today it holds performance budgets:
+ * (or the file passed with --config). It holds performance budgets and how
+ * to sign in to the app (never the password or other secrets: those come from
+ * the environment, see signin.js):
  *
- *   { "budgets": { "tbtMs": 200, "lcpMs": 2500, "cls": 0.1, "criticalFindings": 0 } }
+ *   {
+ *     "budgets": { "tbtMs": 200, "lcpMs": 2500, "cls": 0.1, "criticalFindings": 0 },
+ *     "signIn": { "method": "form", "url": "http://localhost:3000/login", "username": "demo@example.com" }
+ *   }
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { FRONTEND_ROOT } from './config.js';
 import { validateBudgets } from '../shared/result.js';
+import { validateSignInConfig } from './signin.js';
 
 export const CONFIG_FILE = 'spectra.config.json';
 
-/** @returns {{file: string|null, budgets: object}} — throws a readable Error on bad config */
+/** @returns {{file: string|null, budgets: object, signIn: object|null}} — throws a readable Error on bad config */
 export function loadProjectConfig(explicitFile) {
   const file = explicitFile ? path.resolve(explicitFile) : path.join(FRONTEND_ROOT, CONFIG_FILE);
   if (!fs.existsSync(file)) {
     if (explicitFile) throw new Error(`config file not found: ${file}`);
-    return { file: null, budgets: {} };
+    return { file: null, budgets: {}, signIn: null };
   }
   let raw;
   try {
@@ -26,5 +32,11 @@ export function loadProjectConfig(explicitFile) {
   }
   const checked = validateBudgets(raw?.budgets);
   if (!checked.ok) throw new Error(`${path.basename(file)}: ${checked.error}`);
-  return { file, budgets: checked.budgets };
+  let signIn;
+  try {
+    signIn = validateSignInConfig(raw?.signIn);
+  } catch (err) {
+    throw new Error(`${path.basename(file)}: ${err.message}`);
+  }
+  return { file, budgets: checked.budgets, signIn };
 }

package/server/recorder.js

@@ -19,7 +19,7 @@ import { FRONTEND_ROOT, REPORTS_DIR, SOURCE_ROOTS, FRAMEWORK } from './config.js
 import { SourceIndex } from './analysis/locate.js';
 import { gitInfo } from './git.js';
 import { REPORT_SCHEMA_VERSION } from '../shared/result.js';
-import { buildSignInUrl, looksSignedOut } from './signin.js';
+import { buildSignInUrl, hasLoginForm, looksSignedOut, normalizeSignIn, parsePairs, signInWithForm, waitForManualSignIn } from './signin.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const PROBE_SOURCE = fs.readFileSync(
@@ -73,6 +73,11 @@ export class PerfSession extends EventEmitter {
     this.recording = null;
     this.lastError = '';
     this.lastTrace = null;
+    // the sign-in for this browser: kept in memory only, never saved or reported
+    this.signIn = null;
+    this.signedIn = false;
+    this.prepared = '';
+    this.addHeader = null;
   }
 
   setState(state, extra = {}) {
@@ -90,6 +95,11 @@ export class PerfSession extends EventEmitter {
     signIn,
   }) {
     if (this.browser) await this.disconnect();
+    this.signIn = normalizeSignIn(signIn);
+    this.signedIn = false;
+    this.headless = mode !== 'attach' && headless;
+    if (this.signIn?.method === 'manual' && this.headless)
+      throw new Error('Signing in yourself needs a visible Chrome window: turn off Headless (or run with --headed).');
     this.browser =
       mode === 'attach'
         ? await attachChrome(browserURL || 'http://127.0.0.1:9222')
@@ -108,8 +118,13 @@ export class PerfSession extends EventEmitter {
       pages[0] ||
       (await this.browser.newPage());
     await this.attachPage(page);
-    if (url) await this.navigate(url, signIn);
-    this.setState('idle');
+    this.setState('connecting');
+    try {
+      if (url) await this.navigate(url, signIn);
+    } finally {
+      // connected even when signing in failed: the page stays open to look at and retry
+      this.setState('idle');
+    }
   }
 
   async disconnect() {
@@ -154,6 +169,8 @@ export class PerfSession extends EventEmitter {
     this.page = page;
     this.scripts.clear();
     this.injected = [];
+    this.prepared = '';
+    this.addHeader = null;
     const client = await page.createCDPSession();
     this.client = client;
     client.on('Debugger.scriptParsed', e =>
@@ -217,24 +234,142 @@ export class PerfSession extends EventEmitter {
   }
 
   /**
-   * Opens `url`. If that fails or lands on a login screen (the browser profile
-   * starts signed out) and a sign-in URL template is given, signs in through it
-   * and lands on `url` afterwards.
+   * Opens `url`, signed in. Chrome starts signed out, so with a sign-in (given
+   * here, or kept from connect) it first sets up a browser login prompt, token,
+   * cookies or storage entries, then loads the page; if the page still asks for
+   * a login, or a login page was given, it signs in (form or link) or waits for
+   * you to (manual), and lands on `url` afterwards. Once per browser.
    */
   async navigate(url, signIn) {
     this.requirePage();
+    const given = normalizeSignIn(signIn);
+    // new details (the dashboard's form changed): sign in again with them
+    if (given && JSON.stringify(given) !== JSON.stringify(this.signIn)) {
+      this.signIn = given;
+      this.signedIn = false;
+    }
+    const s = this.signIn;
     const go = target =>
       this.page.goto(target, {
         waitUntil: 'domcontentloaded',
         timeout: 60_000,
       });
+    if (s) await this.prepareSignIn(s, url);
     this.navigation = null;
     await go(url);
-    const signInUrl = buildSignInUrl(signIn, url);
-    if (signInUrl && looksSignedOut(this.navigation, this.page.url())) {
+    if (!s) return;
+
+    const signedOut = async () =>
+      looksSignedOut(this.navigation, this.page.url()) || (await hasLoginForm(this.page));
+    if (this.signedIn) {
+      // a session can expire (or a journey sign out): sent back to the login page, sign in again
+      if (!looksSignedOut(this.navigation, this.page.url())) return;
+      this.signedIn = false;
+    }
+    if (s.method === 'link') {
+      if (await signedOut()) {
+        this.navigation = null;
+        await go(buildSignInUrl(s.url, url));
+      }
+      return;
+    }
+    if (s.method === 'http' || s.method === 'token') {
+      if (await signedOut())
+        throw new Error(`The page still asks for a login after signing in with ${s.method === 'http' ? 'the browser login prompt' : 'the token, cookies or storage entries'}. Check the values.`);
+      this.signedIn = true;
+      return;
+    }
+    // form or manual: when the page asks for it, or straight away when a login page was given
+    if (!s.url && !(await signedOut())) {
+      this.signedIn = true;
+      return;
+    }
+    const loginUrl = s.url ? buildSignInUrl(s.url, url) : '';
+    const was = this.state;
+    this.setState('signing-in', { method: s.method }); // the dashboard says what is going on
+    try {
+      if (s.method === 'manual') {
+        if (loginUrl) await go(loginUrl);
+        await waitForManualSignIn(this.page, { loginUrl, timeoutMs: s.waitMs });
+      } else {
+        try {
+          await signInWithForm(this.page, { ...s, url: loginUrl });
+        } catch (err) {
+          // a login page that shows no form, on an app that is not asking for one: already signed in
+          if (!(loginUrl && /No login form was found/.test(err.message) && !(await signedOut()))) throw err;
+        }
+      }
+    } finally {
+      this.setState(was);
+    }
+    this.signedIn = true;
+    // back to the page to profile, unless the login brought us there
+    const same = (a, b) => {
+      try {
+        const x = new URL(a);
+        const y = new URL(b);
+        return x.origin === y.origin && x.pathname === y.pathname && x.search === y.search;
+      } catch {
+        return a === b;
+      }
+    };
+    if (!same(this.page.url(), url)) {
       this.navigation = null;
-      await go(signInUrl);
+      await go(url);
+    }
+    if (await signedOut())
+      throw new Error(`Signed in, but ${new URL(url).pathname} still shows a login. Check the login page URL and the details.`);
+  }
+
+  /**
+   * What must be in place before the first request: the answer to the
+   * browser's login prompt, or the token's cookies, storage entries and header.
+   * Cookies and storage are scoped to the page's origin, and the header is
+   * added only to requests to that origin, so it never reaches third parties.
+   */
+  async prepareSignIn(s, url) {
+    let origin;
+    try {
+      origin = new URL(url).origin;
+    } catch {
+      return;
+    }
+    const key = `${origin}|${JSON.stringify(s)}`;
+    if (this.prepared === key) return;
+    if (s.method === 'http') await this.page.authenticate({ username: s.username, password: s.password });
+    if (s.method === 'token') {
+      const cookies = parsePairs(s.cookies);
+      if (cookies.length) await this.page.setCookie(...cookies.map(([name, value]) => ({ name, value, url: origin })));
+      const storage = parsePairs(s.storage);
+      if (storage.length)
+        await this.inject(
+          `(() => { if (location.origin !== ${JSON.stringify(origin)}) return; try { ${storage
+            .map(([k, v]) => `localStorage.setItem(${JSON.stringify(k)}, ${JSON.stringify(v)});`)
+            .join(' ')} } catch (e) {} })();`,
+          { now: false },
+        );
+    }
+    // one header handler at a time: drop the last one (another origin or other details)
+    const client = this.client;
+    if (this.addHeader) {
+      client.off('Fetch.requestPaused', this.addHeader);
+      this.addHeader = null;
+      await client.send('Fetch.disable').catch(() => {});
+    }
+    if (s.method === 'token' && s.headerName && s.headerValue) {
+      const name = s.headerName;
+      const value = s.headerValue;
+      this.addHeader = e => {
+        const headers = Object.entries(e.request.headers)
+          .filter(([n]) => n.toLowerCase() !== name.toLowerCase())
+          .map(([n, v]) => ({ name: n, value: v }));
+        headers.push({ name, value });
+        client.send('Fetch.continueRequest', { requestId: e.requestId, headers }).catch(() => {});
+      };
+      client.on('Fetch.requestPaused', this.addHeader);
+      await client.send('Fetch.enable', { patterns: [{ urlPattern: `${origin}/*`, requestStage: 'Request' }] });
     }
+    this.prepared = key;
   }
 
   async reload() {
@@ -270,6 +405,8 @@ export class PerfSession extends EventEmitter {
         cpuThrottle: this.recording.cpuThrottle,
       },
       error: this.lastError,
+      // how this browser signs in, without any of the details
+      signIn: this.signIn && { method: this.signIn.method, signedIn: this.signedIn },
     };
   }
 
@@ -461,19 +598,21 @@ export class PerfSession extends EventEmitter {
   }
 
   /**
-   * What the page looks like right now plus where each React component sits on
-   * it, so the report can point from a slow component to its place on screen.
-   * Best effort: any failure just means the report has no page map.
+   * What the page looks like right now plus where each component sits on it
+   * (React, Vue or Angular), so the report can point from a slow component to
+   * its place on screen. The screenshot is taken for every page, with or
+   * without components to pin. Best effort: a failure means no page map.
    */
   async capturePageView() {
     try {
       const { result } = await this.client.send('Runtime.evaluate', {
         expression:
-          'window.__PERF_PROBE__ && __PERF_PROBE__.layout ? __PERF_PROBE__.layout() : null',
+          'window.__PERF_PROBE__ && __PERF_PROBE__.layout ? __PERF_PROBE__.layout() : ' +
+          '{ width: innerWidth, height: innerHeight, scrollX: Math.round(scrollX), scrollY: Math.round(scrollY), entries: [] }',
         returnByValue: true,
       });
       const layout = result.value;
-      if (!layout?.entries?.length) return null;
+      if (!layout?.width || !layout?.height) return null;
       const shot = await this.client.send('Page.captureScreenshot', {
         format: 'jpeg',
         quality: 72,
@@ -491,7 +630,7 @@ export class PerfSession extends EventEmitter {
     }
   }
 
-  /** Function -> source location for each React component seen, via [[FunctionLocation]]. */
+  /** Function -> source location for each React component seen, via [[FunctionLocation]] (Vue and Angular carry their own). */
   async componentLocations(probe) {
     const out = new Map();
     if (!probe?.components?.length) return out;