feat: Readiness gate in PercyDOM.serialize() — works for URL + SDK paths (PER-7348)

[Shivanshu-07]

Summary

Implements readiness-gated snapshot capture for Percy (PER-7348). Readiness checks ensure pages are stable before DOM serialization — no skeleton screens, loaded fonts/images, idle network, settled JavaScript.

Architecture: Two-Call Pattern

Readiness and serialization are two separate calls, not one combined async function:

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

This keeps serialize() always synchronous (zero SDK breakage) while isolating the async readiness into its own independent step. Both the CLI URL-capture path and SDKs use the same pattern.

What's included in this PR (CLI-side)

@percy/dom — readiness checks (packages/dom/src/readiness.js)

• 7 parallel checks: DOM stability (MutationObserver), network idle (PerformanceObserver), font ready, image ready, JS idle (Long Task API + rIC + double-rAF), ready selectors, not-present selectors
• 3 presets: balanced (default), strict, fast, disabled
• Dedicated js_idle_window_ms decoupled from stability_window_ms
• normalizeOptions() for camelCase/snake_case config compatibility
• Abort propagation to all checks on timeout
• 100% test coverage (lines/branches/functions/statements)

@percy/dom — serialization (packages/dom/src/serialize-dom.js)

• serializeDOM() — single sync function. No async variant needed.
• waitForReady() exported separately for the readiness call

@percy/core — CLI URL-capture path (packages/core/src/page.js)

• Two-call pattern: waitForReady(config) then serialize(options) as separate eval calls
• Readiness config from per-snapshot options or global .percy.yml
• Graceful degradation: if readiness fails or times out, serialize still runs

@percy/core — config schema (packages/core/src/config.js)

• readiness schema: preset, stabilityWindowMs, jsIdleWindowMs, networkIdleWindowMs, timeoutMs, maxTimeoutMs, domStability, imageReady, fontReady, jsIdle, readySelectors, notPresentSelectors
• readySelectors / notPresentSelectors accept either a CSS string or an explicit { css } / { xpath } object form. Bare strings beginning with /, //, ./, (/, (./ are auto-detected as XPath.
• readiness_diagnostics allowed in domSnapshot schema (no more validation warnings)
• CLI logs readiness diagnostics at debug/warn level

@percy/sdk-utils — helpers for SDK adoption (packages/sdk-utils/src/serialize-dom.js)

• waitForReadyScript(config, { callback }) — JS code string for the readiness call
  • Default variant: for page.evaluate() (Puppeteer/Playwright auto-await)
  • Callback variant: for executeAsyncScript (Selenium/Nightwatch/WebdriverIO)
• getReadinessConfig(options) — extracts readiness config from per-snapshot or global percy.config
• isReadinessDisabled(options) — quick check for preset: disabled

---

SDK Rollout (separate PRs per SDK)

After this CLI PR merges and a new CLI version is published, each SDK adds a waitForReady() call before its existing serialize() call. The serialize() call itself stays unchanged.

How SDKs adopt readiness

The two-call pattern for SDKs:

Step 1: Call PercyDOM.waitForReady(config)   — async, page stabilizes
Step 2: Call PercyDOM.serialize(options)      — sync, UNCHANGED from today

Pattern A: Puppeteer / Playwright SDKs (page.evaluate auto-awaits)

// NEW — readiness (async, auto-awaited by page.evaluate)
let readinessConfig = utils.getReadinessConfig(options);
if (!utils.isReadinessDisabled(options)) {
  await page.evaluate(async (config) => {
    if (typeof PercyDOM?.waitForReady === 'function') {
      return PercyDOM.waitForReady(config);
    }
  }, readinessConfig).catch(() => {});
}

// UNCHANGED — serialize (sync)
let domSnapshot = await page.evaluate((opts) => PercyDOM.serialize(opts), serializeOptions);

Applies to: @percy/puppeteer, @percy/playwright, percy-playwright-python, percy-playwright-java, percy-playwright-dotnet

Pattern B: Selenium SDKs (executeAsyncScript for readiness, executeScript for serialize)

# NEW — readiness (async, uses executeAsyncScript with callback)
readiness_config = percy.config.get('snapshot', {}).get('readiness', {})
if readiness_config.get('preset') != 'disabled':
    try:
        driver.execute_async_script('''
            var config = arguments[0];
            var done = arguments[arguments.length - 1];
            if (typeof PercyDOM !== 'undefined' && typeof PercyDOM.waitForReady === 'function') {
                PercyDOM.waitForReady(config).then(function() { done(); }).catch(function() { done(); });
            } else { done(); }
        ''', readiness_config or {})
    except Exception:
        pass

# UNCHANGED — serialize (sync, exactly the same as today)
dom = driver.execute_script('return PercyDOM.serialize({})'.format(json.dumps(opts)))

Applies to: percy-selenium-python, percy-selenium-java, percy-selenium-ruby, percy-selenium-dotnet, @percy/selenium-js, percy-capybara, @percy/webdriverio

Pattern C: In-browser SDKs (Cypress, Ember)

// NEW — readiness (await the Promise directly)
if (typeof PercyDOM?.waitForReady === 'function') {
  await PercyDOM.waitForReady(readinessConfig).catch(() => {});
}

// UNCHANGED — serialize (sync)
let domSnapshot = PercyDOM.serialize(options);

Applies to: @percy/cypress, @percy/ember

Pattern D: Other JS SDKs

• @percy/nightwatch: browser.executeAsync() for readiness, browser.execute() unchanged
• @percy/testcafe: await t.eval(async () => PercyDOM.waitForReady(config)) before serialize
• @percy/storybook: Uses CLI page.eval() — already covered by this PR

