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

package/dist/bundle.js

@@ -326,6 +326,86 @@
       }
     }
 
+    // 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.
+    //
+    // MIRROR: must match @percy/dom/src/serialize-frames.js. The pair is kept
+    // duplicated (rather than imported across the package boundary) because the
+    // previous cross-package import broke Node 14 CI; the parity test below
+    // enforces alignment instead. Don't change one without changing the other.
+    const DEFAULT_MAX_IFRAME_DEPTH = 3;
+    const HARD_MAX_IFRAME_DEPTH = 10;
+    function clampIframeDepth(raw) {
+      const n = Number(raw);
+      if (!Number.isFinite(n) || n < 1) return DEFAULT_MAX_IFRAME_DEPTH;
+      return Math.min(Math.floor(n), HARD_MAX_IFRAME_DEPTH);
+    }
+
     var index = /*#__PURE__*/Object.freeze({
       __proto__: null,
       logger: logger,
@@ -340,15 +420,26 @@
       captureAutomateScreenshot: captureAutomateScreenshot,
       postBuildEvents: postBuildEvents,
       getResponsiveWidths: getResponsiveWidths,
+      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
     });
 
+    exports.DEFAULT_MAX_IFRAME_DEPTH = DEFAULT_MAX_IFRAME_DEPTH;
+    exports.HARD_MAX_IFRAME_DEPTH = HARD_MAX_IFRAME_DEPTH;
     exports.captureAutomateScreenshot = captureAutomateScreenshot;
+    exports.clampIframeDepth = clampIframeDepth;
     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;
@@ -356,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

@@ -3,12 +3,14 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.HARD_MAX_IFRAME_DEPTH = exports.DEFAULT_MAX_IFRAME_DEPTH = void 0;
 Object.defineProperty(exports, "captureAutomateScreenshot", {
   enumerable: true,
   get: function () {
     return _postScreenshot.default;
   }
 });
+exports.clampIframeDepth = clampIframeDepth;
 exports.default = void 0;
 Object.defineProperty(exports, "fetchPercyDOM", {
   enumerable: true,
@@ -22,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 () {
@@ -34,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 () {
@@ -76,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"));
@@ -88,8 +108,26 @@ 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); }
 function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// 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.
+//
+// MIRROR: must match @percy/dom/src/serialize-frames.js. The pair is kept
+// duplicated (rather than imported across the package boundary) because the
+// previous cross-package import broke Node 14 CI; the parity test below
+// enforces alignment instead. Don't change one without changing the other.
+const DEFAULT_MAX_IFRAME_DEPTH = exports.DEFAULT_MAX_IFRAME_DEPTH = 3;
+const HARD_MAX_IFRAME_DEPTH = exports.HARD_MAX_IFRAME_DEPTH = 10;
+function clampIframeDepth(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 1) return DEFAULT_MAX_IFRAME_DEPTH;
+  return Math.min(Math.floor(n), HARD_MAX_IFRAME_DEPTH);
+}
+
+// export the namespace by default

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.2",
+  "version": "1.31.14-beta.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -54,5 +54,5 @@
   "dependencies": {
     "pac-proxy-agent": "^7.0.2"
   },
-  "gitHead": "e4fce73023453b77cdef50aac1a9bd5eb70cd01a"
+  "gitHead": "b52f1d2fb6272c0b3694e1e9ff584c5622a118c7"
 }