shopify-audit 1.0.0

package/bin/shopify-audit.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import { parseArgs } from '../src/cli.js';
+import { runAudit } from '../src/index.js';
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.error) {
+  console.error(`Error: ${args.error}`);
+  console.error('');
+  console.error('Usage: shopify-audit <url> [options]');
+  console.error('');
+  console.error('Options:');
+  console.error('  --mobile              Emulate mobile device (default)');
+  console.error('  --desktop             Emulate desktop device');
+  console.error('  --runs <n>            Number of runs per page (default: 1)');
+  console.error('  --password <pw>       Storefront password');
+  console.error('  --block-analytics     Block known analytics scripts');
+  console.error('  --json <file>         Write JSON report to file');
+  console.error('  --pdp-url <url>       Override product page URL');
+  console.error('  --plp-url <url>       Override collection page URL');
+  console.error('  --fail-on <rules>     Exit 1 if conditions met (comma-separated)');
+  console.error('                        Rules: render-blocking, tbt:<ms>, lcp:<ms>');
+  process.exit(1);
+}
+
+runAudit(args)
+  .then((report) => {
+    if (args.failOn.length > 0) {
+      const failed = checkFailConditions(report, args.failOn);
+      if (failed.length > 0) {
+        console.error('');
+        console.error('  \x1b[31mFail conditions triggered:\x1b[0m');
+        for (const msg of failed) {
+          console.error(`    • ${msg}`);
+        }
+        process.exit(1);
+      }
+    }
+  })
+  .catch((err) => {
+    console.error('Fatal error:', err.message);
+    process.exit(1);
+  });
+
+function checkFailConditions(report, failOn) {
+  const failures = [];
+
+  for (const rule of failOn) {
+    if (rule === 'render-blocking') {
+      for (const page of report.pages) {
+        const count = page.scripts.filter((s) => s.renderBlocking).length;
+        if (count > 0) {
+          failures.push(`${page.pageType}: ${count} render-blocking script(s)`);
+        }
+      }
+    } else if (rule.startsWith('tbt:')) {
+      const threshold = parseInt(rule.split(':')[1], 10);
+      if (isNaN(threshold)) continue;
+      for (const page of report.pages) {
+        if (page.metrics.tbt > threshold) {
+          failures.push(`${page.pageType}: TBT ${page.metrics.tbt}ms > ${threshold}ms`);
+        }
+      }
+    } else if (rule.startsWith('lcp:')) {
+      const threshold = parseInt(rule.split(':')[1], 10);
+      if (isNaN(threshold)) continue;
+      for (const page of report.pages) {
+        if (page.metrics.lcp > threshold) {
+          failures.push(`${page.pageType}: LCP ${page.metrics.lcp}ms > ${threshold}ms`);
+        }
+      }
+    }
+  }
+
+  return failures;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "shopify-audit",
+  "version": "1.0.0",
+  "description": "Runtime performance audit tool for Shopify storefronts",
+  "bin": {
+    "shopify-audit": "./bin/shopify-audit.js"
+  },
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node bin/shopify-audit.js",
+    "postinstall": "npx playwright install chromium"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "shopify",
+    "performance",
+    "audit",
+    "web-vitals",
+    "lcp",
+    "tbt",
+    "playwright"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "playwright": "^1.48.0"
+  }
+}

package/src/analyzers/lcp.js

@@ -0,0 +1,32 @@
+export function analyzeLcp(paintData, networkRequests) {
+  const result = {
+    lcpElement: paintData.lcpElement,
+    lcpTime: paintData.lcp,
+    lcpResource: null,
+    longTasksBeforeLcp: 0,
+  };
+
+  if (!paintData.lcpElement) return result;
+
+  const lcpSrc = paintData.lcpElement.src;
+  if (lcpSrc) {
+    const matchingRequest = networkRequests.find((r) =>
+      r.url === lcpSrc || r.url.includes(lcpSrc),
+    );
+    if (matchingRequest) {
+      result.lcpResource = {
+        url: matchingRequest.url,
+        size: matchingRequest.size,
+        duration: matchingRequest.duration,
+      };
+    }
+  }
+
+  if (paintData.lcp != null) {
+    result.longTasksBeforeLcp = paintData.longTasks
+      .filter((t) => t.startTime < paintData.lcp)
+      .reduce((sum, t) => sum + t.duration, 0);
+  }
+
+  return result;
+}

package/src/analyzers/main-thread.js

@@ -0,0 +1,11 @@
+/**
+ * Classifies page-level main-thread blocking severity based on total long task duration:
+ * - >= 200ms → HIGH
+ * - 50–199ms → MED
+ * - < 50ms  → LOW
+ */
+export function classifyBlockingSeverity(totalMs) {
+  if (totalMs >= 200) return 'HIGH';
+  if (totalMs >= 50) return 'MED';
+  return 'LOW';
+}

package/src/analyzers/render-blocking.js

