webperf-snippets 0.1.0

package/snippets/Resources/WORKFLOWS.md

@@ -0,0 +1,173 @@
+## Common Workflows
+
+### Network Quality Assessment
+
+When the user asks about network performance, connection quality, or adaptive loading:
+
+1. **Network-Bandwidth-Connection-Quality.js** - Analyze network bandwidth, effective connection type, RTT, downlink, save-data mode
+
+### Adaptive Loading Strategy
+
+When implementing adaptive loading or the user asks "how to optimize for slow connections":
+
+1. **Network-Bandwidth-Connection-Quality.js** - Detect connection quality
+2. Cross-reference with **webperf-loading** skill:
+   - TTFB.js (measure server response on slow connections)
+   - Find-render-blocking-resources.js (identify heavy resources to defer)
+   - Resource-Hints-Validation.js (optimize preconnect for slow networks)
+3. Cross-reference with **webperf-media** skill:
+   - Image-Element-Audit.js (implement responsive images based on connection)
+   - Video-Element-Audit.js (adjust video quality based on connection)
+
+### Save-Data Mode Detection
+
+When the user asks about save-data or data-saving features:
+
+1. **Network-Bandwidth-Connection-Quality.js** - Check if save-data is enabled
+2. If save-data is enabled, recommend:
+   - Reducing image quality
+   - Disabling autoplay videos
+   - Deferring non-critical resources
+   - Using low-res thumbnails
+
+### Mobile/Slow Connection Optimization
+
+When the user asks "optimize for mobile" or "slow connection users":
+
+1. **Network-Bandwidth-Connection-Quality.js** - Assess connection type
+2. Cross-reference with **webperf-loading** skill:
+   - TTFB.js (critical for slow connections)
+   - Find-render-blocking-resources.js (minimize blocking on slow networks)
+   - Critical-CSS-Detection.js (inline critical CSS to reduce RTT)
+   - Prefetch-Resource-Validation.js (avoid excessive prefetch on slow connections)
+
+## Decision Tree
+
+Use this decision tree to automatically run follow-up snippets based on results:
+
+### After Network-Bandwidth-Connection-Quality.js
+
+- **If effectiveType is "slow-2g" or "2g"** → Very slow connection, recommend:
+  1. Run **webperf-loading:Critical-CSS-Detection.js** (inline critical CSS)
+  2. Run **webperf-media:Image-Element-Audit.js** (implement aggressive lazy loading)
+  3. Run **webperf-loading:Prefetch-Resource-Validation.js** (remove prefetch to save bandwidth)
+  4. Run **webperf-core-web-vitals:LCP.js** (LCP is heavily impacted by slow connections)
+  5. Recommend minimal resource strategy
+
+- **If effectiveType is "3g"** → Moderate connection, recommend:
+  1. Run **webperf-loading:Find-render-blocking-resources.js** (minimize blocking)
+  2. Run **webperf-media:Image-Element-Audit.js** (responsive images)
+  3. Run **webperf-loading:Resource-Hints-Validation.js** (optimize preconnect)
+  4. Run **webperf-core-web-vitals:INP.js** (high latency can impact interaction responsiveness)
+  5. Implement adaptive image quality
+
+- **If effectiveType is "4g" or better** → Good connection, recommend:
+  1. Standard optimization practices
+  2. Consider strategic prefetch for navigation
+  3. Higher quality media is acceptable
+
+- **If save-data is enabled** → User explicitly wants to save data, recommend:
+  1. Reduce image quality aggressively
+  2. Disable autoplay videos
+  3. Defer non-critical resources
+  4. Remove prefetch/preload hints
+  5. Show "high quality" toggle option
+
+- **If RTT > 300ms** → High latency, recommend:
+  1. Run **webperf-loading:TTFB.js** (latency impacts TTFB)
+  2. Run **webperf-loading:TTFB-Sub-Parts.js** (break down latency components)
+  3. Run **webperf-loading:Resource-Hints-Validation.js** (preconnect critical for high RTT)
+  4. Run **webperf-loading:Service-Worker-Analysis.js** (caching is critical for high latency)
+  5. Minimize number of origins
+  6. Use HTTP/2 or HTTP/3 for multiplexing
+
+- **If downlink < 1 Mbps** → Very limited bandwidth, recommend:
+  1. Run **webperf-media:Image-Element-Audit.js** (aggressive compression)
+  2. Run **webperf-media:Video-Element-Audit.js** (disable autoplay)
+  3. Run **webperf-loading:Prefetch-Resource-Validation.js** (remove prefetch)
+  4. Implement bandwidth-aware loading
+
+- **If downlink > 10 Mbps** → Good bandwidth, consider:
+  - Higher quality media
+  - Strategic prefetch
+  - Preloading next-page resources
+
+### Adaptive Loading Implementation Guide
+
+Based on Network Information API results, implement these strategies:
+
+**For slow-2g / 2g (< 50 Kbps):** (`effectiveType: "slow-2g"` or `"2g"`)
+- Serve low-res images (quality: 30-40)
+- Disable autoplay videos
+- Remove all prefetch hints
+- Inline all critical CSS
+- Defer all non-critical JavaScript
+- Use system fonts (no webfonts)
+- Aggressive lazy loading (load on scroll + buffer)
+
+**For 3g (50-700 Kbps):** (`effectiveType: "3g"`)
+- Serve medium-res images (quality: 60-70)
+- Disable autoplay videos
+- Limited prefetch (critical only)
+- Inline critical CSS only
+- Defer non-critical JavaScript
+- Preload 1-2 critical fonts
+- Standard lazy loading
+
+**For 4g+ (> 700 Kbps):** (`effectiveType: "4g"`)
+- Serve high-res images (quality: 80-90)
+- Allow autoplay videos (muted)
+- Strategic prefetch for navigation
+- Standard CSS loading and JavaScript loading
+- Preload critical fonts
+- Standard lazy loading
+
+**For save-data mode:** (`navigator.connection.saveData === true`)
+- Override connection type, treat as worse than actual
+- Show "Load high quality" toggle
+- Disable autoplay entirely
+- Minimal images, minimal quality
+- No prefetch, no preload (except critical)
+
+### Performance Budget by Connection Type
+
+Adjust performance budgets based on connection quality:
+
+**slow-2g / 2g:**
+- Total page weight: < 500KB
+- Images: < 200KB total
+- JavaScript: < 100KB total
+- No videos
+
+**3g:**
+- Total page weight: < 1.5MB
+- Images: < 800KB total
+- JavaScript: < 300KB total
+- Videos: < 3MB (only if critical)
+
+**4g+:**
+- Total page weight: < 3MB
+- Images: < 2MB total
+- JavaScript: < 1MB total
+- Videos: < 10MB
+
+### Network Information API Limitations
+
+Be aware of API limitations and fallbacks:
+
+**API not available:**
+- Safari does not support Network Information API
+- Fallback: Use TTFB as proxy for connection quality
+- Fallback: Device detection (mobile = assume slow)
+- Fallback: User preference toggle
+
+**API values are estimates:**
+- effectiveType is based on recent observations
+- Values can change during session
+- Re-check periodically for long sessions
+
+**Privacy considerations:**
+- Some browsers limit precision for privacy
+- Values may be rounded or capped
+- Consider user privacy when making decisions
+

