feat: add webperf-snippets CLI (MVP)

[nucliweb]

Summary

• Adds a headless CLI that runs curated WebPerf Snippets via Playwright, enabling Core Web Vitals diagnosis and CI budget gating without manual DevTools copy-paste.
• Root package renamed to webperf-snippets-docs (private, no external impact); cli/ added as npm workspace with name: webperf-snippets.
• Zero non-peer deps — only requires Node ≥ 20.12 and Playwright as a peer dependency.

Available snippets

Alias	Snippet	Category
LCP	Largest Contentful Paint	Core Web Vitals
CLS	Cumulative Layout Shift	Core Web Vitals
LCP-Subparts	LCP Subparts breakdown	Core Web Vitals
fonts	Fonts Preloaded, Loaded, and Used Above The Fold	Loading

The default workflow runs LCP + CLS and auto-enqueues LCP-Subparts if LCP exceeds 2.5s.

What it does

# Default workflow: LCP + CLS, auto-enqueues LCP-Subparts if LCP > 2.5s
npx webperf-snippets https://example.com

# JSON output for CI pipes
npx webperf-snippets https://example.com --json

# Single snippet by alias
npx webperf-snippets https://example.com --snippet LCP-Subparts
npx webperf-snippets https://example.com --snippet fonts

# Budget gating — exits 1 on violation
npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1

Key implementation detail

Chrome does not expose largest-contentful-paint or layout-shift entries via performance.getEntriesByType() without a buffered observer running before the entries are emitted. The runner installs an addInitScript shim before navigation that captures entries via observers and patches getEntriesByType so existing snippets work unmodified.

This is also a real bug in the snippets' // Synchronous return for agent paths — tracked and fixed in a separate PR.

Files added

File	Purpose
cli/package.json	Package config, bin, peer dep
cli/src/bin.js	CLI entry, util.parseArgs, exit codes 0/1/2
cli/src/runner.js	Playwright launch, warmup shim, snippet evaluator
cli/src/load-snippet.js	Resolves snippets by name/path
cli/src/workflows/cwv.js	Core Web Vitals workflow definition
cli/src/decision-tree.js	Declarative follow-up rules
cli/src/reporters/human.js	Colour table via util.styleText
cli/src/reporters/json.js	Raw JSON output
cli/README.md	Usage, options, CI example, roadmap, known limitations

Test plan

• node cli/src/bin.js --help prints usage
• node cli/src/bin.js https://web.dev returns green LCP + CLS with element info
• node cli/src/bin.js https://web.dev --json returns valid JSON with all fields
• node cli/src/bin.js https://web.dev --snippet LCP-Subparts shows sub-part breakdown
• node cli/src/bin.js https://web.dev --snippet fonts shows loaded/used-above-fold font tables
• node cli/src/bin.js https://web.dev --budget-lcp 100 exits 1 with violation on stderr
• Lower decision-tree threshold temporarily → confirm LCP-Subparts fires automatically with reason line

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
webperf-snippets	Ready	Preview, Comment	May 1, 2026 6:45am
webperf-snippets-u6am	Ready	Preview, Comment	May 1, 2026 6:45am