@@ -0,0 +1,44 @@
+/**
+ * A script is render-blocking if:
+ * - Located in <head>
+ * - NOT async
+ * - NOT defer
+ * - NOT type="module"
+ */
+export function analyzeRenderBlocking(scripts) {
+  return scripts.map((script) => {
+    if (script.inline) {
+      return { ...script, renderBlocking: false };
+    }
+
+    const isRenderBlocking =
+      script.location === 'head' &&
+      !script.async &&
+      !script.defer &&
+      script.type !== 'module';
+
+    return {
+      ...script,
+      renderBlocking: isRenderBlocking,
+    };
+  });
+}
+
+/**
+ * A stylesheet is render-blocking if:
+ * - Located in <head>
+ * - media is "all" or empty (not print-only, not conditional)
+ */
+export function analyzeRenderBlockingStylesheets(stylesheets) {
+  return stylesheets.map((sheet) => {
+    const nonBlockingMedia = ['print', 'not all'];
+    const isRenderBlocking =
+      sheet.location === 'head' &&
+      !nonBlockingMedia.includes(sheet.media);
+
+    return {
+      ...sheet,
+      renderBlocking: isRenderBlocking,
+    };
+  });
+}

package/src/analyzers/third-party.js

@@ -0,0 +1,74 @@
+const SHOPIFY_CDN_PATTERNS = [
+  'cdn.shopify.com',
+  'cdn.shopifycdn.net',
+  'monorail-edge.shopifysvc.com',
+  'shopify.com',
+];
+
+export function analyzeThirdParty(networkRequests, storefrontDomain, longTasks) {
+  const domainMap = new Map();
+
+  for (const req of networkRequests) {
+    let hostname;
+    try {
+      hostname = new URL(req.url).hostname;
+    } catch {
+      continue;
+    }
+
+    if (isFirstParty(hostname, storefrontDomain)) continue;
+
+    if (!domainMap.has(hostname)) {
+      domainMap.set(hostname, {
+        domain: hostname,
+        requestCount: 0,
+        scriptBytes: 0,
+        requests: [],
+      });
+    }
+
+    const entry = domainMap.get(hostname);
+    entry.requestCount++;
+    if (req.resourceType === 'script' && req.size) {
+      entry.scriptBytes += req.size;
+    }
+    entry.requests.push(req);
+  }
+
+  const totalLongTaskMs = longTasks.reduce((sum, t) => sum + t.duration, 0);
+  const thirdPartyDomains = domainMap.size;
+
+  const results = [];
+  for (const entry of domainMap.values()) {
+    const scriptRequestCount = entry.requests.filter(
+      (r) => r.resourceType === 'script',
+    ).length;
+
+    const proportionalLongTaskMs =
+      thirdPartyDomains > 0 && scriptRequestCount > 0
+        ? Math.round(
+            (scriptRequestCount / networkRequests.filter((r) => r.resourceType === 'script').length) *
+              totalLongTaskMs,
+          )
+        : 0;
+
+    results.push({
+      domain: entry.domain,
+      requestCount: entry.requestCount,
+      scriptBytes: entry.scriptBytes,
+      longTaskMs: proportionalLongTaskMs,
+    });
+  }
+
+  results.sort((a, b) => b.scriptBytes - a.scriptBytes);
+  return results;
+}
+
+function isFirstParty(hostname, storefrontDomain) {
+  if (hostname === storefrontDomain) return true;
+  if (hostname.endsWith(`.${storefrontDomain}`)) return true;
+
+  return SHOPIFY_CDN_PATTERNS.some(
+    (pattern) => hostname === pattern || hostname.endsWith(`.${pattern}`),
+  );
+}

package/src/browser.js

