feat: toHaveScreenshot drop-in — route existing Playwright assertions through Percy

[Shivanshu-07]

Ports the toHaveScreenshot drop-in (PER-8985) into this SDK so it ships from @percy/playwright instead of a separate package. One require line converts a repo's existing Playwright screenshot assertions into Percy visual tests — no test changes, no rewrites.

// playwright.config.js
require('@percy/playwright/dropin');

PERCY_TOKEN=<token> npx percy-playwright exec -- npx playwright test

What's in the box (dropin/)

• The override (dropin/index.js): replaces Playwright's built-in toHaveScreenshot matcher on the shared expect. The public expect.extend() silently ignores built-in matcher names on the shared instance (the override only exists on the discarded return value), so registration writes into expect's internal userMatchers — which call-time dispatch spreads after built-ins. On an unrecognized internal shape it degrades to extend() with a loud warning, never a silent no-op. Verified on @playwright/test 1.60/1.61.
• Never fail the suite: any Percy error is swallowed (warn/debug); if Percy is down at run start the whole run delegates to the genuine native matcher (pristine-expect chain snapshotted before the override), so consumers keep real pixel-diff protection.
• Identity (dropin/identity.js): snapshot names reproduce Playwright's on-disk baseline stems byte-for-byte (same sanitizer regex, same per-test anonymous counters) so uploads pair with committed baselines.
• Capture modes (.percy-playwright-dropin.json):
  • screenshot (default): stabilized PNG → raw-image comparison (generic/app projects); tag width = identity width, tag height parsed from PNG bytes (percy-api validates height presence).
  • snapshot: serialized-DOM web snapshot for web projects — delegates to this repo's own captureDOM, inheriting the readiness gate, responsive capture, and cross-origin iframe handling; the two entry points cannot drift. Locator subjects become element-scoped snapshots (transient data-percy-dropin-scope marker + scope).
• First-build-as-baseline: the percy-playwright wrapper bin sets PERCY_DROPIN_BASELINE_CANDIDATE=true (mirrors PERCY_BUILD_SOURCE); percy-api decides first-ness server-side and, on a genuine first build, dropin/global-setup.js seeds the repo's committed baseline PNGs as the build's content (8-way parallel) while the override skips live captures. The server auto-approves that baseline (org-flag-gated) — diffs start on run 2. Server side lands via percy/percy-api#6178; CLI plumbing via feat(client/sdk-utils): additive support for @percy/playwright-dropin baseline seed + sync verdict cli#2275.
• Opt-in extras: dropin/reporter.js (fail-on-changes CI gate, first build always review-only) and sync-assertion mode (inline verdicts, .percy.yml snapshot.sync, read-token guarded).

Repo-level changes

• index.js: exports captureDOM for internal reuse; ENV_INFO's top-level require('playwright/package.json') crashed at import time under the 1.61 runner (CJS↔ESM interop) — now guarded with graceful fallbacks.
• package.json: ships dropin/ + bin/, adds the percy-playwright bin, @playwright/test as an optional peer (only the dropin entry needs it), devDeps bumped ^1.24.2 → ^1.60.0 (the drop-in requires modern expect internals; existing suite passes unchanged on 1.61).
• Types + README section.

Testing

• 117 passed (full suite on @playwright/test 1.61.1), lint clean.
• New dispatch specs drive the REAL Playwright expect through the override and hard-assert the posted comparison (name/tag dims/tile) — the exact check that prevents a silent registration no-op; wrapped in expect().toPass() because the shared CLI testing server is reset concurrently by parallel workers.
• Unit specs pin name derivation, first-build seeding (server-decision keyed, PNG-dims tags), and locator scope-marker lifecycle.
• The same implementation was E2E-validated against staging percy-api (first build seeded + auto-approved flag-on; run-2 diffs against it) in PER-8985.

Notes for reviewers

• The registration and native-fallback lean on Playwright expect internals (META_INFO symbol / userMatchers); the degrade path is loud by design. This is the part most worth scrutiny.
• dropin/ is a direct port of percy/percy-playwright-dropin PR #2 minus its standalone DOM capture (replaced by captureDOM reuse). If this lands, the standalone package can be retired before ever publishing.

🤖 Generated with Claude Code