feat: PER-7348 add waitForReady() call before serialize()

[Shivanshu-07]

Summary

Adds readiness-gated snapshot capture to this SDK (PER-7348). Before serializing the DOM, the SDK now calls PercyDOM.waitForReady(config) to ensure the page is stable — no skeleton screens, fonts loaded, network idle, JavaScript settled.

Architecture: Two-Call Pattern

Step 1: PercyDOM.waitForReady(config)  — async, waits for page stability
Step 2: PercyDOM.serialize(options)    — sync, captures the stable DOM (unchanged)

• serialize() stays synchronous — zero breakage
• Readiness is a separate async call that runs before serialize
• Diagnostics from waitForReady() are captured and attached to domSnapshot.readiness_diagnostics so the CLI can log timing and pass/fail

Backward compatibility

Scenario	Behavior
This SDK + old CLI	typeof PercyDOM.waitForReady === 'function' is false — skips readiness. serialize() works as today.
This SDK + new CLI	waitForReady() runs, page stabilizes, diagnostics attached, serialize() captures stable DOM.
waitForReady throws	Caught, logged at debug level, serialize() still runs.
waitForReady times out	Resolves with { timed_out: true }, serialize() still runs.

Readiness config

Readiness config flows from .percy.yml through the CLI healthcheck to the SDK:

# .percy.yml
snapshot:
  readiness:
    preset: balanced  # balanced | strict | fast | disabled
    stabilityWindowMs: 300
    networkIdleWindowMs: 200
    timeoutMs: 10000

Per-snapshot overrides: percySnapshot('name', { readiness: { preset: 'strict' } })

Disable globally: readiness: { preset: disabled }

Test plan

• Readiness runs before serialize when enabled
• Readiness config from snapshot options is passed through
• Readiness skipped when preset: disabled
• Serialize still runs when waitForReady throws
• Backward compat: works when PercyDOM.waitForReady is unavailable (old CLI)

Depends on

• feat: Readiness gate in PercyDOM.serialize() — works for URL + SDK paths (PER-7348) cli#2184 (readiness implementation in @percy/dom)

[rishigupta1599]

Nice backward-compatible design — the in-browser typeof PercyDOM.waitForReady guard plus graceful exception handling is the right shape for a staged CLI rollout. A few substantive concerns worth addressing before merge:

1. readiness leaks into PercyDOM.serialize() and into the snapshot POST body. get_serialized_dom never pops readiness out of kwargs, so it gets JSON-serialized into the PercyDOM.serialize(kwargs) argument and also spread into the /percy/snapshot POST body as a top-level field. @percy/dom.serialize ignores unknown keys today, but it's a silent coupling, and the CLI snapshot endpoint receiving a top-level readiness alongside snapshot options is likely not what the CLI expects (readiness config is supposed to flow via healthcheck per the PR description). Pop readiness from kwargs once consumed.

2. Readiness runs N times for responsive capture. capture_responsive_dom calls get_serialized_dom once per width, so with 3 widths and a 10s timeout you can add up to 30s of sequential readiness waits per snapshot name. Consider running readiness once before the width loop and short-circuiting inside get_serialized_dom when responsive is active.

3. No explicit script timeout. execute_async_script relies on the driver's global script timeout (Selenium default ~30s, but BrowserStack hubs and some remotes use lower). If a user sets readiness.timeoutMs higher than the driver's script timeout, WebDriver fires ScriptTimeoutException before the in-page Promise resolves — so the user-facing timeout is silently capped. Either driver.set_script_timeout(readiness.timeoutMs + buffer) around the call (and restore the previous value) or document the interaction.

4. Minor: the is_percy_enabled() call inside _wait_for_ready is redundant — percy_snapshot has already called it and has the data dict in scope. Plumb data['config'] through instead of re-reading the lru_cache.

Tests look solid for the happy paths. Consider adding one for the responsive + readiness interaction once (2) is resolved.

[github-actions]

This PR is stale because it has been open for more than 14 days with no activity. Remove stale label or comment or this will be closed in 14 days.