@@ -0,0 +1,77 @@
+import { chromium, devices } from 'playwright';
+
+const ANALYTICS_DOMAINS = [
+  'google-analytics.com',
+  'googletagmanager.com',
+  'analytics.google.com',
+  'facebook.net',
+  'connect.facebook.net',
+  'hotjar.com',
+  'clarity.ms',
+  'segment.com',
+  'mixpanel.com',
+  'amplitude.com',
+  'heap.io',
+  'fullstory.com',
+  'optimizely.com',
+  'crazyegg.com',
+  'mouseflow.com',
+  'lucky-orange.com',
+  'tiktok.com',
+  'snap.licdn.com',
+  'bat.bing.com',
+  'doubleclick.net',
+  'googlesyndication.com',
+  'googleadservices.com',
+];
+
+export async function launchBrowser(config) {
+  const browser = await chromium.launch({ headless: true });
+
+  const contextOptions = config.device === 'mobile'
+    ? { ...devices['iPhone 12'] }
+    : {
+        viewport: { width: 1440, height: 900 },
+        userAgent:
+          'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      };
+
+  const context = await browser.newContext(contextOptions);
+
+  return { browser, context };
+}
+
+export async function setupPage(context, config) {
+  const page = await context.newPage();
+
+  if (config.blockAnalytics) {
+    await page.route('**/*', (route) => {
+      const url = route.request().url();
+      const shouldBlock = ANALYTICS_DOMAINS.some((domain) => url.includes(domain));
+      if (shouldBlock) {
+        return route.abort();
+      }
+      return route.continue();
+    });
+  }
+
+  return page;
+}
+
+export async function handleStorefrontPassword(page, config) {
+  if (!config.password) return;
+
+  try {
+    const passwordInput = await page.$('input[type="password"]', { timeout: 3000 });
+    if (passwordInput) {
+      await passwordInput.fill(config.password);
+      const submitButton = await page.$('button[type="submit"]');
+      if (submitButton) {
+        await submitButton.click();
+        await page.waitForLoadState('networkidle', { timeout: 10000 });
+      }
+    }
+  } catch {
+    // No password page — continue
+  }
+}

package/src/cli.js

@@ -0,0 +1,71 @@
+export function parseArgs(argv) {
+  const config = {
+    url: null,
+    device: 'mobile',
+    runs: 1,
+    password: null,
+    blockAnalytics: false,
+    jsonOutput: null,
+    pdpUrl: null,
+    plpUrl: null,
+    failOn: [],
+  };
+
+  const args = [...argv];
+
+  while (args.length > 0) {
+    const arg = args.shift();
+
+    if (arg === '--help' || arg === '-h') {
+      return { error: 'Show usage' };
+    } else if (arg === '--mobile') {
+      config.device = 'mobile';
+    } else if (arg === '--desktop') {
+      config.device = 'desktop';
+    } else if (arg === '--runs') {
+      const val = args.shift();
+      const n = parseInt(val, 10);
+      if (isNaN(n) || n < 1) {
+        return { error: `Invalid --runs value: ${val}` };
+      }
+      config.runs = n;
+    } else if (arg === '--password') {
+      config.password = args.shift();
+      if (!config.password) return { error: '--password requires a value' };
+    } else if (arg === '--block-analytics') {
+      config.blockAnalytics = true;
+    } else if (arg === '--json') {
+      config.jsonOutput = args.shift();
+      if (!config.jsonOutput) return { error: '--json requires a file path' };
+    } else if (arg === '--pdp-url') {
+      config.pdpUrl = args.shift();
+      if (!config.pdpUrl) return { error: '--pdp-url requires a URL' };
+    } else if (arg === '--plp-url') {
+      config.plpUrl = args.shift();
+      if (!config.plpUrl) return { error: '--plp-url requires a URL' };
+    } else if (arg === '--fail-on') {
+      const val = args.shift();
+      if (!val) return { error: '--fail-on requires a value (e.g. render-blocking, tbt:200, lcp:2500)' };
+      config.failOn.push(...val.split(',').map((s) => s.trim()));
+    } else if (arg.startsWith('--')) {
+      return { error: `Unknown flag: ${arg}` };
+    } else if (!config.url) {
+      config.url = normalizeUrl(arg);
+    } else {
+      return { error: `Unexpected argument: ${arg}` };
+    }
+  }
+
+  if (!config.url) {
+    return { error: 'URL is required' };
+  }
+
+  return config;
+}
+
+function normalizeUrl(raw) {
+  if (!/^https?:\/\//i.test(raw)) {
+    return `https://${raw}`;
+  }
+  return raw;
+}

package/src/collectors/injected-scripts.js

@@ -0,0 +1,55 @@
+/**
+ * MutationObserver that tracks dynamically injected script elements
+ * with timestamps for before/after LCP classification.
+ *
+ * Uses document as the observe target since document.documentElement
+ * may not exist when addInitScript runs.
+ */
+export function buildMutationObserverScript() {
+  return `
+    window.__auditInjectedScripts = [];
+
+    const __auditMutationCb = (mutations) => {
+      for (const mutation of mutations) {
+        for (const node of mutation.addedNodes) {
+          if (node.nodeName === 'SCRIPT') {
+            window.__auditInjectedScripts.push({
+              src: node.src || null,
+              timestamp: Math.round(performance.now()),
+              async: node.async || false,
+              defer: node.defer || false,
+              type: node.type || null,
+              parentTag: node.parentNode ? node.parentNode.tagName.toLowerCase() : null,
+            });
+          }
+        }
+      }
+    };
+
+    const __auditObserver = new MutationObserver(__auditMutationCb);
+
+    if (document.documentElement) {
+      __auditObserver.observe(document.documentElement, {
+        childList: true,
+        subtree: true,
+      });
+    } else {
+      __auditObserver.observe(document, {
+        childList: true,
+        subtree: true,
+      });
+      document.addEventListener('DOMContentLoaded', () => {
+        try {
+          __auditObserver.observe(document.documentElement, {
+            childList: true,
+            subtree: true,
+          });
+        } catch (e) {}
+      }, { once: true });
+    }
+  `;
+}
+
+export async function collectInjectedScripts(page) {
+  return page.evaluate(() => window.__auditInjectedScripts || []);
+}

package/src/collectors/navigation.js

@@ -0,0 +1,13 @@
+export async function collectNavigationTiming(page) {
+  return page.evaluate(() => {
+    const entry = performance.getEntriesByType('navigation')[0];
+    if (!entry) return null;
+
+    return {
+      domContentLoadedEventEnd: Math.round(entry.domContentLoadedEventEnd),
+      loadEventEnd: Math.round(entry.loadEventEnd),
+      responseStart: Math.round(entry.responseStart),
+      responseEnd: Math.round(entry.responseEnd),
+    };
+  });
+}

package/src/collectors/network.js

@@ -0,0 +1,59 @@
+export function createNetworkCollector(page) {
+  const requests = [];
+  const startTimes = new Map();
+
+  page.on('request', (request) => {
+    startTimes.set(request.url(), Date.now());
+  });
+
+  page.on('response', async (response) => {
+    const request = response.request();
+    const url = request.url();
+    const resourceType = request.resourceType();
+    const startTime = startTimes.get(url) || null;
+    const endTime = Date.now();
+
+    let size = null;
+    try {
+      const headers = response.headers();
+      if (headers['content-length']) {
+        size = parseInt(headers['content-length'], 10);
+      }
+    } catch {
+      // size unknown
+    }
+
+    requests.push({
+      url,
+      resourceType,
+      size,
+      startTime,
+      endTime,
+      duration: startTime ? endTime - startTime : null,
+      status: response.status(),
+    });
+  });
+
+  page.on('requestfailed', (request) => {
+    startTimes.delete(request.url());
+  });
+
+  return {
+    getRequests() {
+      return [...requests];
+    },
+    getScriptRequests() {
+      return requests.filter((r) => r.resourceType === 'script');
+    },
+    getStylesheetRequests() {
+      return requests.filter((r) => r.resourceType === 'stylesheet');
+    },
+    getFontRequests() {
+      return requests.filter((r) => r.resourceType === 'font');
+    },
+    clear() {
+      requests.length = 0;
+      startTimes.clear();
+    },
+  };
+}

package/src/collectors/paint-and-tasks.js

@@ -0,0 +1,106 @@
+/**
+ * Injects PerformanceObserver scripts at document start to capture
+ * FCP, LCP, long tasks, and layout shifts before any page content loads.
+ */
+export function buildObserverScript() {
+  return `
+    window.__auditData = {
+      fcp: null,
+      lcp: null,
+      lcpElement: null,
+      longTasks: [],
+      layoutShifts: [],
+    };
+
+    try {
+      new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          if (entry.name === 'first-contentful-paint') {
+            window.__auditData.fcp = Math.round(entry.startTime);
+          }
+        }
+      }).observe({ type: 'paint', buffered: true });
+    } catch (e) {}
+
+    try {
+      new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          window.__auditData.lcp = Math.round(entry.startTime);
+          const el = entry.element;
+          if (el) {
+            window.__auditData.lcpElement = {
+              tag: el.tagName.toLowerCase(),
+              id: el.id || null,
+              classes: el.className || null,
+              src: el.src || el.currentSrc || null,
+              text: el.tagName === 'IMG' ? null : (el.textContent || '').slice(0, 100),
+            };
+          }
+        }
+      }).observe({ type: 'largest-contentful-paint', buffered: true });
+    } catch (e) {}
+
+    try {
+      new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          window.__auditData.longTasks.push({
+            startTime: Math.round(entry.startTime),
+            duration: Math.round(entry.duration),
+          });
+        }
+      }).observe({ type: 'longtask', buffered: true });
+    } catch (e) {}
+
+    try {
+      new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          if (!entry.hadRecentInput) {
+            window.__auditData.layoutShifts.push({
+              startTime: Math.round(entry.startTime),
+              value: entry.value,
+            });
+          }
+        }
+      }).observe({ type: 'layout-shift', buffered: true });
+    } catch (e) {}
+  `;
+}
+
+export async function collectPaintAndTasks(page) {
+  return page.evaluate(() => {
+    const data = window.__auditData || {};
+
+    const longTasks = data.longTasks || [];
+    const lcp = data.lcp;
+
+    const tbt = longTasks.reduce(
+      (sum, t) => sum + Math.max(0, t.duration - 50),
+      0,
+    );
+    const longtaskTotal = longTasks.reduce((sum, t) => sum + t.duration, 0);
+
+    const tasksBeforeLcp = lcp != null
+      ? longTasks.filter((t) => t.startTime < lcp)
+      : longTasks;
+    const tbtBeforeLcp = tasksBeforeLcp.reduce(
+      (sum, t) => sum + Math.max(0, t.duration - 50),
+      0,
+    );
+    const longtaskTotalBeforeLcp = tasksBeforeLcp.reduce(
+      (sum, t) => sum + t.duration,
+      0,
+    );
+
+    return {
+      fcp: data.fcp,
+      lcp,
+      lcpElement: data.lcpElement || null,
+      longTasks,
+      tbt: Math.round(tbt),
+      tbtBeforeLcp: Math.round(tbtBeforeLcp),
+      longtaskTotal: Math.round(longtaskTotal),
+      longtaskTotalBeforeLcp: Math.round(longtaskTotalBeforeLcp),
+      layoutShifts: data.layoutShifts || [],
+    };
+  });
+}

package/src/collectors/scripts.js

@@ -0,0 +1,22 @@
+export async function collectScripts(page) {
+  return page.evaluate(() => {
+    const scripts = Array.from(document.querySelectorAll('script'));
+    const injectedSrcs = new Set(window.__auditInjectedScripts || []);
+
+    return scripts.map((script) => {
+      const src = script.src || null;
+      const isInHead = script.closest('head') !== null;
+
+      return {
+        src,
+        inline: !src,
+        async: script.async,
+        defer: script.defer,
+        type: script.type || null,
+        location: isInHead ? 'head' : 'body',
+        isInjected: injectedSrcs.has(src) ||
+          (script.dataset && script.dataset.auditInjected === 'true'),
+      };
+    });
+  });
+}

package/src/collectors/stylesheets.js

@@ -0,0 +1,13 @@
+export async function collectStylesheets(page) {
+  return page.evaluate(() => {
+    const links = Array.from(document.querySelectorAll('link[rel="stylesheet"]'));
+    return links.map((link) => {
+      const isInHead = link.closest('head') !== null;
+      return {
+        href: link.href || null,
+        location: isInHead ? 'head' : 'body',
+        media: link.media || 'all',
+      };
+    });
+  });
+}

package/src/discovery.js

@@ -0,0 +1,71 @@
+export async function discoverPages(page, baseUrl, config) {
+  const pages = [
+    { url: baseUrl, pageType: 'home' },
+    { url: new URL('/cart', baseUrl).href, pageType: 'cart' },
+  ];
+
+  if (config.pdpUrl) {
+    const pdp = config.pdpUrl.startsWith('http')
+      ? config.pdpUrl
+      : new URL(config.pdpUrl, baseUrl).href;
+    pages.push({ url: pdp, pageType: 'pdp' });
+  }
+
+  if (config.plpUrl) {
+    const plp = config.plpUrl.startsWith('http')
+      ? config.plpUrl
+      : new URL(config.plpUrl, baseUrl).href;
+    pages.push({ url: plp, pageType: 'plp' });
+  }
+
+  if (!config.pdpUrl || !config.plpUrl) {
+    const discovered = await extractLinksFromPage(page, baseUrl);
+
+    if (!config.pdpUrl && discovered.pdp) {
+      pages.push({ url: discovered.pdp, pageType: 'pdp' });
+    }
+
+    if (!config.plpUrl && discovered.plp) {
+      pages.push({ url: discovered.plp, pageType: 'plp' });
+    }
+  }
+
+  return pages;
+}
+
+async function extractLinksFromPage(page, baseUrl) {
+  const origin = new URL(baseUrl).origin;
+
+  const links = await page.evaluate((origin) => {
+    const anchors = Array.from(document.querySelectorAll('a[href]'));
+    return anchors.map((a) => {
+      try {
+        return new URL(a.getAttribute('href'), origin).href;
+      } catch {
+        return null;
+      }
+    }).filter(Boolean);
+  }, origin);
+
+  let pdp = null;
+  let plp = null;
+
+  for (const link of links) {
+    try {
+      const url = new URL(link);
+      if (url.origin !== origin) continue;
+
+      if (!pdp && /^\/products\/[^/]+$/i.test(url.pathname)) {
+        pdp = link;
+      }
+      if (!plp && /^\/collections\/[^/]+$/i.test(url.pathname)) {
+        plp = link;
+      }
+      if (pdp && plp) break;
+    } catch {
+      continue;
+    }
+  }
+
+  return { pdp, plp };
+}

package/src/findings.js

@@ -0,0 +1,105 @@
+export function generateFindings(pageResult) {
+  const findings = [];
+  const { scripts, stylesheets, metrics, lcpAnalysis, thirdParty, injectedScripts } = pageResult;
+
+  const renderBlockingScripts = scripts.filter((s) => s.renderBlocking);
+  if (renderBlockingScripts.length > 0) {
+    findings.push({
+      type: 'render-blocking-scripts',
+      severity: 'HIGH',
+      message: `${renderBlockingScripts.length} render-blocking script(s) found in <head>`,
+      details: renderBlockingScripts.map((s) => s.src).filter(Boolean),
+    });
+  }
+
+  const renderBlockingSheets = stylesheets.filter((s) => s.renderBlocking);
+  if (renderBlockingSheets.length > 0) {
+    findings.push({
+      type: 'render-blocking-stylesheets',
+      severity: 'MED',
+      message: `${renderBlockingSheets.length} render-blocking stylesheet(s) in <head>`,
+      details: renderBlockingSheets.map((s) => s.href).filter(Boolean),
+    });
+  }
+
+  if (metrics.tbtBeforeLcp >= 200) {
+    findings.push({
+      type: 'high-tbt-before-lcp',
+      severity: 'HIGH',
+      message: `TBT before LCP is ${metrics.tbtBeforeLcp}ms (threshold: 200ms)`,
+    });
+  } else if (metrics.tbt >= 200) {
+    findings.push({
+      type: 'high-tbt',
+      severity: 'HIGH',
+      message: `Total Blocking Time is ${metrics.tbt}ms (threshold: 200ms)`,
+    });
+  } else if (metrics.tbt >= 50) {
+    findings.push({
+      type: 'moderate-tbt',
+      severity: 'MED',
+      message: `Total Blocking Time is ${metrics.tbt}ms (threshold: 50ms)`,
+    });
+  }
+
+  if (metrics.lcp > 2500) {
+    findings.push({
+      type: 'slow-lcp',
+      severity: 'HIGH',
+      message: `LCP is ${metrics.lcp}ms (threshold: 2500ms)`,
+    });
+  } else if (metrics.lcp > 1800) {
+    findings.push({
+      type: 'moderate-lcp',
+      severity: 'MED',
+      message: `LCP is ${metrics.lcp}ms (threshold: 1800ms)`,
+    });
+  }
+
+  if (lcpAnalysis.longTasksBeforeLcp > 100) {
+    findings.push({
+      type: 'long-tasks-before-lcp',
+      severity: 'HIGH',
+      message: `${lcpAnalysis.longTasksBeforeLcp}ms of long tasks occurred before LCP`,
+    });
+  }
+
+  const beforeLcp = injectedScripts.beforeLcp || [];
+  const afterLcp = injectedScripts.afterLcp || [];
+  const allInjected = injectedScripts.all || [];
+
+  if (beforeLcp.length > 0) {
+    findings.push({
+      type: 'injected-scripts-before-lcp',
+      severity: 'HIGH',
+      message: `${beforeLcp.length} script(s) injected before LCP`,
+      details: beforeLcp.filter((s) => s.src).map((s) => s.src),
+    });
+  }
+
+  if (allInjected.length > 0 && beforeLcp.length === 0) {
+    findings.push({
+      type: 'injected-scripts',
+      severity: 'MED',
+      message: `${allInjected.length} dynamically injected script(s) detected (all after LCP)`,
+      details: allInjected.filter((s) => s.src).map((s) => s.src).slice(0, 10),
+    });
+  }
+
+  const heavyThirdParties = thirdParty.filter((tp) => tp.scriptBytes > 50000);
+  for (const tp of heavyThirdParties) {
+    findings.push({
+      type: 'heavy-third-party',
+      severity: 'MED',
+      message: `${tp.domain}: ${formatBytes(tp.scriptBytes)} of script loaded (${tp.requestCount} requests)`,
+    });
+  }
+
+  return findings;
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/index.js

@@ -0,0 +1,196 @@
+import { launchBrowser, setupPage, handleStorefrontPassword } from './browser.js';
+import { discoverPages } from './discovery.js';
+import { collectNavigationTiming } from './collectors/navigation.js';
+import { buildObserverScript, collectPaintAndTasks } from './collectors/paint-and-tasks.js';
+import { buildMutationObserverScript, collectInjectedScripts } from './collectors/injected-scripts.js';
+import { collectScripts } from './collectors/scripts.js';
+import { collectStylesheets } from './collectors/stylesheets.js';
+import { createNetworkCollector } from './collectors/network.js';
+import { analyzeRenderBlocking, analyzeRenderBlockingStylesheets } from './analyzers/render-blocking.js';
+import { analyzeLcp } from './analyzers/lcp.js';
+import { analyzeThirdParty } from './analyzers/third-party.js';
+import { generateFindings } from './findings.js';
+import { printReport, writeJsonReport } from './reporter.js';
+
+export async function runAudit(config) {
+  const startTime = Date.now();
+  console.log(`\n  Starting Shopify audit for ${config.url}`);
+  console.log(`  Device: ${config.device} | Runs: ${config.runs}`);
+
+  const { browser, context } = await launchBrowser(config);
+  const storefrontDomain = new URL(config.url).hostname;
+
+  try {
+    const initScripts =
+      buildObserverScript() + '\n' + buildMutationObserverScript();
+    await context.addInitScript({ content: initScripts });
+
+    console.log('\n  Discovering pages...');
+    const discoveryPage = await setupPage(context, config);
+    await navigateWithRetry(discoveryPage, config.url, config);
+    const pagesToTest = await discoverPages(discoveryPage, config.url, config);
+    await discoveryPage.close();
+
+    console.log(`  Found ${pagesToTest.length} pages to test:`);
+    for (const p of pagesToTest) {
+      console.log(`    • ${p.pageType}: ${p.url}`);
+    }
+
+    const report = {
+      runMeta: {
+        timestamp: new Date().toISOString(),
+        device: config.device,
+        url: config.url,
+        runs: config.runs,
+      },
+      pages: [],
+    };
+
+    for (const pageInfo of pagesToTest) {
+      console.log(`\n  Testing ${pageInfo.pageType.toUpperCase()}: ${pageInfo.url}`);
+
+      const pageResults = [];
+      for (let run = 0; run < config.runs; run++) {
+        if (config.runs > 1) {
+          console.log(`    Run ${run + 1}/${config.runs}...`);
+        }
+
+        const result = await auditSinglePage(context, pageInfo, config, storefrontDomain);
+        pageResults.push(result);
+      }
+
+      const averaged = config.runs > 1 ? averageRuns(pageResults) : pageResults[0];
+      report.pages.push(averaged);
+    }
+
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    console.log(`\n  Audit complete in ${elapsed}s`);
+
+    printReport(report);
+
+    if (config.jsonOutput) {
+      await writeJsonReport(report, config.jsonOutput);
+    }
+
+    return report;
+  } finally {
+    await browser.close();
+  }
+}
+
+async function auditSinglePage(context, pageInfo, config, storefrontDomain) {
+  const page = await setupPage(context, config);
+  const networkCollector = createNetworkCollector(page);
+
+  try {
+    await navigateWithRetry(page, pageInfo.url, config);
+
+    await page.waitForLoadState('load', { timeout: 30000 });
+    await page.waitForTimeout(2000);
+
+    const [navTiming, paintData, scripts, stylesheets, injectedScripts] = await Promise.all([
+      collectNavigationTiming(page),
+      collectPaintAndTasks(page),
+      collectScripts(page),
+      collectStylesheets(page),
+      collectInjectedScripts(page),
+    ]);
+
+    const networkRequests = networkCollector.getRequests();
+
+    const analyzedScripts = analyzeRenderBlocking(scripts);
+    const analyzedStylesheets = analyzeRenderBlockingStylesheets(stylesheets);
+    const lcpAnalysis = analyzeLcp(paintData, networkRequests);
+    const thirdParty = analyzeThirdParty(
+      networkRequests,
+      storefrontDomain,
+      paintData.longTasks,
+    );
+
+    const lcpTime = paintData.lcp;
+    const injectedBeforeLcp = lcpTime != null
+      ? injectedScripts.filter((s) => s.timestamp <= lcpTime)
+      : injectedScripts;
+    const injectedAfterLcp = lcpTime != null
+      ? injectedScripts.filter((s) => s.timestamp > lcpTime)
+      : [];
+
+    const metrics = {
+      fcp: paintData.fcp,
+      lcp: paintData.lcp,
+      tbt: paintData.tbt,
+      tbtBeforeLcp: paintData.tbtBeforeLcp,
+      longtaskTotal: paintData.longtaskTotal,
+      longtaskTotalBeforeLcp: paintData.longtaskTotalBeforeLcp,
+      dcl: navTiming?.domContentLoadedEventEnd || null,
+      load: navTiming?.loadEventEnd || null,
+    };
+
+    const pageResult = {
+      url: pageInfo.url,
+      pageType: pageInfo.pageType,
+      metrics,
+      longTasks: paintData.longTasks,
+      scripts: analyzedScripts,
+      stylesheets: analyzedStylesheets,
+      injectedScripts: {
+        all: injectedScripts,
+        beforeLcp: injectedBeforeLcp,
+        afterLcp: injectedAfterLcp,
+      },
+      lcpAnalysis,
+      thirdParty,
+      networkSummary: {
+        totalRequests: networkRequests.length,
+        scriptRequests: networkCollector.getScriptRequests().length,
+        stylesheetRequests: networkCollector.getStylesheetRequests().length,
+        fontRequests: networkCollector.getFontRequests().length,
+      },
+      findings: [],
+    };
+
+    pageResult.findings = generateFindings(pageResult);
+
+    return pageResult;
+  } finally {
+    await page.close();
+  }
+}
+
+async function navigateWithRetry(page, url, config, retries = 2) {
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+      await handleStorefrontPassword(page, config);
+      return;
+    } catch (err) {
+      if (attempt === retries) throw err;
+      console.log(`    Retry ${attempt + 1}/${retries} for ${url}...`);
+      await page.waitForTimeout(2000);
+    }
+  }
+}
+
+function averageRuns(runs) {
+  const base = { ...runs[0] };
+  const metricKeys = ['fcp', 'lcp', 'tbt', 'tbtBeforeLcp', 'longtaskTotal', 'longtaskTotalBeforeLcp', 'dcl', 'load'];
+
+  base.metrics = {};
+  for (const key of metricKeys) {
+    const values = runs.map((r) => r.metrics[key]).filter((v) => v != null);
+    base.metrics[key] = values.length > 0
+      ? Math.round(values.reduce((a, b) => a + b, 0) / values.length)
+      : null;
+  }
+
+  const last = runs[runs.length - 1];
+  base.longTasks = last.longTasks;
+  base.scripts = last.scripts;
+  base.stylesheets = last.stylesheets;
+  base.injectedScripts = last.injectedScripts;
+  base.lcpAnalysis = last.lcpAnalysis;
+  base.thirdParty = last.thirdParty;
+  base.findings = last.findings;
+
+  return base;
+}