Backward compatibility

Scenario	Behavior
Old SDK + new CLI	SDK never calls waitForReady. serialize() works as today. No readiness.
New SDK + old CLI	SDK checks typeof PercyDOM.waitForReady === 'function' — undefined on old CLI. Skips readiness. serialize() works.
New SDK + new CLI	waitForReady() runs then page stabilizes then serialize() captures stable DOM.
waitForReady throws	SDK catches error, proceeds to serialize(). Snapshot captured without readiness.
waitForReady times out	Resolves with { timed_out: true }. SDK proceeds to serialize().

SDK change matrix

SDK	Repo	Change needed
@percy/puppeteer	percy/percy-puppeteer	Pattern A
@percy/playwright	percy/percy-playwright	Pattern A
percy-playwright-python	percy/percy-playwright-python	Pattern A
percy-playwright-java	percy/percy-playwright-java	Pattern A
percy-playwright-dotnet	percy/percy-playwright-dotnet	Pattern A
@percy/cypress	percy/percy-cypress	Pattern C
@percy/ember	percy/percy-ember	Pattern C
@percy/nightwatch	percy/percy-nightwatch	Pattern D
@percy/testcafe	percy/percy-testcafe	Pattern D
@percy/selenium-js	percy/percy-selenium-js	Pattern B
@percy/webdriverio	percy/percy-webdriverio	Pattern B
percy-selenium-python	percy/percy-selenium-python	Pattern B
percy-selenium-java	percy/percy-selenium-java	Pattern B
percy-selenium-ruby	percy/percy-selenium-ruby	Pattern B
percy-selenium-dotnet	percy/percy-selenium-dotnet	Pattern B
percy-capybara	percy/percy-capybara	Pattern B
@percy/storybook	percy/percy-storybook	No change (uses CLI page.eval)

---

Test plan

• @percy/dom tests: 616 pass, 100% coverage
• @percy/core tests: 684 specs, no new failures (27 pre-existing env failures: Chromium install mocks, runDoctor, AggregateError)
• @percy/config tests: 82 pass
• Lint passes
• serializeDOM() is always sync (backward compat test)
• waitForReady() with disabled preset skips all checks
• Readiness waits for DOM stability (skeleton removal test)
• Readiness waits for ready selectors
• Readiness times out gracefully (serialize still happens)
• camelCase config normalization (SDK flow)
• Direct unit tests for helpers: isLayoutMutation, hasLayoutStyleChange, parseStyleProps, normalizeOptions, createAbortHandle

Configuration

# .percy.yml
snapshot:
  readiness:
    preset: balanced  # balanced | strict | fast | disabled
    stabilityWindowMs: 300
    jsIdleWindowMs: 300
    networkIdleWindowMs: 200
    timeoutMs: 10000
    maxTimeoutMs: 25000  # cap for Selenium async timeout compat
    domStability: true   # set false to fully disable the MutationObserver check
    imageReady: true
    fontReady: true
    jsIdle: true
    readySelectors:
      - '.content-loaded'                    # CSS string
      - '//section[@id="ready" and contains(@class,"loaded")]'  # XPath (auto-detected)
      - { xpath: '//div[@id="root"]' }       # explicit XPath object form
      - { css: '.weird /selector' }          # explicit CSS object form
    notPresentSelectors: ['.skeleton']

Kill switches

Scenario	Setting
Disable everything (revert to pre-readiness behavior)	preset: disabled
Keep gating on JS idle / images / fonts / selectors but skip the MutationObserver (use this on heavy-DOM pages where the observer drives CPU/memory pressure)	domStability: false
Skip individual checks	imageReady: false, fontReady: false, jsIdle: false

Generated with Claude Code

[rishigupta1599]

Review Summary

The architecture is solid -- moving readiness into PercyDOM.serialize() is the right call for URL + SDK parity. Good test coverage (1000+ lines) and clean abort/cleanup logic.

However, there are several issues that need addressing before merge, ranging from a config naming mismatch bug that will silently break user overrides, to missing abort propagation, and a coupling concern in the JS idle check. See inline comments.

[Shivanshu-07]

Review feedback addressed in a1046bf2

#	Reviewer concern	Resolution
1	diagnostics fetched in page.js but never attached → reader in snapshot.js is dead code	Diagnostics now attached onto capture.domSnapshot (object form) before returning, so backend/UI can surface readiness metrics on the CLI URL path
2	/* istanbul ignore next */ swallows the .catch handler in page.js	Ignore moved inside the eval(...) call, scoped only to the injected arrow. Added spec that rejects readiness eval and asserts Readiness check failed: ... debug log fires
3	migrated.domSnapshot?.readiness_diagnostics reads cleanly off a string but is unclear	Explicit typeof migrated.domSnapshot === 'object' gate via domSnapshotObj. Reader is no longer dead code — populated by the CLI URL path today and by SDKs once their PRs land
4	JSON.stringify(readinessConfig) interpolates without escaping U+2028/U+2029	Escape both with .replace(/ /g, '\\u2028').replace(/ /g, '\\u2029'). Added JSDoc warning that the output must not be inlined into HTML. New sdk-utils spec asserts the escape sequences are present
5	checkFontReady abort: document.fonts.ready can flip the race to { passed: true } after timeout	Race now includes a third abortPromise that resolves with { passed: false, aborted: true } on abort, settling the result deterministically

CI is green on Linux (Linux Test @percy/core passed at 11m22s, all other checks pass). Windows variant still in progress.