@percy/sdk-utils 1.31.14-beta.3 → 1.31.14-beta.4

package/dist/bundle.js

@@ -326,6 +326,70 @@
       }
     }
 
+    // Returns the readiness config for a snapshot.
+    // Priority: per-snapshot options > global percy.config > empty object (triggers balanced default).
+    // SDKs obtain percy.config via the healthcheck endpoint in isPercyEnabled().
+    function getReadinessConfig(snapshotOptions = {}) {
+      var _percy$config;
+      return (snapshotOptions === null || snapshotOptions === void 0 ? void 0 : snapshotOptions.readiness) || ((_percy$config = info.config) === null || _percy$config === void 0 || (_percy$config = _percy$config.snapshot) === null || _percy$config === void 0 ? void 0 : _percy$config.readiness) || {};
+    }
+
+    // Returns true if readiness should be skipped for this snapshot.
+    function isReadinessDisabled(snapshotOptions = {}) {
+      let config = getReadinessConfig(snapshotOptions);
+      return (config === null || config === void 0 ? void 0 : config.preset) === 'disabled';
+    }
+
+    // Returns a JavaScript code string that SDKs evaluate in the browser
+    // to run readiness checks BEFORE serialize.
+    //
+    // This is the READINESS-ONLY call. Serialize stays as a separate sync call.
+    // The two-call pattern:
+    //   1. await evaluate(waitForReadyScript(config))     — async, readiness
+    //   2. evaluate('return PercyDOM.serialize(options)')  — sync, unchanged
+    //
+    // Usage:
+    //   // Puppeteer/Playwright (page.evaluate auto-awaits):
+    //   await page.evaluate(waitForReadyScript(config));
+    //
+    //   // Selenium (executeAsyncScript with callback):
+    //   driver.execute_async_script(waitForReadyScript(config, { callback: true }));
+    //
+    // Graceful degradation:
+    //   - If PercyDOM.waitForReady is not available (old CLI): resolves immediately
+    //   - If waitForReady throws: resolves immediately (catch swallows the error)
+    //   - If readiness times out: waitForReady resolves with { timed_out: true }
+    //
+    // IMPORTANT: The output is intended for CDP / executeScript / executeAsyncScript channels.
+    // Do NOT inline this string into HTML — `</script>` sequences in user config would break out
+    // of a <script> tag. SDK authors must add HTML escaping before any HTML-inline use.
+    function waitForReadyScript(readinessConfig = {}, {
+      callback = false
+    } = {}) {
+      // U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) are valid in JSON strings but
+      // were illegal in JS source string literals before ES2019. Escaping them keeps the emitted
+      // script source legal on older engines that may host the SDK eval.
+      let config = JSON.stringify(readinessConfig).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+      if (callback) {
+        // For executeAsyncScript — last argument is the callback
+        return `
+        var done = arguments[arguments.length - 1];
+        try {
+          if (typeof PercyDOM !== 'undefined' && typeof PercyDOM.waitForReady === 'function') {
+            PercyDOM.waitForReady(${config}).then(function(r) { done(r); }).catch(function() { done(); });
+          } else { done(); }
+        } catch(e) { done(); }
+      `;
+      }
+
+      // For page.evaluate (auto-await Promises)
+      return `
+      if (typeof PercyDOM !== 'undefined' && typeof PercyDOM.waitForReady === 'function') {
+        return PercyDOM.waitForReady(${config});
+      }
+    `;
+    }
+
     // Iframe depth constants shared with @percy/dom's serialize-frames. Kept
     // here so external Percy SDKs (Capybara, Cypress, Playwright, etc.) can
     // clamp their own pre-CLI configuration to the same bounds the CLI enforces.
@@ -359,6 +423,9 @@
       DEFAULT_MAX_IFRAME_DEPTH: DEFAULT_MAX_IFRAME_DEPTH,
       HARD_MAX_IFRAME_DEPTH: HARD_MAX_IFRAME_DEPTH,
       clampIframeDepth: clampIframeDepth,
+      waitForReadyScript: waitForReadyScript,
+      getReadinessConfig: getReadinessConfig,
+      isReadinessDisabled: isReadinessDisabled,
       'default': index
     });
 
@@ -369,8 +436,10 @@
     exports["default"] = index;
     exports.fetchPercyDOM = fetchPercyDOM;
     exports.flushSnapshots = flushSnapshots;
+    exports.getReadinessConfig = getReadinessConfig;
     exports.getResponsiveWidths = getResponsiveWidths;
     exports.isPercyEnabled = isPercyEnabled;
+    exports.isReadinessDisabled = isReadinessDisabled;
     exports.logger = logger;
     exports.percy = info;
     exports.postBuildEvents = postBuildEvents;
@@ -378,6 +447,7 @@
     exports.postSnapshot = postSnapshot;
     exports.request = request;
     exports.waitForPercyIdle = waitForPercyIdle;
+    exports.waitForReadyScript = waitForReadyScript;
 
     Object.defineProperty(exports, '__esModule', { value: true });
 

package/dist/index.js

@@ -24,6 +24,12 @@ Object.defineProperty(exports, "flushSnapshots", {
     return _flushSnapshots.default;
   }
 });
