feat: Fully Loaded Snapshot Capture — Readiness Gate (PER-7348)

packages/core/src/config.js

@@ -132,6 +132,21 @@ export const configSchema = {
       sync: {
         type: 'boolean'
       },
+      readiness: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          preset: { type: 'string', enum: ['balanced', 'strict', 'fast', 'disabled'] },
+          stabilityWindowMs: { type: 'integer', minimum: 50, maximum: 30000 },
+          networkIdleWindowMs: { type: 'integer', minimum: 50, maximum: 10000 },
+          timeoutMs: { type: 'integer', minimum: 1000, maximum: 60000 },
+          imageReady: { type: 'boolean' },
+          fontReady: { type: 'boolean' },
+          jsIdle: { type: 'boolean' },
+          readySelectors: { type: 'array', items: { type: 'string' } },
+          notPresentSelectors: { type: 'array', items: { type: 'string' } }
+        }
+      },
       responsiveSnapshotCapture: {
         type: 'boolean',
         default: false
@@ -502,6 +517,7 @@ export const snapshotSchema = {
         ignoreCanvasSerializationErrors: { $ref: '/config/snapshot#/properties/ignoreCanvasSerializationErrors' },
         ignoreStyleSheetSerializationErrors: { $ref: '/config/snapshot#/properties/ignoreStyleSheetSerializationErrors' },
         pseudoClassEnabledElements: { $ref: '/config/snapshot#/properties/pseudoClassEnabledElements' },
+        readiness: { $ref: '/config/snapshot#/properties/readiness' },
         discovery: {
           type: 'object',
           additionalProperties: false,
@@ -651,6 +667,7 @@ export const snapshotSchema = {
         url: { type: 'string' },
         name: { type: 'string' },
         width: { $ref: '/config/snapshot#/properties/widths/items' },
+        readiness_diagnostics: { type: 'object', additionalProperties: true },
         domSnapshot: {
           oneOf: [{ type: 'string' }, {
             type: 'object',

packages/core/src/discovery.js

@@ -359,6 +359,11 @@ async function* captureSnapshotResources(page, snapshot, options) {
     yield waitForFontLoading(page);
     yield waitForDiscoveryNetworkIdle(page, discovery);
     yield* captureResponsiveAssets();
+    // Readiness does NOT run on SDK-provided domSnapshots. The DOM is already
+    // serialized at this point — running readiness cannot modify it. Preserving
+    // the domSnapshot maintains modal state, post-interaction state, and supports
+    // localhost testing. SDK users who need fully-loaded snapshots should wait
+    // for page stability in their test code before calling percySnapshot().
     capture(processSnapshotResources(snapshot));
   }
 }
@@ -483,10 +488,29 @@ export function createDiscoveryQueue(percy) {
             }
           });
 
+          // Set readiness config on page for Storybook (which calls page.snapshot() without readiness in options)
+          page._readinessConfig = snapshot.readiness || percy.config?.snapshot?.readiness;
+
           try {
+            // Wrap callback to send failed readiness diagnostics to smart debugging
+            /* istanbul ignore next: diagnostic callback requires live browser readiness timeout */
+            let captureWithDiagnostics = (captured) => {
+              if (captured?.readiness_diagnostics && !captured.readiness_diagnostics.passed) {
+                let diag = captured.readiness_diagnostics;
+                let failedChecks = Object.entries(diag.checks || {})
+                  .filter(([, c]) => !c.passed)
+                  .map(([name]) => name);
+                percy.suggestionsForFix(
+                  `Snapshot "${captured.name}" readiness timed out after ${diag.total_duration_ms}ms. Failed checks: ${failedChecks.join(', ')}`,
+                  { snapshotLevel: true, snapshotName: captured.name }
+                );
+              }
+              callback(captured);
+            };
+
             yield* captureSnapshotResources(page, snapshot, {
               captureWidths: !snapshot.domSnapshot && percy.deferUploads,
-              capture: callback,
+              capture: captureWithDiagnostics,
               captureForDevices: percy.deviceDetails || []
             });
           } finally {

packages/core/src/page.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import logger from '@percy/logger';
 import Network from './network.js';
 import { PERCY_DOM } from './api.js';
+import { waitForReadiness } from './readiness.js';
 import {
   hostname,
   waitFor,
@@ -11,6 +12,9 @@ import {
 
 export class Page {
   static TIMEOUT = undefined;
+  // Global readiness config set by Percy constructor, accessible by all page instances.
+  // Needed for Storybook which calls page.snapshot() without readiness in options.
+  static _globalReadinessConfig = null;
 
   log = logger('core:page');
 
@@ -213,6 +217,15 @@ export class Page {
 
     await this.insertPercyDom();
 
+    // Run readiness checks before capturing — only when explicitly configured.
+    // Config priority: per-snapshot > per-page > global (from Percy constructor)
+    let readinessDiagnostics = null;
+    let effectiveReadiness = snapshot.readiness || this._readinessConfig || Page._globalReadinessConfig;
+    /* istanbul ignore next: readiness execution requires live browser + active config */
+    if (effectiveReadiness && effectiveReadiness.preset !== 'disabled') {
+      readinessDiagnostics = await waitForReadiness(this, { ...snapshot, readiness: effectiveReadiness });
+    }
+
     // serialize and capture a DOM snapshot
     this.log.debug('Serialize DOM', this.meta);
 
@@ -223,6 +236,8 @@ export class Page {
       url: document.URL
     }), { enableJavaScript, disableShadowDOM, forceShadowAsLightDOM, domTransformation, reshuffleInvalidTags, ignoreCanvasSerializationErrors, ignoreStyleSheetSerializationErrors, pseudoClassEnabledElements });
 
+    /* istanbul ignore next: readinessDiagnostics only set when readiness runs (requires live browser) */
+    if (readinessDiagnostics) capture.readiness_diagnostics = readinessDiagnostics;
     return { ...snapshot, ...capture };
   }
 

packages/core/src/percy.js

@@ -3,6 +3,7 @@ import PercyConfig from '@percy/config';
 import logger from '@percy/logger';
 import { getProxy } from '@percy/client/utils';
 import Browser from './browser.js';
+import { Page } from './page.js';
 import Pako from 'pako';
 import {
   base64encode,
@@ -96,6 +97,11 @@ export class Percy {
     this.config = config;
     this.cliStartTime = null;
 
+    // Set global readiness config for all Page instances
+    if (config.snapshot?.readiness) {
+      Page._globalReadinessConfig = config.snapshot.readiness;
+    }
+
     if (testing) loglevel = 'silent';
     if (loglevel) this.loglevel(loglevel);
 
@@ -363,8 +369,9 @@ export class Percy {
       await this.#discovery.end();
       await this.#snapshots.end();
 
-      // mark instance as stopped
+      // mark instance as stopped and reset global readiness config
       this.readyState = 3;
+      Page._globalReadinessConfig = null;
     } catch (err) {
       this.log.error(err);
       throw err;

packages/core/src/readiness.js

@@ -0,0 +1,90 @@
+import logger from '@percy/logger';
+
+const log = logger('core:readiness');
+
+export const PRESETS = {
+  balanced: { stability_window_ms: 300, network_idle_window_ms: 200, timeout_ms: 10000, image_ready: true, font_ready: true, js_idle: true },
+  strict: { stability_window_ms: 1000, network_idle_window_ms: 500, timeout_ms: 30000, image_ready: true, font_ready: true, js_idle: true },
+  fast: { stability_window_ms: 100, network_idle_window_ms: 100, timeout_ms: 5000, image_ready: false, font_ready: true, js_idle: true }
+};
+
+// Resolve readiness config from preset + per-snapshot overrides.
+// Accepts camelCase (from Percy config normalizer) and outputs snake_case for @percy/dom.
+/* istanbul ignore next: default params and ?? branches tested via unit tests */
+export function resolveReadinessConfig(options = {}) {
+  let readiness = options.readiness || {};
+  let presetName = readiness.preset || 'balanced';
+  if (presetName === 'disabled') return { preset: 'disabled' };
+
+  let preset = PRESETS[presetName] || PRESETS.balanced;
+  return {
+    preset: presetName,
+    stability_window_ms: (readiness.stabilityWindowMs ?? readiness.stability_window_ms) ?? preset.stability_window_ms,
+    network_idle_window_ms: (readiness.networkIdleWindowMs ?? readiness.network_idle_window_ms) ?? preset.network_idle_window_ms,
+    timeout_ms: (readiness.timeoutMs ?? readiness.timeout_ms) ?? preset.timeout_ms,
+    image_ready: (readiness.imageReady ?? readiness.image_ready) ?? preset.image_ready,
+    font_ready: (readiness.fontReady ?? readiness.font_ready) ?? preset.font_ready,
+    js_idle: (readiness.jsIdle ?? readiness.js_idle) ?? preset.js_idle,
+    ...((readiness.readySelectors ?? readiness.ready_selectors) && { ready_selectors: readiness.readySelectors ?? readiness.ready_selectors }),
+    ...((readiness.notPresentSelectors ?? readiness.not_present_selectors) && { not_present_selectors: readiness.notPresentSelectors ?? readiness.not_present_selectors })
+  };
+}
+
+// CLI-side readiness orchestrator.
+// Calls PercyDOM.waitForReady() in the browser context via page.eval().
+/* istanbul ignore next: warning logging branches tested via unit tests with mocks */
+export async function waitForReadiness(page, options = {}) {
+  let config = resolveReadinessConfig(options);
+  if (config.preset === 'disabled') return null;
+
+  log.debug(`Running readiness checks: preset=${config.preset}, not_present=${JSON.stringify(config.not_present_selectors || [])}`);
+
+  // Note: insertPercyDom() is already called by the caller in page.snapshot() (line 218)
+  // before waitForReadiness is invoked — no need to call it again here.
+
+  let result;
+  try {
+    /* istanbul ignore next: no instrumenting injected code */
+    /* istanbul ignore next: no instrumenting injected code */
+    result = await page.eval((_, readinessConfig) => {
+      // eslint-disable-next-line no-undef
+      if (typeof PercyDOM === 'undefined' || typeof PercyDOM.waitForReady !== 'function') {
+        return { passed: true, error: 'waitForReady not available', checks: {} };
+      }
+      // eslint-disable-next-line no-undef
+      return PercyDOM.waitForReady(readinessConfig);
+    }, config);
+  } catch (error) {
+    log.debug(`Readiness check error: ${error.message}`);
+    result = { passed: false, timed_out: false, error: error.message, total_duration_ms: 0, checks: {} };
+  }
+
+  if (result && !result.passed) {
+    let lines = [`Snapshot "${options.name || 'unknown'}" captured before stable (timed out after ${result.total_duration_ms}ms)`];
+    for (let [name, check] of Object.entries(result.checks || {})) {
+      let status = check.passed ? 'passed' : 'FAILED';
+      let detail = check.duration_ms != null ? ` (${check.duration_ms}ms)` : '';
+      if (!check.passed && check.mutations_observed) detail = ` (${check.mutations_observed} mutations in ${check.duration_ms}ms)`;
+      lines.push(`  - ${name}: ${status}${detail}`);
+    }
+    let failed = Object.entries(result.checks || {}).filter(([, c]) => !c.passed);
+    if (failed.length) {
+      let [name] = failed[0];
+      let tips = {
+        dom_stability: 'Try adding notPresentSelectors for loading indicators, or increase stabilityWindowMs.',
+        network_idle: 'Check for long-polling or analytics. Try adding endpoints to disallowedHostnames.',
+        image_ready: 'Images still loading. Try imageReady: false if images load lazily.',
+        js_idle: 'JavaScript still executing (long tasks detected on main thread). Try increasing timeoutMs or set jsIdle: false for pages with continuous JS.',
+        ready_selectors: 'Required selector(s) not found. Verify selectors exist on the page.',
+        not_present_selectors: 'Loading indicators still present. These may be skeleton loaders or spinners.'
+      };
+      if (tips[name]) lines.push(`  Tip: ${tips[name]}`);
+    }
+    log.warn(`Warning: ${lines[0]}`);
+    for (let l of lines.slice(1)) log.warn(l);
+  } else if (result) {
+    log.debug(`Readiness checks passed in ${result.total_duration_ms}ms`);
+  }
+
+  return result;
+}

packages/core/test/api.test.js

@@ -1008,4 +1008,32 @@ describe('API Server', () => {
       });
     });
   });
+
+  describe('POST /percy/snapshot — passes options unchanged', () => {
+    it('forwards snapshot options to percy.snapshot without adding internal flags', async () => {
+      await percy.start();
+
+      let receivedOptions;
+      spyOn(percy, 'snapshot').and.callFake((opts) => {
+        receivedOptions = opts;
+        return Promise.resolve();
+      });
+
+      await request('/percy/snapshot', {
+        method: 'POST',
+        body: {
+          name: 'sdk test',
+          url: 'http://localhost:8000',
+          domSnapshot: '<html></html>'
+        }
+      });
+
+      expect(receivedOptions).toEqual({
+        name: 'sdk test',
+        url: 'http://localhost:8000',
+        domSnapshot: '<html></html>'
+      });
+      expect(receivedOptions._fromSDK).toBeUndefined();
+    });
+  });
 });