@applitools/core 4.68.0 → 4.69.0

package/CHANGELOG.md

@@ -1,5 +1,209 @@
 # Changelog
 
+## [4.69.0](https://github.com/Applitools-Dev/sdk/compare/js/core@4.68.1...js/core@4.69.0) (2026-08-19)
+
+
+### Features
+
+* label and tag figma logs, warn that the feature is experimental | AD-15681 ([#4108](https://github.com/Applitools-Dev/sdk/issues/4108)) ([5b20bf3](https://github.com/Applitools-Dev/sdk/commit/5b20bf327a857f09b9d3b1d55d59976390fae9fb))
+
+
+### Bug Fixes
+
+* fail loudly when the Figma rate limit blocks further requests | AD-15531  ([#4065](https://github.com/Applitools-Dev/sdk/issues/4065)) ([9240e3e](https://github.com/Applitools-Dev/sdk/commit/9240e3ea6bed5225e8c9802cfb4669099968fc11))
+* report a stalled lazyLoad pass instead of success under a scroll lock | FLD-3965 ([#4101](https://github.com/Applitools-Dev/sdk/issues/4101)) ([6244790](https://github.com/Applitools-Dev/sdk/commit/62447903464d27027f169d6b058d20e3e943ffda))
+
+
+### Code Refactoring
+
+* make the figma logger and req explicit inputs | AD-15681 ([#4109](https://github.com/Applitools-Dev/sdk/issues/4109)) ([2a29778](https://github.com/Applitools-Dev/sdk/commit/2a2977865f1f26b0b55f7ab004c8ff737ed2573c))
+
+
+### Dependencies
+
+* @applitools/dom-snapshot bumped to 4.18.0
+  #### Features
+
+  * report canvases captured before they are drawn | FLD-3965 ([#4097](https://github.com/Applitools-Dev/sdk/issues/4097)) ([48b92ec](https://github.com/Applitools-Dev/sdk/commit/48b92ecba0804ad77333a6b4c799435d998f1418))
+
+
+
+* @applitools/snippets bumped to 2.9.7
+  #### Bug Fixes
+
+  * report a stalled lazyLoad pass instead of success under a scroll lock | FLD-3965 ([#4101](https://github.com/Applitools-Dev/sdk/issues/4101)) ([6244790](https://github.com/Applitools-Dev/sdk/commit/62447903464d27027f169d6b058d20e3e943ffda))
+* @applitools/nml-client bumped to 1.12.0
+  #### Features
+
+  * seat region-check DOM via NML crop targetRegion | AD-14690 ([#4054](https://github.com/Applitools-Dev/sdk/issues/4054)) ([d442ff3](https://github.com/Applitools-Dev/sdk/commit/d442ff336b66144b55102d04b74175305b05169e))
+
+
+
+* @applitools/driver bumped to 1.26.9
+
+* @applitools/spec-driver-webdriver bumped to 1.6.9
+
+* @applitools/spec-driver-selenium bumped to 1.8.9
+
+* @applitools/spec-driver-playwright bumped to 1.9.9
+
+* @applitools/spec-driver-puppeteer bumped to 1.8.9
+
+* @applitools/screenshoter bumped to 3.12.29
+
+* @applitools/ec-client bumped to 1.12.43
+
+
+## [4.68.1](https://github.com/Applitools-Dev/sdk/compare/js/core@4.68.0...js/core@4.68.1) (2026-08-10)
+
+
+### Bug Fixes
+
+* apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+* omit the empty os from the figma reference env so the design baseline persists | AD-15527 ([#4067](https://github.com/Applitools-Dev/sdk/issues/4067)) ([8395814](https://github.com/Applitools-Dev/sdk/commit/8395814feb6b20eee1c1322dc1539aa4642663d8))
+* use an authoritative CSS viewport in classic mode | FLD-4814 ([#4047](https://github.com/Applitools-Dev/sdk/issues/4047)) ([c46497e](https://github.com/Applitools-Dev/sdk/commit/c46497e573fd7fd2da4913452239beea082b148f))
+
+
+### Dependencies
+
+* @applitools/utils bumped to 1.15.2
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+* @applitools/logger bumped to 2.3.1
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/dom-shared bumped to 1.2.3
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+* @applitools/dom-snapshot bumped to 4.17.9
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/socket bumped to 1.3.16
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/req bumped to 1.11.3
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/image bumped to 1.3.1
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/snippets bumped to 2.9.6
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/dom-capture bumped to 11.8.5
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/driver bumped to 1.26.8
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+  * use an authoritative CSS viewport in classic mode | FLD-4814 ([#4047](https://github.com/Applitools-Dev/sdk/issues/4047)) ([c46497e](https://github.com/Applitools-Dev/sdk/commit/c46497e573fd7fd2da4913452239beea082b148f))
+
+
+
+* @applitools/spec-driver-webdriver bumped to 1.6.8
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/spec-driver-selenium bumped to 1.8.8
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/spec-driver-playwright bumped to 1.9.8
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/spec-driver-puppeteer bumped to 1.8.8
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/screenshoter bumped to 3.12.28
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/nml-client bumped to 1.11.40
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/tunnel-client bumped to 1.12.3
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/ufg-client bumped to 1.23.1
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/core-base bumped to 1.38.1
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/ec-client bumped to 1.12.42
+  #### Bug Fixes
+
+  * apply the figma UFG environments rewrite to the renders | AD-15528 ([#4072](https://github.com/Applitools-Dev/sdk/issues/4072)) ([bd6b143](https://github.com/Applitools-Dev/sdk/commit/bd6b143f855750ae93701f8e44da6129ff7ae84c))
+
+
+
+* @applitools/test-server bumped to 1.4.7
+
+
 ## [4.68.0](https://github.com/Applitools-Dev/sdk/compare/js/core@4.67.2...js/core@4.68.0) (2026-08-05)
 
 

package/dist/automation/utils/wait-for-lazy-load.js

@@ -6,7 +6,7 @@ async function waitForLazyLoad({ context, settings = {}, logger, }) {
     var _a;
     logger.log('Running scrolling sequence to lazy load a view content');
     const { scrollLength = 300, waitingTime = 2000, maxAmountToScroll = 15000 } = settings;
-    await context.executePoll(lazyLoad, {
+    const result = await context.executePoll(lazyLoad, {
         main: [
             await context.getScrollingElement(),
             {
@@ -19,5 +19,22 @@ async function waitForLazyLoad({ context, settings = {}, logger, }) {
         executionTimeout: 300000 /* 5min */,
         pollTimeout: (_a = settings.pollTimeout) !== null && _a !== void 0 ? _a : waitingTime,
     });
+    try {
+        const steps = Array.isArray(result) ? result : undefined;
+        const last = steps === null || steps === void 0 ? void 0 : steps[steps.length - 1];
+        if ((last === null || last === void 0 ? void 0 : last.reason) === 'stalled' || (last === null || last === void 0 ? void 0 : last.reason) === 'cappedAt') {
+            const coverage = `at ${last.maxScrollTop}px of ${last.maxScrollHeight}px`;
+            logger.console.log(last.reason === 'stalled'
+                ? `Lazy loading stopped early: the page stopped scrolling ${coverage}, ` +
+                    'which usually means something locked the page (for example a modal) while the content was being ' +
+                    'scrolled through. Content below that point may be missing from the captured page.'
+                : `Lazy loading stopped early: the scrolling attempt limit was reached ${coverage}. ` +
+                    'Content below that point may be missing from the captured page.');
+            logger.log('lazy load ended early', last);
+        }
+    }
+    catch (error) {
+        logger.log('Failed to inspect the lazy load result', error);
+    }
 }
 exports.waitForLazyLoad = waitForLazyLoad;

package/dist/check-and-close.js

@@ -26,10 +26,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeCheckAndClose = void 0;
 const driver_1 = require("@applitools/driver");
 const utils = __importStar(require("@applitools/utils"));
-function makeCheckAndClose({ type: defaultType = 'classic', eyes, target: defaultTarget, spec, logger: mainLogger, }) {
+function makeCheckAndClose({ type: defaultType = 'classic', eyes, target: defaultTarget, environments: openEnvironments, spec, logger: mainLogger, }) {
     return async function checkAndClose({ type = defaultType, target = defaultTarget, settings = {}, config, logger = mainLogger, } = {}) {
         logger = logger.extend(mainLogger, { tags: [`check-and-close-${type}-${utils.general.shortid()}`] });
+        // Same environments precedence as in check.ts.
+        const explicitEnvironments = settings != null && 'environments' in settings;
         settings = { ...config === null || config === void 0 ? void 0 : config.screenshot, ...config === null || config === void 0 ? void 0 : config.check, ...config === null || config === void 0 ? void 0 : config.close, ...settings };
+        if (type === 'ufg' && (openEnvironments === null || openEnvironments === void 0 ? void 0 : openEnvironments.length) && !explicitEnvironments) {
+            ;
+            settings.environments = openEnvironments;
+        }
         const driver = (0, driver_1.isDriver)(target, spec)
             ? await (0, driver_1.makeDriver)({ spec, driver: target, reset: target === defaultTarget, logger })
             : null;

package/dist/check.js

@@ -32,13 +32,20 @@ const defaults_1 = require("./automation/utils/defaults");
 const utils = __importStar(require("@applitools/utils"));
 const lang = __importStar(require("./lang"));
 const chalk_1 = __importDefault(require("chalk"));
-function makeCheck({ type: defaultType = 'classic', eyes, target: defaultTarget, spec, logger: mainLogger, }) {
+function makeCheck({ type: defaultType = 'classic', eyes, target: defaultTarget, environments: openEnvironments, spec, logger: mainLogger, }) {
     let stepIndex = 0;
     return async function check({ type = defaultType, target = defaultTarget, settings, config, logger = mainLogger, } = {}) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
         var _t, _u, _v, _w, _x;
         logger = logger.extend(mainLogger, { tags: [`check-${type}-${utils.general.shortid()}`] });
+        // Open-time environments (possibly rewritten by the figma seam) win over the config's per-check
+        // re-send; environments passed explicitly to this call win over both.
+        const explicitEnvironments = settings != null && 'environments' in settings;
         settings = { ...config === null || config === void 0 ? void 0 : config.screenshot, ...config === null || config === void 0 ? void 0 : config.check, ...settings };
+        if (type === 'ufg' && (openEnvironments === null || openEnvironments === void 0 ? void 0 : openEnvironments.length) && !explicitEnvironments) {
+            ;
+            settings.environments = openEnvironments;
+        }
         (_a = settings.fully) !== null && _a !== void 0 ? _a : (settings.fully = !settings.region && (!settings.frames || settings.frames.length === 0));
         (_b = settings.waitBeforeCapture) !== null && _b !== void 0 ? _b : (settings.waitBeforeCapture = defaults_1.DEFAULT_WAIT_BEFORE_CAPTURE);
         (_c = settings.hideScrollbars) !== null && _c !== void 0 ? _c : (settings.hideScrollbars = true);

package/dist/classic/utils/extract-default-environments.js

@@ -34,8 +34,23 @@ async function extractDefaultEnvironments({ driver, settings, }) {
     try {
         const driverEnvironment = await driver.getEnvironment();
         const viewport = await driver.getViewport();
-        // scale layout viewport by visualViewport.scale to get visible CSS viewport (avoids double-scaling spec drivers that already return CSS pixels)
-        environment.viewportSize = utils.geometry.scale(viewport.viewportSize, viewport.viewportScale);
+        // The reported viewport is part of the baseline key: it must stay identical to the historical
+        // derivation (`layout viewport × visualViewport.scale`) for every viewport already reported
+        // correctly (FLD-4359). The framework-reported CSS viewport may substitute only to correct
+        // sub-pixel rounding noise in that derivation (FLD-4814): integral on both axes, within < 1px
+        // per axis, and viewportScale <= 1 — the residue bound the backward-compatibility proof depends
+        // on. The value must come from getCssViewportSize(), never getViewportSize(), whose fallback is
+        // the unscaled layout viewport. Full derivation, proof and history: llm-docs/CLASSIC.md →
+        // Reported viewport.
+        const derivedViewportSize = utils.geometry.scale(viewport.viewportSize, viewport.viewportScale);
+        const cssViewportSize = await driver.getCssViewportSize();
+        const corroboratesDerivedSize = !!cssViewportSize &&
+            viewport.viewportScale <= 1 &&
+            Number.isInteger(cssViewportSize.width) &&
+            Number.isInteger(cssViewportSize.height) &&
+            Math.abs(cssViewportSize.width - derivedViewportSize.width) < 1 &&
+            Math.abs(cssViewportSize.height - derivedViewportSize.height) < 1;
+        environment.viewportSize = corroboratesDerivedSize ? cssViewportSize : derivedViewportSize;
         environment.environmentId = utils.general.guid();
         if (driverEnvironment.isEC)
             environment.ecSessionId = (_a = (await driver.getSessionId())) !== null && _a !== void 0 ? _a : undefined;

package/dist/figma/client/figma-req.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.makeFigmaReq = exports.FIGMA_API = void 0;
+exports.makeFigmaReq = exports.figmaRateLimitMessage = exports.parseRetryAfterSeconds = exports.DEFAULT_MAX_RATE_LIMIT_WAIT_SECONDS = exports.FIGMA_API = void 0;
 // The Figma REST transport: `@applitools/req` configured for Figma's rate limits.
 const req_1 = require("@applitools/req");
 exports.FIGMA_API = 'https://api.figma.com/v1';
@@ -9,7 +9,42 @@ exports.FIGMA_API = 'https://api.figma.com/v1';
 const RETRY_LIMIT = 5;
 // Only used when Figma omits `Retry-After`.
 const RETRY_BACKOFF_MS = [1000, 2000, 5000, 10000];
-function makeFigmaReq({ proxy, logger, maxRateLimitWaitSeconds = 60 } = {}) {
+exports.DEFAULT_MAX_RATE_LIMIT_WAIT_SECONDS = 60;
+/** Undefined when Figma sent no `Retry-After`, or one this doesn't parse (e.g. an HTTP-date). */
+function parseRetryAfterSeconds(headers) {
+    const seconds = Number(headers.get('Retry-After'));
+    return headers.has('Retry-After') && Number.isFinite(seconds) ? seconds : undefined;
+}
+exports.parseRetryAfterSeconds = parseRetryAfterSeconds;
+/**
+ * The single wording for "Figma throttled us and we stopped trying", shared by the log line here and by
+ * the errors `figma-rest` throws — a user who sees only one of the two still gets the whole cause.
+ */
+function figmaRateLimitMessage(ending, maxRateLimitWaitSeconds) {
+    const budget = `${maxRateLimitWaitSeconds}s wait budget (figmaOptions.maxRateLimitWaitSeconds)`;
+    let cause;
+    switch (ending.reason) {
+        case 'retry-after-over-budget':
+            cause =
+                `Figma's Retry-After asked for ${ending.retryAfterSeconds}s, over the ${budget}, so no retry was ` +
+                    `attempted. Raising that budget only helps for short waits — a Retry-After of hours or days cannot ` +
+                    `be waited out.`;
+            break;
+        case 'wait-budget-exhausted':
+            cause = `retrying consumed the ${budget}. A larger budget can help when Figma's Retry-After is short.`;
+            break;
+        case 'attempts-exhausted':
+            cause =
+                `Figma was still throttling after the retry limit of ${RETRY_LIMIT} attempts, which is not ` +
+                    `configurable — raising the ${budget} does not change it.`;
+            break;
+    }
+    return (`Figma API rate limit (HTTP 429): ${cause} Rerun against a warm on-disk Figma cache ` +
+        `(figmaOptions.tempPath / APPLITOOLS_FIGMA_TEMP_PATH — an earlier run must have populated it, and ` +
+        `figmaOptions.nodesCacheTtlSeconds must still cover it), or use a token that is not throttled.`);
+}
+exports.figmaRateLimitMessage = figmaRateLimitMessage;
+function makeFigmaReq({ proxy, logger, maxRateLimitWaitSeconds = exports.DEFAULT_MAX_RATE_LIMIT_WAIT_SECONDS, } = {}) {
     const maxWaitMs = maxRateLimitWaitSeconds * 1000;
     return (0, req_1.makeReq)({
         proxy,
@@ -26,17 +61,19 @@ function makeFigmaReq({ proxy, logger, maxRateLimitWaitSeconds = 60 } = {}) {
             validate: ({ response }) => {
                 if ((response === null || response === void 0 ? void 0 : response.status) !== 429)
                     return false;
-                const retryAfterMs = Number(response.headers.get('Retry-After')) * 1000;
-                // Unparseable (e.g. an HTTP-date) reads as NaN: retry on the backoff schedule rather than trust it.
-                if (!Number.isFinite(retryAfterMs))
+                // No duration to weigh against the budget, so retry: on the backoff schedule when Figma sent no
+                // `Retry-After` at all, but immediately when it sent one this can't parse — req reads the header
+                // itself and turns an unparseable value into a NaN delay. Tracked in AD-15577.
+                const retryAfterSeconds = parseRetryAfterSeconds(response.headers);
+                if (retryAfterSeconds === undefined)
                     return true;
-                if (retryAfterMs > maxWaitMs) {
-                    logger === null || logger === void 0 ? void 0 : logger.log(`Figma rate limit — Retry-After of ${retryAfterMs / 1000}s exceeds the ${maxRateLimitWaitSeconds}s budget; giving up.`);
+                if (retryAfterSeconds > maxRateLimitWaitSeconds) {
+                    logger === null || logger === void 0 ? void 0 : logger.error(figmaRateLimitMessage({ reason: 'retry-after-over-budget', retryAfterSeconds }, maxRateLimitWaitSeconds));
                     return false;
                 }
                 // Logged here because `beforeRetry` fires only after the sleep, leaving a long wait unexplained.
-                if (retryAfterMs > 0)
-                    logger === null || logger === void 0 ? void 0 : logger.log(`Figma rate limit — waiting ${retryAfterMs / 1000}s before retry...`);
+                if (retryAfterSeconds > 0)
+                    logger === null || logger === void 0 ? void 0 : logger.log(`Figma rate limit — waiting ${retryAfterSeconds}s before retry...`);
                 return true;
             },
         },

package/dist/figma/client/figma-rest.js

@@ -32,6 +32,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const buffer_1 = require("buffer");
+const req_1 = require("@applitools/req");
 const utils_1 = require("../utils");
 const figma_req_1 = require("./figma-req");
 const DEFAULT_NODES_CACHE_TTL_SECONDS = 120;
@@ -54,8 +55,34 @@ function figmaImageCacheFileName(fileId, nodeId, lastModifiedUnix) {
     return `figma-image-${hash}.png`;
 }
 exports.figmaImageCacheFileName = figmaImageCacheFileName;
-async function figmaGet(req, endpoint, accessToken) {
-    const response = await req(`${figma_req_1.FIGMA_API}${endpoint}`, {
+/**
+ * Every `req` call in this file goes through here — the Figma API legs and the CDN image download alike.
+ * A terminal rate limit surfaces two ways, neither of which carries a diagnosis of its own, and each
+ * caller's own status message would bury it.
+ */
+async function figmaFetch(req, url, maxRateLimitWaitSeconds, init = {}) {
+    const response = await req(url, init).catch(error => {
+        // Waits that each fit the budget but together outlast it end here: req abandons the retry loop
+        // itself, so no 429 response is left to read. `name` rather than `instanceof` alone so an injected
+        // `opts.req` or a duplicated req copy still matches. `cause` keeps req's own error (and its
+        // `RETRY_DURATION_EXCEEDED` code) reachable — `Error`'s two-argument form is not typed at es2019.
+        if (error instanceof req_1.RetryTimeoutError || (error === null || error === void 0 ? void 0 : error.name) === 'RetryTimeoutError') {
+            throw Object.assign(new Error((0, figma_req_1.figmaRateLimitMessage)({ reason: 'wait-budget-exhausted' }, maxRateLimitWaitSeconds)), { cause: error });
+        }
+        throw error;
+    });
+    if (response.status === 429) {
+        // The retry policy in ./figma-req refuses an over-budget `Retry-After` outright and otherwise stops at
+        // the attempt limit. Which of the two happened decides what the user can do about it.
+        const retryAfterSeconds = (0, figma_req_1.parseRetryAfterSeconds)(response.headers);
+        throw new Error((0, figma_req_1.figmaRateLimitMessage)(retryAfterSeconds !== undefined && retryAfterSeconds > maxRateLimitWaitSeconds
+            ? { reason: 'retry-after-over-budget', retryAfterSeconds }
+            : { reason: 'attempts-exhausted' }, maxRateLimitWaitSeconds));
+    }
+    return response;
+}
+async function figmaGet(req, endpoint, accessToken, maxRateLimitWaitSeconds) {
+    const response = await figmaFetch(req, `${figma_req_1.FIGMA_API}${endpoint}`, maxRateLimitWaitSeconds, {
         headers: { 'X-Figma-Token': accessToken },
     });
     if (!response.ok) {
@@ -94,7 +121,7 @@ async function fetchFigmaFileNodes(urls, accessToken, opts) {
                 throw new Error(`APPLITOOLS_FIGMA_SKIP_API is set but no nodes cache found at ${nodesFilePath}`);
             }
             const ids = uniqueNodeIds.map(id => encodeURIComponent(id)).join(',');
-            nodesResp = await figmaGet(opts.req, `/files/${fileId}/nodes?ids=${ids}`, accessToken);
+            nodesResp = await figmaGet(opts.req, `/files/${fileId}/nodes?ids=${ids}`, accessToken, opts.maxRateLimitWaitSeconds);
             fs.writeFileSync(nodesFilePath, JSON.stringify(nodesResp));
         }
         resolved.push({ fileId, nodesResp, nodes });
@@ -124,20 +151,23 @@ function metadataFromNodesResp(nodesResp, fileId, nodeId) {
 function resolveRestOptions(opts) {
     var _a, _b, _c, _d;
     return {
-        tempPath: (_a = opts === null || opts === void 0 ? void 0 : opts.tempPath) !== null && _a !== void 0 ? _a : os.tmpdir(),
-        ttlSeconds: (_b = opts === null || opts === void 0 ? void 0 : opts.nodesCacheTtlSeconds) !== null && _b !== void 0 ? _b : DEFAULT_NODES_CACHE_TTL_SECONDS,
-        skipApi: (_c = opts === null || opts === void 0 ? void 0 : opts.skipApi) !== null && _c !== void 0 ? _c : false,
-        req: (_d = opts === null || opts === void 0 ? void 0 : opts.req) !== null && _d !== void 0 ? _d : (0, figma_req_1.makeFigmaReq)({
-            proxy: opts === null || opts === void 0 ? void 0 : opts.proxy,
-            logger: opts === null || opts === void 0 ? void 0 : opts.logger,
-            maxRateLimitWaitSeconds: opts === null || opts === void 0 ? void 0 : opts.maxRateLimitWaitSeconds,
-        }),
+        tempPath: (_a = opts.tempPath) !== null && _a !== void 0 ? _a : os.tmpdir(),
+        ttlSeconds: (_b = opts.nodesCacheTtlSeconds) !== null && _b !== void 0 ? _b : DEFAULT_NODES_CACHE_TTL_SECONDS,
+        skipApi: (_c = opts.skipApi) !== null && _c !== void 0 ? _c : false,
+        maxRateLimitWaitSeconds: (_d = opts.maxRateLimitWaitSeconds) !== null && _d !== void 0 ? _d : figma_req_1.DEFAULT_MAX_RATE_LIMIT_WAIT_SECONDS,
+        req: opts.req,
     };
 }
 // No /images render or PNG download — `test-baseline` mode sizes the viewport from metadata alone.
 async function fetchFigmaMetadata(urls, accessToken, opts) {
-    const { tempPath, ttlSeconds, skipApi, req } = resolveRestOptions(opts);
-    const fileGroups = await fetchFigmaFileNodes(urls, accessToken, { tempPath, ttlSeconds, skipApi, req });
+    const { tempPath, ttlSeconds, skipApi, req, maxRateLimitWaitSeconds } = resolveRestOptions(opts);
+    const fileGroups = await fetchFigmaFileNodes(urls, accessToken, {
+        tempPath,
+        ttlSeconds,
+        skipApi,
+        req,
+        maxRateLimitWaitSeconds,
+    });
     const results = new Array(urls.length);
     for (const { fileId, nodesResp, nodes } of fileGroups) {
         for (const { nodeId, urlIndex } of nodes) {
@@ -148,9 +178,8 @@ async function fetchFigmaMetadata(urls, accessToken, opts) {
 }
 exports.fetchFigmaMetadata = fetchFigmaMetadata;
 async function fetchFigmaImages(urls, accessToken, opts) {
-    const { tempPath, skipApi, req } = resolveRestOptions(opts);
-    // Pass `req` through so an injected stub or proxy applies to the /nodes leg too.
-    const metadataList = await fetchFigmaMetadata(urls, accessToken, { ...opts, req });
+    const { tempPath, skipApi, req, maxRateLimitWaitSeconds } = resolveRestOptions(opts);
+    const metadataList = await fetchFigmaMetadata(urls, accessToken, opts);
     const results = new Array(urls.length);
     for (const [fileId, nodes] of groupByFile(urls)) {
         const uniqueNodeIds = [...new Set(nodes.map(n => n.nodeId))].sort();
@@ -165,7 +194,7 @@ async function fetchFigmaImages(urls, accessToken, opts) {
                 throw new Error(`APPLITOOLS_FIGMA_SKIP_API is set but no image cache found for node ${missNodeIds[0]} in file ${fileId}`);
             }
             const ids = missNodeIds.map(id => encodeURIComponent(id)).join(',');
-            const imagesResp = await figmaGet(req, `/images/${fileId}?ids=${ids}&format=png&scale=1`, accessToken);
+            const imagesResp = await figmaGet(req, `/images/${fileId}?ids=${ids}&format=png&scale=1`, accessToken, maxRateLimitWaitSeconds);
             await Promise.all(missNodeIds.map(async (nodeId) => {
                 var _a;
                 const imageUrl = (_a = imagesResp.images) === null || _a === void 0 ? void 0 : _a[nodeId];
@@ -173,7 +202,7 @@ async function fetchFigmaImages(urls, accessToken, opts) {
                     throw new Error(`No image URL returned for node "${nodeId}"`);
                 }
                 // The CDN URL is pre-signed and carries no Figma token — no auth header here.
-                const imageResponse = await req(imageUrl);
+                const imageResponse = await figmaFetch(req, imageUrl, maxRateLimitWaitSeconds);
                 if (!imageResponse.ok) {
                     throw new Error(`Failed to download Figma image: HTTP ${imageResponse.status}`);
                 }

package/dist/figma/client/index.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 // The Figma REST client: transport configuration (./figma-req) plus the batched /nodes + /images calls
-// and their disk caches (./figma-rest). Takes logger, proxy, token, skipApi and cache settings as inputs —
-// it reads no environment of its own.
+// and their disk caches (./figma-rest). Takes the `req` instance, token, skipApi and cache settings as
+// inputs — it reads no environment of its own.
 __exportStar(require("./figma-req"), exports);
 __exportStar(require("./figma-rest"), exports);

package/dist/figma/figma.js

@@ -22,6 +22,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setFigmaBaseline = exports.setFigmaBaselineFlow = void 0;
 // Figma baseline resolver (AD-14881): orchestration only, operating directly on core's OpenSettings
@@ -34,7 +37,18 @@ const target_config_1 = require("./target-config");
 const client_1 = require("./client");
 const figma_images_1 = require("./figma-images");
 const run_figma_check_1 = require("./run-figma-check");
-async function setFigmaBaselineFlow(figmaUrls, originalConfig, deps, mode = 'auto-baseline', viewportOpts = {}, logger = (0, logger_1.makeLogger)()) {
+const lang = __importStar(require("../lang"));
+const chalk_1 = __importDefault(require("chalk"));
+let experimentalWarned = false;
+function warnExperimental(logger) {
+    logger.warn(lang.figmaExperimentalWarning);
+    // The console copy is once per process — a storybook run resolves a design per story.
+    if (experimentalWarned)
+        return;
+    experimentalWarned = true;
+    logger.console.warn(chalk_1.default.yellow(lang.figmaExperimentalWarning));
+}
+async function setFigmaBaselineFlow(figmaUrls, originalConfig, deps, logger, mode = 'auto-baseline', viewportOpts = {}) {
     var _a, _b;
     const maxViewportHeight = (_a = viewportOpts.maxViewportHeight) !== null && _a !== void 0 ? _a : target_config_1.DEFAULT_MAX_VIEWPORT_HEIGHT;
     const minViewportSize = (_b = viewportOpts.minViewportSize) !== null && _b !== void 0 ? _b : null;
@@ -105,7 +119,7 @@ async function setFigmaBaselineFlow(figmaUrls, originalConfig, deps, mode = 'aut
         batch: originalConfig.batch,
         appName: originalConfig.appName,
         testName: originalConfig.testName,
-        environment: { hostingApp: 'Figma', os: '', viewportSize: figmaViewport },
+        environment: { hostingApp: 'Figma', viewportSize: figmaViewport },
         properties: (0, utils_1.figmaMetadataToProperties)(realResults[0].metadata, mode),
         baselineEnvName: figmaEnvName,
         saveNewTests: true,
@@ -124,9 +138,8 @@ async function setFigmaBaselineFlow(figmaUrls, originalConfig, deps, mode = 'aut
     return (0, target_config_1.buildTargetTestConfig)(originalConfig, realResults[0].metadata, figmaViewport, { figmaEnvName, useLatestEnvBaseline: mode === 'auto-baseline' }, mode);
 }
 exports.setFigmaBaselineFlow = setFigmaBaselineFlow;
-async function setFigmaBaseline(configuration, figmaBaselines, opts) {
-    var _a;
-    const logger = (_a = opts === null || opts === void 0 ? void 0 : opts.logger) !== null && _a !== void 0 ? _a : (0, logger_1.makeLogger)();
+async function setFigmaBaseline(configuration, figmaBaselines, logger, opts) {
+    logger = (0, logger_1.makeLogger)({ logger, format: { label: 'figma' } });
     const mode = (0, utils_1.resolveFigmaMode)(opts === null || opts === void 0 ? void 0 : opts.mode);
     if (mode === 'disabled') {
         logger.log('setFigmaBaseline: disabled (APPLITOOLS_FIGMA_MODE=disabled) — skipping.');
@@ -145,9 +158,9 @@ async function setFigmaBaseline(configuration, figmaBaselines, opts) {
         nodesCacheTtlSeconds: opts === null || opts === void 0 ? void 0 : opts.nodesCacheTtlSeconds,
         maxRateLimitWaitSeconds: opts === null || opts === void 0 ? void 0 : opts.maxRateLimitWaitSeconds,
         skipApi: opts === null || opts === void 0 ? void 0 : opts.skipApi,
-        proxy: opts === null || opts === void 0 ? void 0 : opts.proxy,
-        req: opts === null || opts === void 0 ? void 0 : opts.req,
-        logger,
+        // The instance enforces the wait budget and figma-rest names it in the error, so both are given
+        // the same value — unset, they fall back to the one DEFAULT_MAX_RATE_LIMIT_WAIT_SECONDS.
+        req: (0, client_1.makeFigmaReq)({ proxy: opts === null || opts === void 0 ? void 0 : opts.proxy, logger, maxRateLimitWaitSeconds: opts === null || opts === void 0 ? void 0 : opts.maxRateLimitWaitSeconds }),
     };
     const deps = {
         fetchFigmaImages: urlList => (0, client_1.fetchFigmaImages)(urlList, getToken(), restOpts),
@@ -159,10 +172,11 @@ async function setFigmaBaseline(configuration, figmaBaselines, opts) {
     const figmaUrls = (0, utils_1.resolveFigmaUrls)(figmaBaselines, configuration.testName);
     if (figmaUrls === null)
         return;
-    const updated = await setFigmaBaselineFlow(figmaUrls, configuration, deps, mode, {
+    warnExperimental(logger);
+    const updated = await setFigmaBaselineFlow(figmaUrls, configuration, deps, logger, mode, {
         maxViewportHeight: opts === null || opts === void 0 ? void 0 : opts.maxViewportHeight,
         minViewportSize: opts === null || opts === void 0 ? void 0 : opts.minViewportSize,
-    }, logger);
+    });
     Object.assign(configuration, updated);
 }
 exports.setFigmaBaseline = setFigmaBaseline;

package/dist/figma/seam.js

@@ -45,6 +45,7 @@ async function applyFigmaBaselines(settings, logger, resolve = figma_1.setFigmaB
         delete settings.figmaOptions;
         return;
     }
+    logger = logger.extend({ label: 'figma', tags: [`figma-${utils.general.shortid()}`] });
     try {
         // A shared open config applies to every test, so an unmapped test must not fail — only skip.
         if (typeof figmaBaselines !== 'string' && figmaBaselines[settings.testName] === undefined) {
@@ -63,8 +64,7 @@ async function applyFigmaBaselines(settings, logger, resolve = figma_1.setFigmaB
         const accessToken = (_e = figmaOptions.accessToken) !== null && _e !== void 0 ? _e : process.env.FIGMA_ACCESS_TOKEN;
         if (accessToken)
             logger.mask(accessToken);
-        await resolve(settings, figmaBaselines, {
-            logger,
+        await resolve(settings, figmaBaselines, logger, {
             skipApi,
             mode: (0, utils_1.resolveFigmaMode)((_f = figmaOptions.mode) !== null && _f !== void 0 ? _f : utils.general.getEnvValue('FIGMA_MODE')),
             accessToken,

package/dist/lang.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applitoolsLibConflictingCapabilitiesWarning = exports.requestedEnvironmentOutOfDriverBoundsWarning = exports.breakpointOutOfDriverBoundsWarning = exports.requestedEnvironmentSmallerThenBreakpointWarning = exports.outdatedSdkVersionWarning = exports.edgeUfgEnvironmentDeprecatedWarning = exports.matchLevelContentDeprecatedWarning = void 0;
+exports.applitoolsLibConflictingCapabilitiesWarning = exports.requestedEnvironmentOutOfDriverBoundsWarning = exports.breakpointOutOfDriverBoundsWarning = exports.requestedEnvironmentSmallerThenBreakpointWarning = exports.outdatedSdkVersionWarning = exports.figmaExperimentalWarning = exports.edgeUfgEnvironmentDeprecatedWarning = exports.matchLevelContentDeprecatedWarning = void 0;
 exports.matchLevelContentDeprecatedWarning = `The "Content" match level value has been deprecated, use "IgnoreColors" instead.`;
 exports.edgeUfgEnvironmentDeprecatedWarning = `The 'edge' option that is being used in your browsers' configuration will soon be deprecated. Please change it to either 'edgelegacy' for the legacy version or to 'edgechromium' for the new Chromium-based version. Please note, when using the built-in BrowserType enum, then the values are BrowserType.EDGE_LEGACY and BrowserType.EDGE_CHROMIUM, respectively.`;
+exports.figmaExperimentalWarning = `Figma support is experimental. It is not officially supported and may change or be removed in a future release.`;
 const outdatedSdkVersionWarning = (options) => {
     return `You are using "${options.currentVersion}" and there is a newer version "${options.latestVersion}" of the "${options.name}" SDK.`;
 };

package/dist/open-eyes.js

@@ -184,8 +184,8 @@ function makeOpenEyes({ type: defaultType = 'classic', clients, batch, removeDup
             var _a, _b;
             return ({
                 getTypedEyes,
-                check: (0, check_1.makeCheck)({ type, eyes, target: driver, spec, logger }),
-                checkAndClose: (0, check_and_close_1.makeCheckAndClose)({ type, eyes, target: driver, spec, logger }),
+                check: (0, check_1.makeCheck)({ type, eyes, target: driver, environments: settings.environments, spec, logger }),
+                checkAndClose: (0, check_and_close_1.makeCheckAndClose)({ type, eyes, target: driver, environments: settings.environments, spec, logger }),
                 close: (0, close_1.makeClose)({ eyes, environments: (_a = config === null || config === void 0 ? void 0 : config.check) === null || _a === void 0 ? void 0 : _a.environments, logger }),
                 abort: (0, abort_1.makeAbort)({ eyes, environments: (_b = config === null || config === void 0 ? void 0 : config.check) === null || _b === void 0 ? void 0 : _b.environments, logger }),
                 getResults: (0, get_eyes_results_1.makeGetEyesResults)({ eyes, logger }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/core",
-  "version": "4.68.0",
+  "version": "4.69.0",
   "homepage": "https://applitools.com",
   "bugs": {
     "url": "https://github.com/applitools/eyes.sdk.javascript1/issues"
@@ -61,20 +61,20 @@
     "setup:standalone": "sh -c 'yarn chromedriver --port=4444 --verbose &'"
   },
   "dependencies": {
-    "@applitools/core-base": "1.38.0",
-    "@applitools/dom-capture": "11.8.4",
-    "@applitools/dom-snapshot": "4.17.8",
-    "@applitools/driver": "1.26.7",
-    "@applitools/ec-client": "1.12.41",
-    "@applitools/image": "1.3.0",
-    "@applitools/logger": "2.3.0",
-    "@applitools/nml-client": "1.11.39",
-    "@applitools/req": "1.11.2",
-    "@applitools/screenshoter": "3.12.27",
-    "@applitools/snippets": "2.9.5",
-    "@applitools/socket": "1.3.15",
-    "@applitools/ufg-client": "1.23.0",
-    "@applitools/utils": "1.15.1",
+    "@applitools/core-base": "1.38.1",
+    "@applitools/dom-capture": "11.8.5",
+    "@applitools/dom-snapshot": "4.18.0",
+    "@applitools/driver": "1.26.9",
+    "@applitools/ec-client": "1.12.43",
+    "@applitools/image": "1.3.1",
+    "@applitools/logger": "2.3.1",
+    "@applitools/nml-client": "1.12.0",
+    "@applitools/req": "1.11.3",
+    "@applitools/screenshoter": "3.12.29",
+    "@applitools/snippets": "2.9.7",
+    "@applitools/socket": "1.3.16",
+    "@applitools/ufg-client": "1.23.1",
+    "@applitools/utils": "1.15.2",
     "abort-controller": "3.0.0",
     "chalk": "4.1.2",
     "node-fetch": "2.6.7",
@@ -84,13 +84,13 @@
   },
   "devDependencies": {
     "@applitools/bongo": "^5.10.0",
-    "@applitools/spec-driver-playwright": "^1.9.7",
-    "@applitools/spec-driver-puppeteer": "^1.8.7",
-    "@applitools/spec-driver-selenium": "^1.8.7",
-    "@applitools/spec-driver-webdriver": "^1.6.7",
-    "@applitools/test-server": "^1.4.6",
+    "@applitools/spec-driver-playwright": "^1.9.9",
+    "@applitools/spec-driver-puppeteer": "^1.8.9",
+    "@applitools/spec-driver-selenium": "^1.8.9",
+    "@applitools/spec-driver-webdriver": "^1.6.9",
+    "@applitools/test-server": "^1.4.7",
     "@applitools/test-utils": "^1.5.17",
-    "@applitools/tunnel-client": "^1.12.2",
+    "@applitools/tunnel-client": "^1.12.3",
     "@swc-node/register": "^1.6.8",
     "@types/mocha": "^10.0.7",
     "@types/node": "^12.20.55",

package/types/check-and-close.d.ts

@@ -1,14 +1,15 @@
-import type { Target, DriverTarget, Eyes, Config, CheckSettings, CloseSettings } from './types';
+import type { Target, DriverTarget, Eyes, Config, CheckSettings, CloseSettings, Environment } from './types';
 import { type Logger } from '@applitools/logger';
 import { type SpecType, type SpecDriver } from '@applitools/driver';
 type Options<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = {
     type?: TType;
     eyes: Eyes<TSpec, TType>;
     target?: DriverTarget<TSpec>;
+    environments?: Environment[];
     spec?: SpecDriver<TSpec>;
     logger: Logger;
 };
-export declare function makeCheckAndClose<TSpec extends SpecType, TDefaultType extends 'classic' | 'ufg'>({ type: defaultType, eyes, target: defaultTarget, spec, logger: mainLogger, }: Options<TSpec, TDefaultType>): <TType extends "classic" | "ufg" = TDefaultType>({ type, target, settings, config, logger, }?: {
+export declare function makeCheckAndClose<TSpec extends SpecType, TDefaultType extends 'classic' | 'ufg'>({ type: defaultType, eyes, target: defaultTarget, environments: openEnvironments, spec, logger: mainLogger, }: Options<TSpec, TDefaultType>): <TType extends "classic" | "ufg" = TDefaultType>({ type, target, settings, config, logger, }?: {
     type?: TType | undefined;
     target?: Target<TSpec, TType> | undefined;
     settings?: (CheckSettings<TSpec, TDefaultType> & CloseSettings<TDefaultType> & CheckSettings<TSpec, TType> & CloseSettings<TType>) | undefined;

package/types/check.d.ts

@@ -1,14 +1,15 @@
-import type { Target, DriverTarget, Eyes, Config, CheckSettings } from './types';
+import type { Target, DriverTarget, Eyes, Config, CheckSettings, Environment } from './types';
 import { type Logger } from '@applitools/logger';
 import { type SpecType, type SpecDriver } from '@applitools/driver';
 type Options<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = {
     type?: TType;
     eyes: Eyes<TSpec, TType>;
     target?: DriverTarget<TSpec>;
+    environments?: Environment[];
     spec?: SpecDriver<TSpec>;
     logger: Logger;
 };
-export declare function makeCheck<TSpec extends SpecType, TDefaultType extends 'classic' | 'ufg'>({ type: defaultType, eyes, target: defaultTarget, spec, logger: mainLogger, }: Options<TSpec, TDefaultType>): <TType extends "classic" | "ufg" = TDefaultType>({ type, target, settings, config, logger, }?: {
+export declare function makeCheck<TSpec extends SpecType, TDefaultType extends 'classic' | 'ufg'>({ type: defaultType, eyes, target: defaultTarget, environments: openEnvironments, spec, logger: mainLogger, }: Options<TSpec, TDefaultType>): <TType extends "classic" | "ufg" = TDefaultType>({ type, target, settings, config, logger, }?: {
     type?: TType | undefined;
     target?: Target<TSpec, TType> | undefined;
     settings?: CheckSettings<TSpec, TType> | undefined;

package/types/figma/client/figma-req.d.ts

@@ -1,9 +1,35 @@
-import { type Req, type Proxy } from '@applitools/req';
+import { type Req, type Proxy, type Headers } from '@applitools/req';
 import { type Logger } from '@applitools/logger';
 export declare const FIGMA_API = "https://api.figma.com/v1";
+export declare const DEFAULT_MAX_RATE_LIMIT_WAIT_SECONDS = 60;
+/** Undefined when Figma sent no `Retry-After`, or one this doesn't parse (e.g. an HTTP-date). */
+export declare function parseRetryAfterSeconds(headers: Headers): number | undefined;
+/**
+ * Retrying a 429 can end three ways, and they have different remedies — the wait budget is the binding
+ * constraint in only two of them. Whoever observes the ending names it; nothing infers it after the fact.
+ */
+export type FigmaRateLimitEnding = 
+/** Figma asked for longer than the budget allows, so no retry was attempted. */
+{
+    reason: 'retry-after-over-budget';
+    retryAfterSeconds: number;
+}
+/** Retried up to the attempt limit and Figma was still throttling. */
+ | {
+    reason: 'attempts-exhausted';
+}
+/** The waits themselves consumed the budget, so `req` abandoned the retry loop. */
+ | {
+    reason: 'wait-budget-exhausted';
+};
+/**
+ * The single wording for "Figma throttled us and we stopped trying", shared by the log line here and by
+ * the errors `figma-rest` throws — a user who sees only one of the two still gets the whole cause.
+ */
+export declare function figmaRateLimitMessage(ending: FigmaRateLimitEnding, maxRateLimitWaitSeconds: number): string;
 export type FigmaReqOptions = {
     proxy?: Proxy;
     logger?: Logger;
     maxRateLimitWaitSeconds?: number;
 };
-export declare function makeFigmaReq({ proxy, logger, maxRateLimitWaitSeconds }?: FigmaReqOptions): Req;
+export declare function makeFigmaReq({ proxy, logger, maxRateLimitWaitSeconds, }?: FigmaReqOptions): Req;

package/types/figma/client/figma-rest.d.ts

@@ -1,16 +1,13 @@
-import { type Logger } from '@applitools/logger';
-import type { Proxy, Req } from '@applitools/req';
+import { type Req } from '@applitools/req';
 import type { FigmaImageResult, FigmaNodeMetadata } from '../types';
 export type FigmaRestOptions = {
+    req: Req;
     tempPath?: string;
     nodesCacheTtlSeconds?: number;
+    /** Must be the budget `req` was built with: `req` enforces the wait, this names it in the error. */
     maxRateLimitWaitSeconds?: number;
     /** Serve from the on-disk caches only; throw on any miss. */
     skipApi?: boolean;
-    proxy?: Proxy;
-    /** Defaults to `makeFigmaReq(…)`; tests inject a stub. */
-    req?: Req;
-    logger?: Logger;
 };
 /**
  * Cache names are hashed because Figma node ids are not filename-safe — an instance node id looks like
@@ -20,5 +17,5 @@ export type FigmaRestOptions = {
  */
 export declare function figmaNodesCacheFileName(fileId: string, uniqueNodeIds: string[]): string;
 export declare function figmaImageCacheFileName(fileId: string, nodeId: string, lastModifiedUnix: number): string;
-export declare function fetchFigmaMetadata(urls: string[], accessToken: string, opts?: FigmaRestOptions): Promise<FigmaNodeMetadata[]>;
-export declare function fetchFigmaImages(urls: string[], accessToken: string, opts?: FigmaRestOptions): Promise<FigmaImageResult[]>;
+export declare function fetchFigmaMetadata(urls: string[], accessToken: string, opts: FigmaRestOptions): Promise<FigmaNodeMetadata[]>;
+export declare function fetchFigmaImages(urls: string[], accessToken: string, opts: FigmaRestOptions): Promise<FigmaImageResult[]>;

package/types/figma/figma.d.ts

@@ -1,10 +1,10 @@
 import { type Logger } from '@applitools/logger';
-import type { Proxy, Req } from '@applitools/req';
+import type { Proxy } from '@applitools/req';
 import type { OpenSettings } from '../automation/types';
 import { type FigmaMode } from './utils';
 import type { FigmaViewportOptions, FigmaBaselineDeps } from './types';
-export declare function setFigmaBaselineFlow(figmaUrls: string[], originalConfig: Partial<OpenSettings>, deps: FigmaBaselineDeps, mode?: Exclude<FigmaMode, 'disabled'>, viewportOpts?: FigmaViewportOptions, logger?: Logger): Promise<Partial<OpenSettings>>;
-export declare function setFigmaBaseline(configuration: Partial<OpenSettings>, figmaBaselines: string | Record<string, string | string[]>, opts?: {
+export declare function setFigmaBaselineFlow(figmaUrls: string[], originalConfig: Partial<OpenSettings>, deps: FigmaBaselineDeps, logger: Logger, mode?: Exclude<FigmaMode, 'disabled'>, viewportOpts?: FigmaViewportOptions): Promise<Partial<OpenSettings>>;
+export declare function setFigmaBaseline(configuration: Partial<OpenSettings>, figmaBaselines: string | Record<string, string | string[]>, logger: Logger, opts?: {
     accessToken?: string;
     maxRateLimitWaitSeconds?: number;
     nodesCacheTtlSeconds?: number;
@@ -15,7 +15,4 @@ export declare function setFigmaBaseline(configuration: Partial<OpenSettings>, f
     /** Serve from the disk caches only; throw on any miss. */
     skipApi?: boolean;
     proxy?: Proxy;
-    /** Defaults to the client's own req; tests inject a stub. */
-    req?: Req;
-    logger?: Logger;
 }): Promise<void>;

package/types/lang.d.ts

@@ -1,5 +1,6 @@
 export declare const matchLevelContentDeprecatedWarning = "The \"Content\" match level value has been deprecated, use \"IgnoreColors\" instead.";
 export declare const edgeUfgEnvironmentDeprecatedWarning = "The 'edge' option that is being used in your browsers' configuration will soon be deprecated. Please change it to either 'edgelegacy' for the legacy version or to 'edgechromium' for the new Chromium-based version. Please note, when using the built-in BrowserType enum, then the values are BrowserType.EDGE_LEGACY and BrowserType.EDGE_CHROMIUM, respectively.";
+export declare const figmaExperimentalWarning = "Figma support is experimental. It is not officially supported and may change or be removed in a future release.";
 export declare const outdatedSdkVersionWarning: (options: {
     name: string;
     currentVersion: string;