package/src/bin.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { loadSnippet } from "./load-snippet.js";
+import { runSnippets, VIEWPORT_PRESETS } from "./runner.js";
+import { cwvWorkflow } from "./workflows/cwv.js";
+import { auditWorkflow } from "./workflows/audit.js";
+import { nextSteps } from "./decision-tree.js";
+import { reportHuman } from "./reporters/human.js";
+import { reportJson } from "./reporters/json.js";
+
+const WORKFLOWS = {
+  "core-web-vitals": cwvWorkflow,
+  audit: auditWorkflow,
+};
+
+const SNIPPET_ALIASES = {
+  LCP: "CoreWebVitals/LCP",
+  CLS: "CoreWebVitals/CLS",
+  "LCP-Subparts": "CoreWebVitals/LCP-Subparts",
+  fonts: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold",
+  "Fonts-Preloaded-Loaded-and-used-above-the-fold":
+    "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold",
+  // Tier 1 — Loading
+  "render-blocking": "Loading/Find-render-blocking-resources",
+  "Find-render-blocking-resources": "Loading/Find-render-blocking-resources",
+  "resource-hints": "Loading/Resource-Hints-Validation",
+  "Resource-Hints-Validation": "Loading/Resource-Hints-Validation",
+  "preload-scripts": "Loading/Validate-Preload-Async-Defer-Scripts",
+  "Validate-Preload-Async-Defer-Scripts": "Loading/Validate-Preload-Async-Defer-Scripts",
+  "priority-hints": "Loading/Priority-Hints-Audit",
+  "Priority-Hints-Audit": "Loading/Priority-Hints-Audit",
+  "critical-css": "Loading/Critical-CSS-Detection",
+  "Critical-CSS-Detection": "Loading/Critical-CSS-Detection",
+  ttfb: "Loading/TTFB-Sub-Parts",
+  "TTFB-Sub-Parts": "Loading/TTFB-Sub-Parts",
+  "script-parties": "Loading/First-And-Third-Party-Script-Info",
+  "First-And-Third-Party-Script-Info": "Loading/First-And-Third-Party-Script-Info",
+  "script-loading": "Loading/Script-Loading",
+  "Script-Loading": "Loading/Script-Loading",
+  // Tier 2 — Media
+  "lazy-atf": "Loading/Find-Above-The-Fold-Lazy-Loaded-Images",
+  "Find-Above-The-Fold-Lazy-Loaded-Images": "Loading/Find-Above-The-Fold-Lazy-Loaded-Images",
+  "lazy-conflict": "Loading/Find-Images-With-Lazy-and-Fetchpriority",
+  "Find-Images-With-Lazy-and-Fetchpriority": "Loading/Find-Images-With-Lazy-and-Fetchpriority",
+  "eager-below-fold": "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport",
+  "Find-non-Lazy-Loaded-Images-outside-of-the-viewport":
+    "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport",
+};
+
+const USAGE = `webperf-snippets <url> [options]
+
+Run curated WebPerf Snippets headlessly via Playwright.
+
+Options:
+  --workflow <name>     Workflow to run (default: core-web-vitals)
+                        Workflows: core-web-vitals, audit
+  --snippet <name>      Run a single snippet by alias or Category/Name path
+                        Aliases: LCP, CLS, LCP-Subparts, fonts,
+                                 render-blocking, resource-hints, preload-scripts,
+                                 priority-hints, critical-css, ttfb,
+                                 script-parties, script-loading,
+                                 lazy-atf, lazy-conflict, eager-below-fold
+  --json                Output JSON instead of formatted text
+  --viewport <preset>   Viewport preset: mobile (default), tablet, desktop
+  --wait <ms>           Post-load wait before evaluating (default: 3000)
+  --budget-lcp <ms>     Exit 1 if LCP exceeds this value
+  --budget-cls <score>  Exit 1 if CLS exceeds this value
+  --verbose             Show all items, even for passing checks
+  --headed              Show the browser window (debug)
+  -h, --help            Show this help
+
+Examples:
+  npx webperf-snippets https://web.dev
+  npx webperf-snippets https://web.dev --workflow audit
+  npx webperf-snippets https://web.dev --json
+  npx webperf-snippets https://web.dev --snippet LCP-Subparts
+  npx webperf-snippets https://web.dev --snippet render-blocking
+  npx webperf-snippets https://web.dev --snippet fonts
+  npx webperf-snippets https://web.dev --budget-lcp 2500
+`;
+
+function fail(message, code = 2) {
+  process.stderr.write(`${message}\n`);
+  process.exit(code);
+}
+
+function resolveSnippetPath(name) {
+  return SNIPPET_ALIASES[name] ?? name;
+}
+
+function buildItems(values) {
+  if (values.snippet) {
+    const path = resolveSnippetPath(values.snippet);
+    return [{ id: values.snippet, path, source: loadSnippet(path) }];
+  }
+  const workflowName = values.workflow ?? "core-web-vitals";
+  const workflow = WORKFLOWS[workflowName];
+  if (!workflow) fail(`Unknown workflow: ${workflowName}`);
+  return workflow.steps.map((step) => ({
+    id: step.id,
+    path: step.path,
+    source: loadSnippet(step.path),
+  }));
+}
+
+function checkBudgets(results, values) {
+  const violations = [];
+  const lcpBudget = values["budget-lcp"] ? Number(values["budget-lcp"]) : null;
+  const clsBudget = values["budget-cls"] ? Number(values["budget-cls"]) : null;
+
+  for (const r of results) {
+    if (r.status !== "ok") continue;
+    if (r.metric === "LCP" && lcpBudget != null && r.value > lcpBudget) {
+      violations.push(`LCP ${r.value}ms exceeds budget ${lcpBudget}ms`);
+    }
+    if (r.metric === "CLS" && clsBudget != null && r.value > clsBudget) {
+      violations.push(`CLS ${r.value} exceeds budget ${clsBudget}`);
+    }
+  }
+  return violations;
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      options: {
+        workflow: { type: "string" },
+        snippet: { type: "string" },
+        json: { type: "boolean" },
+        wait: { type: "string" },
+        "budget-lcp": { type: "string" },
+        "budget-cls": { type: "string" },
+        viewport: { type: "string" },
+        verbose: { type: "boolean" },
+        headed: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+      },
+      allowPositionals: true,
+    });
+  } catch (err) {
+    fail(err.message);
+  }
+
+  const { values, positionals } = parsed;
+
+  if (values.help) {
+    process.stdout.write(USAGE);
+    return;
+  }
+
+  const url = positionals[0];
+  if (!url) {
+    process.stdout.write(USAGE);
+    process.exit(2);
+  }
+
+  const items = buildItems(values);
+  const waitMs = values.wait ? Number(values.wait) : 3000;
+  const viewportName = values.viewport ?? "mobile";
+  const viewport = VIEWPORT_PRESETS[viewportName];
+  if (!viewport) {
+    fail(`Unknown viewport preset: "${viewportName}". Choose from: ${Object.keys(VIEWPORT_PRESETS).join(", ")}`);
+  }
+
+  const initial = await runSnippets({
+    url,
+    items,
+    waitMs,
+    headless: !values.headed,
+    viewport,
+  });
+
+  // Apply decision tree to spawn follow-up steps.
+  const followUps = nextSteps(initial.results);
+  let followUpRun = { results: [], pageErrors: [] };
+  if (followUps.length > 0) {
+    const followItems = followUps.map((f) => ({
+      id: f.id,
+      path: f.path,
+      source: loadSnippet(f.path),
+      reason: f.reason,
+    }));
+    // v0.1 limitation: follow-ups re-navigate. Acceptable for now; consolidate
+    // into a single page session in v0.2 if perf becomes a problem.
+    followUpRun = await runSnippets({
+      url,
+      items: followItems,
+      waitMs,
+      headless: !values.headed,
+      viewport,
+    });
+    // Carry forward the human-readable reason so reporters can show it.
+    followUpRun.results = followUpRun.results.map((r) => {
+      const f = followUps.find((x) => x.id === r.id);
+      return f ? { ...r, reason: f.reason } : r;
+    });
+  }
+
+  const payload = {
+    url,
+    navMs: initial.navMs,
+    results: [...initial.results, ...followUpRun.results],
+    pageErrors: [...initial.pageErrors, ...(followUpRun.pageErrors ?? [])],
+  };
+
+  const output = values.json ? reportJson(payload) : reportHuman({ ...payload, verbose: values.verbose });
+  process.stdout.write(output + "\n");
+
+  // Exit codes.
+  const violations = checkBudgets(payload.results, values);
+  if (violations.length > 0) {
+    if (!values.json) {
+      for (const v of violations) process.stderr.write(`Budget violation: ${v}\n`);
+    }
+    process.exit(1);
+  }
+
+  const anyError = payload.results.some((r) => r.status === "error");
+  const anyAuditViolation = payload.results.some(
+    (r) => Array.isArray(r.issues) && r.issues.some((i) => i.severity === "error"),
+  );
+  process.exit(anyError || anyAuditViolation ? 1 : 0);
+}
+
+main().catch((err) => {
+  process.stderr.write(`Error: ${err.stack ?? err.message}\n`);
+  process.exit(1);
+});

