@applitools/core 4.67.2 → 4.68.1

package/CHANGELOG.md

@@ -1,5 +1,192 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* add figmaOptions open config to all SDKs | AD-15464 ([#4052](https://github.com/Applitools-Dev/sdk/issues/4052)) ([cff2a2d](https://github.com/Applitools-Dev/sdk/commit/cff2a2d2f3d905dbfd9e12a9b7b26c61c2348935))
+* figmaBaselines first-class open-config, in-repo resolver, all SDKs | AD-15462 ([#4021](https://github.com/Applitools-Dev/sdk/issues/4021)) ([998b3b3](https://github.com/Applitools-Dev/sdk/commit/998b3b38486669d2997f9eb11316067abbe85230))
+* forward accessibilityReportOptions (axe-core) from render-info into the UFG render request | AD-15104 ([#4004](https://github.com/Applitools-Dev/sdk/issues/4004)) ([eef1b59](https://github.com/Applitools-Dev/sdk/commit/eef1b59feac63a488fdb9e7de73d3063cf43c8ca))
+
+
+### Dependencies
+
+* @applitools/image bumped to 1.3.0
+  #### Features
+
+  * figmaBaselines first-class open-config, in-repo resolver, all SDKs | AD-15462 ([#4021](https://github.com/Applitools-Dev/sdk/issues/4021)) ([998b3b3](https://github.com/Applitools-Dev/sdk/commit/998b3b38486669d2997f9eb11316067abbe85230))
+* @applitools/ufg-client bumped to 1.23.0
+  #### Features
+
+  * forward accessibilityReportOptions (axe-core) from render-info into the UFG render request | AD-15104 ([#4004](https://github.com/Applitools-Dev/sdk/issues/4004)) ([eef1b59](https://github.com/Applitools-Dev/sdk/commit/eef1b59feac63a488fdb9e7de73d3063cf43c8ca))
+
+
+
+* @applitools/screenshoter bumped to 3.12.27
+
+* @applitools/nml-client bumped to 1.11.39
+
+* @applitools/core-base bumped to 1.38.0
+  #### Features
+
+  * forward accessibilityReportOptions (axe-core) from render-info into the UFG render request | AD-15104 ([#4004](https://github.com/Applitools-Dev/sdk/issues/4004)) ([eef1b59](https://github.com/Applitools-Dev/sdk/commit/eef1b59feac63a488fdb9e7de73d3063cf43c8ca))
+
+
+
+* @applitools/ec-client bumped to 1.12.41
+
+
 ## [4.67.2](https://github.com/Applitools-Dev/sdk/compare/js/core@4.67.1...js/core@4.67.2) (2026-07-30)
 
 

package/dist/autonomous/create-render-results.js

@@ -23,6 +23,7 @@ function makeCreateRenderResults({ logger }) {
             }
         });
         return results.map(({ selectorRegions, renderId, status, error, ...baseTarget }, index) => {
+            var _a;
             const { elementReferences: selectors, getBaseCheckSettings } = (0, to_base_check_settings_1.toBaseCheckSettings)({
                 settings: renders[index].settings,
             });
@@ -38,7 +39,11 @@ function makeCreateRenderResults({ logger }) {
             return {
                 status,
                 error,
-                target: { ...baseTarget, isTransformed: true },
+                target: {
+                    ...baseTarget,
+                    isTransformed: true,
+                    accessibilityReportLocation: (_a = baseTarget.accessibilityReportLocation) !== null && _a !== void 0 ? _a : renders[index].accessibilityReportLocation,
+                },
                 settings: baseSettings,
                 environment: renders[index].environment,
                 account: renders[index].account,

package/dist/autonomous/start-renders.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeStartRenders = void 0;
 const to_base_check_settings_1 = require("../automation/utils/to-base-check-settings");
+const build_accessibility_report_options_1 = require("../ufg/build-accessibility-report-options");
 function makeStartRenders({ core, logger: defaultLogger }) {
     return async function startRenders({ targets, logger = defaultLogger, }) {
         const clients = await targets.reduce(async (promise, target) => {
@@ -25,9 +26,12 @@ function makeStartRenders({ core, logger: defaultLogger }) {
             });
         }, Promise.resolve(new Map()));
         const renders = await Promise.all(Array.from(clients.entries(), async ([ufgClient, targets]) => {
+            const accessibilityReportOptions = targets.map(target => target.settings.accessibilitySettings
+                ? (0, build_accessibility_report_options_1.buildAccessibilityReportOptions)({ accessibilityOptions: target.account.accessibilityOptions })
+                : undefined);
             const [renders, ...environments] = await Promise.all([
                 ufgClient.startRenders({
-                    renders: targets.map(target => {
+                    renders: targets.map((target, index) => {
                         var _a;
                         const { elementReferences: selectors } = (0, to_base_check_settings_1.toBaseCheckSettings)({ settings: target.settings });
                         return {
@@ -41,6 +45,7 @@ function makeStartRenders({ core, logger: defaultLogger }) {
                                 environment: target.environment,
                                 uploadUrl: target.account.uploadUrl,
                                 stitchingServiceUrl: target.account.stitchingServiceUrl,
+                                accessibilityReportOptions: accessibilityReportOptions[index],
                             },
                         };
                     }),
@@ -54,12 +59,16 @@ function makeStartRenders({ core, logger: defaultLogger }) {
                     return { ...environment, properties: target.environment.properties };
                 }),
             ]);
-            return renders.map((render, index) => ({
-                render,
-                settings: targets[index].settings,
-                environment: environments[index],
-                account: targets[index].account,
-            }));
+            return renders.map((render, index) => {
+                var _a;
+                return ({
+                    render,
+                    settings: targets[index].settings,
+                    environment: environments[index],
+                    account: targets[index].account,
+                    accessibilityReportLocation: (_a = accessibilityReportOptions[index]) === null || _a === void 0 ? void 0 : _a.uploadUrl,
+                });
+            });
         }));
         return renders.flat();
     };

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeFigmaReq = 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';
+// `limit` is what bounds the number of retries, not `retryTimeout`: Figma may answer `Retry-After: 0`, and
+// a zero delay never advances an elapsed-time budget.
+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 } = {}) {
+    const maxWaitMs = maxRateLimitWaitSeconds * 1000;
+    return (0, req_1.makeReq)({
+        proxy,
+        retry: {
+            limit: RETRY_LIMIT,
+            timeout: RETRY_BACKOFF_MS,
+            /**
+             * Deciding here rather than with `statuses: [429]` is what enforces the wait budget. `req` sleeps
+             * `Retry-After` in full and only compares `retryTimeout` against time already ELAPSED, so accepting a
+             * retry commits to the whole delay: an hour, a day or a week each block for their full duration.
+             * (Beyond ~24.8 days it overflows `setTimeout` and fires almost immediately — wrong in the other
+             * direction.) Refusing the retry surfaces the 429 to the caller instead.
+             */
+            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))
+                    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.`);
+                    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...`);
+                return true;
+            },
+        },
+        retryTimeout: maxWaitMs,
+    });
+}
+exports.makeFigmaReq = makeFigmaReq;

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

@@ -0,0 +1,189 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchFigmaImages = exports.fetchFigmaMetadata = exports.figmaImageCacheFileName = exports.figmaNodesCacheFileName = void 0;
+// Figma REST layer: batched /nodes + /images calls and their on-disk caches. Rate limiting, proxying and
+// timeouts belong to the `req` instance (./figma-req).
+// All metadata flows through fetchFigmaFileNodes so /nodes is fetched at most once per file.
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const buffer_1 = require("buffer");
+const utils_1 = require("../utils");
+const figma_req_1 = require("./figma-req");
+const DEFAULT_NODES_CACHE_TTL_SECONDS = 120;
+/**
+ * Cache names are hashed because Figma node ids are not filename-safe — an instance node id looks like
+ * `I1:2;3:4`, and `:` / `;` are illegal on Windows.
+ *
+ * `test/fixtures/figma-cache/seed.mjs` mirrors both functions — keep them in sync.
+ */
+function figmaNodesCacheFileName(fileId, uniqueNodeIds) {
+    const hash = crypto
+        .createHash('sha1')
+        .update(`${fileId}:${[...uniqueNodeIds].sort().join(',')}`)
+        .digest('hex');
+    return `figma-nodes-${hash}.json`;
+}
+exports.figmaNodesCacheFileName = figmaNodesCacheFileName;
+function figmaImageCacheFileName(fileId, nodeId, lastModifiedUnix) {
+    const hash = crypto.createHash('sha1').update(`${fileId}:${nodeId}:${lastModifiedUnix}`).digest('hex');
+    return `figma-image-${hash}.png`;
+}
+exports.figmaImageCacheFileName = figmaImageCacheFileName;
+async function figmaGet(req, endpoint, accessToken) {
+    const response = await req(`${figma_req_1.FIGMA_API}${endpoint}`, {
+        headers: { 'X-Figma-Token': accessToken },
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`Figma API error ${response.status}${body ? `: ${body}` : ''}`);
+    }
+    return response.json();
+}
+// Grouping by file is what keeps API usage proportional to files touched, not URLs requested.
+function groupByFile(urls) {
+    const byFile = new Map();
+    urls.forEach((url, urlIndex) => {
+        const { fileId, nodeId } = (0, utils_1.parseFigmaNodeUrl)(url);
+        if (!byFile.has(fileId))
+            byFile.set(fileId, []);
+        byFile.get(fileId).push({ nodeId, urlIndex });
+    });
+    return byFile;
+}
+// The single source of node metadata — both entry points route through here, so /nodes is never fetched twice.
+async function fetchFigmaFileNodes(urls, accessToken, opts) {
+    const resolved = [];
+    for (const [fileId, nodes] of groupByFile(urls)) {
+        const uniqueNodeIds = [...new Set(nodes.map(n => n.nodeId))].sort();
+        const nodesFilePath = path.join(opts.tempPath, figmaNodesCacheFileName(fileId, uniqueNodeIds));
+        let nodesResp;
+        if (fs.existsSync(nodesFilePath)) {
+            const stat = fs.statSync(nodesFilePath);
+            const ageSeconds = (Date.now() - stat.mtimeMs) / 1000;
+            if (opts.skipApi || ageSeconds < opts.ttlSeconds) {
+                nodesResp = JSON.parse(fs.readFileSync(nodesFilePath, 'utf8'));
+            }
+        }
+        if (!nodesResp) {
+            if (opts.skipApi) {
+                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);
+            fs.writeFileSync(nodesFilePath, JSON.stringify(nodesResp));
+        }
+        resolved.push({ fileId, nodesResp, nodes });
+    }
+    return resolved;
+}
+function metadataFromNodesResp(nodesResp, fileId, nodeId) {
+    var _a, _b, _c;
+    const nodeData = (_a = nodesResp.nodes) === null || _a === void 0 ? void 0 : _a[nodeId];
+    if (!nodeData) {
+        throw new Error(`Node "${nodeId}" not found in file "${fileId}"`);
+    }
+    const doc = nodeData.document;
+    const box = (_b = doc.absoluteBoundingBox) !== null && _b !== void 0 ? _b : doc.absoluteRenderBounds;
+    if (!box) {
+        throw new Error(`Node "${nodeId}" has no bounding box`);
+    }
+    return {
+        name: doc.name,
+        type: doc.type,
+        width: Math.round(box.width),
+        height: Math.round(box.height),
+        revision: String((_c = nodesResp.version) !== null && _c !== void 0 ? _c : 'unknown'),
+        lastModifiedAt: nodesResp.lastModified,
+    };
+}
+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,
+        }),
+    };
+}
+// 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 results = new Array(urls.length);
+    for (const { fileId, nodesResp, nodes } of fileGroups) {
+        for (const { nodeId, urlIndex } of nodes) {
+            results[urlIndex] = metadataFromNodesResp(nodesResp, fileId, nodeId);
+        }
+    }
+    return results;
+}
+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 results = new Array(urls.length);
+    for (const [fileId, nodes] of groupByFile(urls)) {
+        const uniqueNodeIds = [...new Set(nodes.map(n => n.nodeId))].sort();
+        // lastModified is file-level, so any node of this file carries it. Absent ⇒ NaN, which would poison
+        // the cache key.
+        const lastModifiedMs = new Date(metadataList[nodes[0].urlIndex].lastModifiedAt).getTime();
+        const lastModifiedUnix = Number.isFinite(lastModifiedMs) ? Math.floor(lastModifiedMs / 1000) : 0;
+        const imagePathFor = (nodeId) => path.join(tempPath, figmaImageCacheFileName(fileId, nodeId, lastModifiedUnix));
+        const missNodeIds = uniqueNodeIds.filter(nodeId => !fs.existsSync(imagePathFor(nodeId)));
+        if (missNodeIds.length > 0) {
+            if (skipApi) {
+                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);
+            await Promise.all(missNodeIds.map(async (nodeId) => {
+                var _a;
+                const imageUrl = (_a = imagesResp.images) === null || _a === void 0 ? void 0 : _a[nodeId];
+                if (!imageUrl) {
+                    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);
+                if (!imageResponse.ok) {
+                    throw new Error(`Failed to download Figma image: HTTP ${imageResponse.status}`);
+                }
+                fs.writeFileSync(imagePathFor(nodeId), buffer_1.Buffer.from(await imageResponse.arrayBuffer()));
+            }));
+        }
+        for (const { nodeId, urlIndex } of nodes) {
+            results[urlIndex] = { imagePath: imagePathFor(nodeId), metadata: metadataList[urlIndex] };
+        }
+    }
+    return results;
+}
+exports.fetchFigmaImages = fetchFigmaImages;

package/dist/figma/client/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+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.
+__exportStar(require("./figma-req"), exports);
+__exportStar(require("./figma-rest"), exports);