+Object.defineProperty(exports, "getReadinessConfig", {
+  enumerable: true,
+  get: function () {
+    return _serializeDom.getReadinessConfig;
+  }
+});
 Object.defineProperty(exports, "getResponsiveWidths", {
   enumerable: true,
   get: function () {
@@ -36,6 +42,12 @@ Object.defineProperty(exports, "isPercyEnabled", {
     return _percyEnabled.default;
   }
 });
+Object.defineProperty(exports, "isReadinessDisabled", {
+  enumerable: true,
+  get: function () {
+    return _serializeDom.isReadinessDisabled;
+  }
+});
 Object.defineProperty(exports, "logger", {
   enumerable: true,
   get: function () {
@@ -78,6 +90,12 @@ Object.defineProperty(exports, "waitForPercyIdle", {
     return _percyIdle.default;
   }
 });
+Object.defineProperty(exports, "waitForReadyScript", {
+  enumerable: true,
+  get: function () {
+    return _serializeDom.waitForReadyScript;
+  }
+});
 var _logger = _interopRequireDefault(require("./logger.js"));
 var _percyInfo = _interopRequireDefault(require("./percy-info.js"));
 var _request = _interopRequireDefault(require("./request.js"));
@@ -90,6 +108,7 @@ var _postBuildEvent = _interopRequireDefault(require("./post-build-event.js"));
 var _flushSnapshots = _interopRequireDefault(require("./flush-snapshots.js"));
 var _postScreenshot = _interopRequireDefault(require("./post-screenshot.js"));
 var _getResponsiveWidths = _interopRequireDefault(require("./get-responsive-widths.js"));
+var _serializeDom = require("./serialize-dom.js");
 var _default = _interopRequireWildcard(require("./index.js"));
 exports.default = _default;
 function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }

package/dist/serialize-dom.js

@@ -0,0 +1,75 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+exports.getReadinessConfig = getReadinessConfig;
+exports.isReadinessDisabled = isReadinessDisabled;
+exports.waitForReadyScript = waitForReadyScript;
+var _percyInfo = _interopRequireDefault(require("./percy-info.js"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Returns the readiness config for a snapshot.
+// Priority: per-snapshot options > global percy.config > empty object (triggers balanced default).
+// SDKs obtain percy.config via the healthcheck endpoint in isPercyEnabled().
+function getReadinessConfig(snapshotOptions = {}) {
+  var _percy$config;
+  return (snapshotOptions === null || snapshotOptions === void 0 ? void 0 : snapshotOptions.readiness) || ((_percy$config = _percyInfo.default.config) === null || _percy$config === void 0 || (_percy$config = _percy$config.snapshot) === null || _percy$config === void 0 ? void 0 : _percy$config.readiness) || {};
+}
+
+// Returns true if readiness should be skipped for this snapshot.
+function isReadinessDisabled(snapshotOptions = {}) {
+  let config = getReadinessConfig(snapshotOptions);
+  return (config === null || config === void 0 ? void 0 : config.preset) === 'disabled';
+}
+
+// Returns a JavaScript code string that SDKs evaluate in the browser
+// to run readiness checks BEFORE serialize.
+//
+// This is the READINESS-ONLY call. Serialize stays as a separate sync call.
+// The two-call pattern:
+//   1. await evaluate(waitForReadyScript(config))     — async, readiness
+//   2. evaluate('return PercyDOM.serialize(options)')  — sync, unchanged
+//
+// Usage:
+//   // Puppeteer/Playwright (page.evaluate auto-awaits):
+//   await page.evaluate(waitForReadyScript(config));
+//
+//   // Selenium (executeAsyncScript with callback):
+//   driver.execute_async_script(waitForReadyScript(config, { callback: true }));
+//
+// Graceful degradation:
+//   - If PercyDOM.waitForReady is not available (old CLI): resolves immediately
+//   - If waitForReady throws: resolves immediately (catch swallows the error)
+//   - If readiness times out: waitForReady resolves with { timed_out: true }
+//
+// IMPORTANT: The output is intended for CDP / executeScript / executeAsyncScript channels.
+// Do NOT inline this string into HTML — `</script>` sequences in user config would break out
+// of a <script> tag. SDK authors must add HTML escaping before any HTML-inline use.
+function waitForReadyScript(readinessConfig = {}, {
+  callback = false
+} = {}) {
+  // U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) are valid in JSON strings but
+  // were illegal in JS source string literals before ES2019. Escaping them keeps the emitted
+  // script source legal on older engines that may host the SDK eval.
+  let config = JSON.stringify(readinessConfig).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+  if (callback) {
+    // For executeAsyncScript — last argument is the callback
+    return `
+      var done = arguments[arguments.length - 1];
+      try {
+        if (typeof PercyDOM !== 'undefined' && typeof PercyDOM.waitForReady === 'function') {
+          PercyDOM.waitForReady(${config}).then(function(r) { done(r); }).catch(function() { done(); });
+        } else { done(); }
+      } catch(e) { done(); }
+    `;
+  }
+
+  // For page.evaluate (auto-await Promises)
+  return `
+    if (typeof PercyDOM !== 'undefined' && typeof PercyDOM.waitForReady === 'function') {
+      return PercyDOM.waitForReady(${config});
+    }
+  `;
+}
+var _default = exports.default = waitForReadyScript;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/sdk-utils",
-  "version": "1.31.14-beta.3",
+  "version": "1.31.14-beta.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -54,5 +54,5 @@
   "dependencies": {
     "pac-proxy-agent": "^7.0.2"
   },
-  "gitHead": "a17d4a1453c6bef282fd3da38082b670e125a5be"
+  "gitHead": "b52f1d2fb6272c0b3694e1e9ff584c5622a118c7"
 }