package/src/reporter.js

@@ -0,0 +1,174 @@
+import { writeFile } from 'fs/promises';
+
+const SEVERITY_COLORS = {
+  HIGH: '\x1b[31m',
+  MED: '\x1b[33m',
+  LOW: '\x1b[32m',
+};
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+
+export function printReport(report) {
+  console.log('');
+  console.log(`${BOLD}═══════════════════════════════════════════════════════════${RESET}`);
+  console.log(`${BOLD}  Shopify Audit Report${RESET}`);
+  console.log(`${BOLD}═══════════════════════════════════════════════════════════${RESET}`);
+  console.log(`  Device: ${report.runMeta.device}`);
+  console.log(`  Time:   ${report.runMeta.timestamp}`);
+  console.log(`  Runs:   ${report.runMeta.runs}`);
+  console.log('');
+
+  for (const page of report.pages) {
+    printPageReport(page);
+  }
+}
+
+function printPageReport(page) {
+  console.log(`${BOLD}───────────────────────────────────────────────────────────${RESET}`);
+  console.log(`${BOLD}  ${page.pageType.toUpperCase()}${RESET} — ${page.url}`);
+  console.log(`${BOLD}───────────────────────────────────────────────────────────${RESET}`);
+  console.log('');
+
+  printMetrics(page.metrics);
+  printLcp(page);
+  printRenderBlockingScripts(page.scripts);
+  printRenderBlockingStylesheets(page.stylesheets);
+  printInjectedScripts(page.injectedScripts, page.metrics.lcp);
+  printThirdParty(page.thirdParty);
+  printFindings(page.findings);
+}
+
+function printMetrics(metrics) {
+  console.log(`  ${BOLD}Core Metrics${RESET}`);
+  console.log(`    FCP:              ${colorMetric(metrics.fcp, 1800, 3000)}ms`);
+  console.log(`    LCP:              ${colorMetric(metrics.lcp, 2500, 4000)}ms`);
+  console.log(`    TBT:              ${colorMetric(metrics.tbt, 200, 600)}ms`);
+  console.log(`    TBT (0→LCP):      ${colorMetric(metrics.tbtBeforeLcp, 200, 600)}ms`);
+  console.log(`    Long Tasks:       ${metrics.longtaskTotal}ms total (${metrics.longtaskTotalBeforeLcp}ms before LCP)`);
+  console.log(`    DCL:              ${metrics.dcl}ms`);
+  console.log(`    Load:             ${metrics.load}ms`);
+  console.log('');
+}
+
+function printLcp(page) {
+  if (!page.lcpAnalysis?.lcpElement) return;
+
+  const el = page.lcpAnalysis.lcpElement;
+  console.log(`  ${BOLD}LCP Element${RESET}`);
+  console.log(`    Tag:     <${el.tag}>`);
+  if (el.id) console.log(`    ID:      #${el.id}`);
+  if (el.classes) console.log(`    Classes: .${el.classes.replace(/\s+/g, '.')}`);
+  if (el.src) console.log(`    Src:     ${truncate(el.src, 80)}`);
+  if (page.lcpAnalysis.lcpResource) {
+    const res = page.lcpAnalysis.lcpResource;
+    console.log(`    Resource: ${formatBytes(res.size)} loaded in ${res.duration}ms`);
+  }
+  console.log(`    Long tasks before LCP: ${page.lcpAnalysis.longTasksBeforeLcp}ms`);
+  console.log('');
+}
+
+function printRenderBlockingScripts(scripts) {
+  const blocking = scripts.filter((s) => s.renderBlocking);
+  if (blocking.length === 0) return;
+
+  console.log(`  ${BOLD}Render-Blocking Scripts${RESET} ${SEVERITY_COLORS.HIGH}[HIGH]${RESET}`);
+  for (const s of blocking) {
+    console.log(`    ${DIM}•${RESET} ${truncate(s.src, 80)}`);
+  }
+  console.log('');
+}
+
+function printRenderBlockingStylesheets(stylesheets) {
+  if (!stylesheets) return;
+  const blocking = stylesheets.filter((s) => s.renderBlocking);
+  if (blocking.length === 0) return;
+
+  console.log(`  ${BOLD}Render-Blocking Stylesheets${RESET} (${blocking.length})`);
+  for (const s of blocking) {
+    console.log(`    ${DIM}•${RESET} ${truncate(s.href, 80)}`);
+  }
+  console.log('');
+}
+
+function printInjectedScripts(injectedScripts, lcpTime) {
+  if (!injectedScripts) return;
+  const { all, beforeLcp, afterLcp } = injectedScripts;
+  if (!all || all.length === 0) return;
+
+  const withSrc = all.filter((s) => s.src);
+  console.log(`  ${BOLD}Dynamically Injected Scripts${RESET} (${all.length} total, ${withSrc.length} external)`);
+
+  if (beforeLcp.length > 0) {
+    console.log(`    ${SEVERITY_COLORS.HIGH}Before LCP (${beforeLcp.length}):${RESET}`);
+    for (const s of beforeLcp.filter((s) => s.src).slice(0, 10)) {
+      console.log(`      ${DIM}•${RESET} ${truncate(s.src, 74)} ${DIM}@${s.timestamp}ms${RESET}`);
+    }
+    const inlineBeforeLcp = beforeLcp.filter((s) => !s.src).length;
+    if (inlineBeforeLcp > 0) {
+      console.log(`      ${DIM}+ ${inlineBeforeLcp} inline script(s)${RESET}`);
+    }
+  }
+
+  if (afterLcp.length > 0) {
+    console.log(`    After LCP (${afterLcp.length}):`);
+    for (const s of afterLcp.filter((s) => s.src).slice(0, 5)) {
+      console.log(`      ${DIM}•${RESET} ${truncate(s.src, 74)} ${DIM}@${s.timestamp}ms${RESET}`);
+    }
+    const remaining = afterLcp.filter((s) => s.src).length - 5;
+    if (remaining > 0) {
+      console.log(`      ${DIM}  ... and ${remaining} more${RESET}`);
+    }
+  }
+  console.log('');
+}
+
+function printThirdParty(thirdParty) {
+  if (!thirdParty || thirdParty.length === 0) return;
+
+  console.log(`  ${BOLD}Third-Party Domains${RESET}`);
+  for (const tp of thirdParty.slice(0, 15)) {
+    const bytes = tp.scriptBytes > 0 ? ` (${formatBytes(tp.scriptBytes)} scripts)` : '';
+    console.log(`    ${DIM}•${RESET} ${tp.domain}: ${tp.requestCount} req${bytes}`);
+  }
+  if (thirdParty.length > 15) {
+    console.log(`    ${DIM}  ... and ${thirdParty.length - 15} more${RESET}`);
+  }
+  console.log('');
+}
+
+function printFindings(findings) {
+  if (!findings || findings.length === 0) return;
+
+  console.log(`  ${BOLD}Findings${RESET}`);
+  for (const f of findings) {
+    const color = SEVERITY_COLORS[f.severity] || '';
+    console.log(`    ${color}[${f.severity}]${RESET} ${f.message}`);
+  }
+  console.log('');
+}
+
+export async function writeJsonReport(report, filepath) {
+  const json = JSON.stringify(report, null, 2);
+  await writeFile(filepath, json, 'utf-8');
+  console.log(`\n  JSON report written to: ${filepath}`);
+}
+
+function colorMetric(value, warningThreshold, errorThreshold) {
+  if (value == null) return `${DIM}N/A${RESET}`;
+  if (value >= errorThreshold) return `${SEVERITY_COLORS.HIGH}${value}${RESET}`;
+  if (value >= warningThreshold) return `${SEVERITY_COLORS.MED}${value}${RESET}`;
+  return `${SEVERITY_COLORS.LOW}${value}${RESET}`;
+}
+
+function truncate(str, maxLen) {
+  if (!str) return '';
+  return str.length > maxLen ? str.slice(0, maxLen - 3) + '...' : str;
+}
+
+function formatBytes(bytes) {
+  if (bytes == null) return 'unknown';
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}