package/src/decision-tree.js

@@ -0,0 +1,19 @@
+// Declarative follow-ups: if a result matches the predicate, append the step.
+// Mirrors the WORKFLOWS.md decision trees from the snippet catalogue.
+const RULES = [
+  {
+    when: (r) => r.id === "LCP" && r.status === "ok" && r.value > 2500,
+    append: { id: "LCP-Subparts", path: "CoreWebVitals/LCP-Subparts" },
+    reason: "LCP > 2.5s — drilling into sub-parts",
+  },
+];
+
+export function nextSteps(results) {
+  const followUps = [];
+  for (const result of results) {
+    for (const rule of RULES) {
+      if (rule.when(result)) followUps.push({ ...rule.append, reason: rule.reason });
+    }
+  }
+  return followUps;
+}

package/src/load-snippet.js

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(HERE, "..");
+
+// Resolution order: bundled (published package) → workspace root (dev).
+const SNIPPET_DIRS = [
+  join(PKG_ROOT, "snippets"),
+  resolve(PKG_ROOT, "..", "snippets"),
+];
+
+export function loadSnippet(relativePath) {
+  for (const dir of SNIPPET_DIRS) {
+    try {
+      return readFileSync(join(dir, `${relativePath}.js`), "utf8");
+    } catch {
+      // try next directory
+    }
+  }
+  throw new Error(`Snippet not found: ${relativePath}`);
+}

package/src/reporters/human.js

@@ -0,0 +1,179 @@
+import { styleText } from "node:util";
+
+const RATING_ICON = {
+  good: "🟢",
+  "needs-improvement": "🟡",
+  poor: "🔴",
+};
+
+const RATING_STYLE = {
+  good: "green",
+  "needs-improvement": "yellow",
+  poor: "red",
+};
+
+function formatValue(value, unit) {
+  if (unit === "ms") {
+    return value >= 1000 ? `${(value / 1000).toFixed(2)}s` : `${value}ms`;
+  }
+  if (unit === "score") return value.toFixed(4);
+  return String(value);
+}
+
+function paint(rating, text) {
+  return styleText(RATING_STYLE[rating] ?? "white", text);
+}
+
+function pad(text, len) {
+  const visibleLen = text.replace(/\[\d+m/g, "").length;
+  return text + " ".repeat(Math.max(0, len - visibleLen));
+}
+
+const DISPLAY_WARN = new Set(["block", "auto", "unknown"]);
+
+function renderFontsResult(r) {
+  const d = r.details ?? {};
+  const lines = [];
+
+  lines.push(styleText("bold", `  Fonts — preloaded: ${d.preloadedCount ?? 0}  loaded: ${d.loadedCount ?? 0}  used above fold: ${d.usedAboveFoldCount ?? 0}`));
+
+  if (r.items?.length) {
+    lines.push("");
+    lines.push(styleText("dim", "  Loaded fonts:"));
+    lines.push(styleText("dim", `    ${"Family".padEnd(20)} ${"Weight".padEnd(8)} ${"Style".padEnd(10)} Display`));
+    for (const f of r.items) {
+      const displayWarning = DISPLAY_WARN.has(f.display) ? styleText("yellow", ` ⚠ ${f.display}`) : styleText("green", ` ${f.display}`);
+      lines.push(`    ${f.family.padEnd(20)} ${f.weight.padEnd(8)} ${f.style.padEnd(10)}${displayWarning}`);
+    }
+  }
+
+  if (r.usedFonts?.length) {
+    lines.push("");
+    lines.push(styleText("dim", "  Used above fold:"));
+    lines.push(styleText("dim", `    ${"Family".padEnd(20)} ${"Weight".padEnd(8)} ${"Style".padEnd(10)} Elements`));
+    const sorted = [...r.usedFonts].sort((a, b) => b.elements - a.elements);
+    for (const f of sorted) {
+      lines.push(`    ${f.family.padEnd(20)} ${f.weight.padEnd(8)} ${f.style.padEnd(10)} ${f.elements}`);
+    }
+  }
+
+  if (r.issues?.length) {
+    lines.push("");
+    lines.push(styleText("dim", "  Issues:"));
+    for (const issue of r.issues) {
+      const color = issue.severity === "error" ? "red" : "yellow";
+      lines.push(`    ${styleText(color, issue.severity === "error" ? "✗" : "⚠")} ${issue.message}`);
+    }
+  } else {
+    lines.push("");
+    lines.push(`    ${styleText("green", "✓")} Font loading looks optimized`);
+  }
+
+  return lines.join("\n");
+}
+
+function renderAuditResult(r, verbose) {
+  const lines = [];
+  const id = r.id ?? r.script;
+  const errors = (r.issues ?? []).filter((i) => i.severity === "error");
+  const warnings = (r.issues ?? []).filter((i) => i.severity === "warning");
+
+  const icon = errors.length ? "🔴" : warnings.length ? "🟡" : "🟢";
+  const countSuffix = r.count > 0 ? styleText("dim", ` (${r.count})`) : "";
+  lines.push(`  ${icon} ${id}${countSuffix}`);
+
+  if (r.issues?.length) {
+    for (const issue of r.issues) {
+      const color = issue.severity === "error" ? "red" : issue.severity === "warning" ? "yellow" : "blue";
+      const sym = issue.severity === "error" ? "✗" : issue.severity === "warning" ? "⚠" : "ℹ";
+      lines.push(`     ${styleText(color, sym)} ${issue.message}`);
+    }
+  } else {
+    lines.push(`     ${styleText("green", "✓")} No issues`);
+  }
+
+  const isGreen = errors.length === 0 && warnings.length === 0;
+  const MAX_ITEMS = 10;
+  const items = r.items ?? [];
+  if (items.length > 0 && (!isGreen || verbose)) {
+    lines.push("");
+    const shown = items.slice(0, MAX_ITEMS);
+    for (const item of shown) {
+      const name = item.shortName ?? item.resource ?? item.url ?? item.src ?? item.selector ?? item.filename ?? "";
+      const tag = item.type ?? item.tag ?? item.strategy ?? item.media ?? "";
+      const timing = item.responseEndMs != null ? `${item.responseEndMs}ms` : item.durationMs != null ? `${item.durationMs}ms` : "";
+      const cols = [tag, name, timing].filter(Boolean).join("  ");
+      lines.push(`     ${styleText("dim", `· ${cols}`)}`);
+    }
+    if (items.length > MAX_ITEMS) {
+      lines.push(`     ${styleText("dim", `… and ${items.length - MAX_ITEMS} more`)}`);
+    }
+  }
+
+  if (r.reason) {
+    lines.push(`     ${styleText("dim", `↳ ${r.reason}`)}`);
+  }
+
+  return lines.join("\n");
+}
+
+function renderResult(r, verbose) {
+  if (r.status === "error") {
+    return `  ${styleText("red", "✗")} ${pad(r.id, 16)} ${styleText("dim", r.error)}`;
+  }
+
+  if (r.script === "Fonts-Preloaded-Loaded-and-used-above-the-fold") {
+    return renderFontsResult(r);
+  }
+
+  if (Array.isArray(r.issues)) {
+    return renderAuditResult(r, verbose);
+  }
+
+  const icon = RATING_ICON[r.rating] ?? "·";
+  const valueText = paint(r.rating, formatValue(r.value, r.unit));
+  const ratingText = styleText("dim", r.rating ?? "");
+  const detail = r.details?.element ? styleText("dim", r.details.element) : "";
+
+  let out = `  ${icon} ${pad(r.id, 16)} ${pad(valueText, 10)} ${pad(ratingText, 20)} ${detail}`;
+
+  if (r.metric === "LCP" && r.details?.subParts) {
+    const sp = r.details.subParts;
+    const rows = [
+      ["TTFB", sp.ttfb],
+      ["Resource Load Delay", sp.resourceLoadDelay],
+      ["Resource Load Time", sp.resourceLoadTime],
+      ["Element Render Delay", sp.elementRenderDelay],
+    ];
+    out += "\n";
+    out += rows
+      .map(([name, info]) => {
+        const status = info.overTarget ? styleText("red", "🔴") : styleText("green", "✓");
+        return `       ${status} ${pad(name, 22)} ${pad(`${info.value}ms`, 8)} ${pad(`${info.percent}%`, 6)}`;
+      })
+      .join("\n");
+    if (r.details.slowestPhase) {
+      out += `\n       ${styleText("blue", "→ Slowest:")} ${r.details.slowestPhase}`;
+    }
+  }
+
+  if (r.reason) {
+    out += `\n     ${styleText("dim", `↳ ${r.reason}`)}`;
+  }
+
+  return out;
+}
+
+export function reportHuman({ url, navMs, results, pageErrors, verbose }) {
+  const lines = [];
+  lines.push(styleText(["bold"], `WebPerf Snippets — ${url}`));
+  lines.push(styleText("dim", `Navigated in ${navMs}ms`));
+  lines.push("");
+  for (const r of results) lines.push(renderResult(r, verbose));
+  if (pageErrors?.length) {
+    lines.push("");
+    lines.push(styleText("yellow", "Page errors during run:"));
+    for (const err of pageErrors) lines.push(`  ${styleText("dim", err)}`);
+  }
+  return lines.join("\n");
+}

package/src/reporters/json.js

@@ -0,0 +1,3 @@
+export function reportJson(payload) {
+  return JSON.stringify(payload, null, 2);
+}

package/src/runner.js

@@ -0,0 +1,61 @@
+import { chromium } from "playwright";
+
+export const VIEWPORT_PRESETS = {
+  mobile: { width: 375, height: 812 },
+  tablet: { width: 768, height: 1024 },
+  desktop: { width: 1280, height: 800 },
+};
+
+const DEFAULT_NAV_TIMEOUT = 30000;
+
+// Snippets are IIFEs. Playwright evaluates a string as an expression, so we
+// trim trailing semicolons to keep the IIFE call as a single expression and
+// recover its return value in Node.
+function toExpression(source) {
+  return source.trim().replace(/;\s*$/, "");
+}
+
+export async function runSnippets({
+  url,
+  items,
+  waitMs = 3000,
+  headless = true,
+  viewport = VIEWPORT_PRESETS.mobile,
+  navTimeout = DEFAULT_NAV_TIMEOUT,
+}) {
+  const browser = await chromium.launch({ headless });
+  try {
+    const context = await browser.newContext({ viewport });
+    const page = await context.newPage();
+
+    const pageErrors = [];
+    page.on("pageerror", (err) => pageErrors.push(err.message));
+
+    const navStart = Date.now();
+    await page.goto(url, { waitUntil: "load", timeout: navTimeout });
+    if (waitMs > 0) await page.waitForTimeout(waitMs);
+    const navMs = Date.now() - navStart;
+
+    const results = [];
+    for (const item of items) {
+      try {
+        const result = await page.evaluate(toExpression(item.source));
+        if (result && typeof result === "object") {
+          results.push({ id: item.id, ...result });
+        } else {
+          results.push({
+            id: item.id,
+            status: "error",
+            error: "Snippet did not return an object — check the IIFE return statement",
+          });
+        }
+      } catch (err) {
+        results.push({ id: item.id, status: "error", error: err.message });
+      }
+    }
+
+    return { url, navMs, results, pageErrors };
+  } finally {
+    await browser.close();
+  }
+}