@applitools/core 4.67.1 → 4.68.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [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)
+
+
+### Dependencies
+
+* @applitools/dom-snapshot bumped to 4.17.8
+  #### Bug Fixes
+
+  * strip basic auth from stylesheet sheet.href | FLD-4738 ([#4036](https://github.com/Applitools-Dev/sdk/issues/4036)) ([2ff5259](https://github.com/Applitools-Dev/sdk/commit/2ff525919157598df8e22650a69f59efdb448311))
+  * use sheet.href for stylesheet links | FLD-4738 ([#4033](https://github.com/Applitools-Dev/sdk/issues/4033)) ([20d2e65](https://github.com/Applitools-Dev/sdk/commit/20d2e65fb83b9680729a0565e5f4301d2ea79e04))
+
+
+
+* @applitools/snippets bumped to 2.9.5
+  #### Bug Fixes
+
+  * honor maxAmountToScroll in lazyLoad when scrollTop overshoots ([#4032](https://github.com/Applitools-Dev/sdk/issues/4032)) ([b4393d7](https://github.com/Applitools-Dev/sdk/commit/b4393d76cc9457c2a36896dc1bb6cbaa0c6ed2b4))
+* @applitools/driver bumped to 1.26.7
+
+* @applitools/spec-driver-webdriver bumped to 1.6.7
+
+* @applitools/spec-driver-selenium bumped to 1.8.7
+
+* @applitools/spec-driver-playwright bumped to 1.9.7
+
+* @applitools/spec-driver-puppeteer bumped to 1.8.7
+
+* @applitools/screenshoter bumped to 3.12.26
+
+* @applitools/nml-client bumped to 1.11.38
+
+* @applitools/ec-client bumped to 1.12.40
+
+
 ## [4.67.1](https://github.com/Applitools-Dev/sdk/compare/js/core@4.67.0...js/core@4.67.1) (2026-07-29)
 
 

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/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);

package/dist/figma/figma-images.js

@@ -0,0 +1,62 @@
+"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.createPaddedDesignImage = exports.createPlaceholderPng = void 0;
+// Image helpers for the Figma resolver: the white placeholder PNG for '' steps and the minViewportSize
+// padding that centers a small design on a larger canvas. Both keyed by output dimensions so repeats reuse the file.
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const image_1 = require("@applitools/image");
+const utils_1 = require("./utils");
+// Writes (or reuses) a placeholder PNG keyed by dimensions alone — content is always identical.
+async function createPlaceholderPng(width, height, tempPath) {
+    const imagePath = path.join(tempPath, `figma-placeholder-${width}x${height}.png`);
+    if (!fs.existsSync(imagePath)) {
+        fs.writeFileSync(imagePath, await (0, image_1.generateWhitePng)(width, height));
+    }
+    return imagePath;
+}
+exports.createPlaceholderPng = createPlaceholderPng;
+// Pads imagePath onto a centered white canvas at paddedDesignSize, returning the new path + canvas size
+// (unchanged if it already meets minSize on both axes). Keyed by basename + canvas size so repeats reuse the file.
+async function createPaddedDesignImage(imagePath, width, height, minSize, tempPath) {
+    const canvas = (0, utils_1.paddedDesignSize)(width, height, minSize);
+    if (canvas.width === width && canvas.height === height) {
+        return { imagePath, width, height };
+    }
+    const baseName = path.basename(imagePath, path.extname(imagePath));
+    const outputPath = path.join(tempPath, `figma-padded-${baseName}-${canvas.width}x${canvas.height}.png`);
+    if (!fs.existsSync(outputPath)) {
+        const canvasImage = (0, image_1.makeImage)(await (0, image_1.generateWhitePng)(canvas.width, canvas.height));
+        canvasImage.copy((0, image_1.makeImage)(imagePath), {
+            x: Math.floor((canvas.width - width) / 2),
+            y: Math.floor((canvas.height - height) / 2),
+        });
+        // toPng (not toFile) — Image.toFile writes the pre-transform pixels, dropping the copy above.
+        fs.writeFileSync(outputPath, await canvasImage.toPng());
+    }
+    return { imagePath: outputPath, ...canvas };
+}
+exports.createPaddedDesignImage = createPaddedDesignImage;

package/dist/figma/figma.js

@@ -0,0 +1,168 @@
+"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.setFigmaBaseline = exports.setFigmaBaselineFlow = void 0;
+// Figma baseline resolver (AD-14881): orchestration only, operating directly on core's OpenSettings
+// (the eyes/cypress/non-JS bindings adapt the flat config to this shape). Helpers split into ./utils,
+// ./client, ./figma-images, ./target-config.
+const os = __importStar(require("os"));
+const logger_1 = require("@applitools/logger");
+const utils_1 = require("./utils");
+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)()) {
+    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;
+    for (const url of figmaUrls) {
+        if (url !== '' && !(0, utils_1.isFigmaUrl)(url)) {
+            throw new Error(`setFigmaBaseline: "${url}" is not a valid Figma URL. ` + `To skip a test, use an empty string.`);
+        }
+    }
+    // '' entries are placeholder steps; resolveFigmaUrls guarantees at least one real URL here.
+    const realUrls = figmaUrls.filter(url => url !== '');
+    if (mode === 'test-baseline') {
+        logger.log(`Fetching Figma design metadata: ${realUrls[0]}${realUrls.length > 1 ? ` (+${realUrls.length - 1} more)` : ''}`);
+        const rawMetadataList = await deps.fetchFigmaMetadata(realUrls);
+        logger.log(`Figma node: "${rawMetadataList[0].name}" (${rawMetadataList[0].type}) ${rawMetadataList[0].width}x${rawMetadataList[0].height}, last modified ${rawMetadataList[0].lastModifiedAt}`);
+        logger.log(`Mode is test-baseline — skipping Figma change detection; adjusting viewport only.`);
+        // test-baseline never fetches images, so minViewportSize floors the metadata dimensions directly.
+        const metadataList = minViewportSize != null
+            ? rawMetadataList.map(m => ({ ...m, ...(0, utils_1.paddedDesignSize)(m.width, m.height, minViewportSize) }))
+            : rawMetadataList;
+        const stepViewports = metadataList.map(m => ({ width: m.width, height: m.height }));
+        const figmaViewport = (0, utils_1.computeFigmaViewport)(stepViewports, maxViewportHeight);
+        logger.log(`Figma viewport: ${figmaViewport.width}x${figmaViewport.height}`);
+        return (0, target_config_1.buildTargetTestConfig)(originalConfig, metadataList[0], figmaViewport, null, mode);
+    }
+    logger.log(`Fetching Figma design: ${realUrls[0]}${realUrls.length > 1 ? ` (+${realUrls.length - 1} more)` : ''}`);
+    const rawResults = await deps.fetchFigmaImages(realUrls);
+    logger.log(`Figma node: "${rawResults[0].metadata.name}" (${rawResults[0].metadata.type}) ${rawResults[0].metadata.width}x${rawResults[0].metadata.height}, last modified ${rawResults[0].metadata.lastModifiedAt}`);
+    const realResults = minViewportSize != null
+        ? await Promise.all(rawResults.map(async (r) => {
+            const padded = await deps.padDesignImage(r.imagePath, r.metadata.width, r.metadata.height, minViewportSize);
+            return { imagePath: padded.imagePath, metadata: { ...r.metadata, width: padded.width, height: padded.height } };
+        }))
+        : rawResults;
+    // The figma viewport bounds every step, so a multi-step test with differently-sized frames renders at one consistent size.
+    const stepViewports = realResults.map(r => ({ width: r.metadata.width, height: r.metadata.height }));
+    const figmaViewport = (0, utils_1.computeFigmaViewport)(stepViewports, maxViewportHeight);
+    const figmaEnvName = `Figma ${figmaViewport.width}x${figmaViewport.height}`;
+    logger.log(`Figma viewport: ${figmaViewport.width}x${figmaViewport.height}`);
+    // Splice placeholder steps back at their original positions, using a blank image at the shared figma viewport.
+    const results = [];
+    let realResultIndex = 0;
+    for (const url of figmaUrls) {
+        if (url === '') {
+            const imagePath = await deps.createPlaceholderImage(figmaViewport.width, figmaViewport.height);
+            results.push({
+                imagePath,
+                metadata: {
+                    name: target_config_1.PLACEHOLDER_TAG,
+                    type: 'PLACEHOLDER',
+                    width: figmaViewport.width,
+                    height: figmaViewport.height,
+                    revision: 'placeholder',
+                    lastModifiedAt: '',
+                },
+            });
+        }
+        else {
+            results.push(realResults[realResultIndex]);
+            realResultIndex++;
+        }
+    }
+    logger.log(`Establishing Figma baseline...`);
+    const figmaReferenceConfig = {
+        apiKey: originalConfig.apiKey,
+        // Same server + proxy as the real test — otherwise on-prem users get the baseline on the public cloud.
+        eyesServerUrl: originalConfig.eyesServerUrl,
+        proxy: originalConfig.proxy,
+        batch: originalConfig.batch,
+        appName: originalConfig.appName,
+        testName: originalConfig.testName,
+        environment: { hostingApp: 'Figma', os: '', viewportSize: figmaViewport },
+        properties: (0, utils_1.figmaMetadataToProperties)(realResults[0].metadata, mode),
+        baselineEnvName: figmaEnvName,
+        saveNewTests: true,
+        saveDiffs: true,
+        keepBatchOpen: true,
+    };
+    if (originalConfig.branchName !== undefined)
+        figmaReferenceConfig.branchName = originalConfig.branchName;
+    const checks = results.map(({ imagePath }, i) => ({
+        imagePath,
+        tag: figmaUrls[i] === '' ? target_config_1.PLACEHOLDER_TAG : (0, utils_1.figmaStepTag)(figmaUrls[i]),
+    }));
+    const { isNew: figmaIsNew, diffs: figmaDiffs } = await deps.runFigmaCheck(figmaReferenceConfig, checks);
+    logger.log(`Figma baseline: ${figmaIsNew ? 'new (first run)' : !figmaDiffs ? 'passed (design unchanged)' : 'changed (design updated)'}`);
+    logger.log(`Linking test to Figma baseline: ${figmaEnvName}`);
+    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)();
+    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.');
+        return;
+    }
+    const getToken = () => {
+        var _a;
+        if (!(opts === null || opts === void 0 ? void 0 : opts.skipApi) && !(opts === null || opts === void 0 ? void 0 : opts.accessToken)) {
+            throw new Error('setFigmaBaseline: no Figma access token. ' +
+                'Pass accessToken or set the FIGMA_ACCESS_TOKEN environment variable.');
+        }
+        return (_a = opts === null || opts === void 0 ? void 0 : opts.accessToken) !== null && _a !== void 0 ? _a : '';
+    };
+    const restOpts = {
+        tempPath: opts === null || opts === void 0 ? void 0 : opts.tempPath,
+        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,
+    };
+    const deps = {
+        fetchFigmaImages: urlList => (0, client_1.fetchFigmaImages)(urlList, getToken(), restOpts),
+        fetchFigmaMetadata: urlList => (0, client_1.fetchFigmaMetadata)(urlList, getToken(), restOpts),
+        createPlaceholderImage: (width, height) => { var _a; return (0, figma_images_1.createPlaceholderPng)(width, height, (_a = opts === null || opts === void 0 ? void 0 : opts.tempPath) !== null && _a !== void 0 ? _a : os.tmpdir()); },
+        padDesignImage: (imagePath, width, height, minViewportSize) => { var _a; return (0, figma_images_1.createPaddedDesignImage)(imagePath, width, height, minViewportSize, (_a = opts === null || opts === void 0 ? void 0 : opts.tempPath) !== null && _a !== void 0 ? _a : os.tmpdir()); },
+        runFigmaCheck: run_figma_check_1.runFigmaCheck,
+    };
+    const figmaUrls = (0, utils_1.resolveFigmaUrls)(figmaBaselines, configuration.testName);
+    if (figmaUrls === null)
+        return;
+    const updated = await setFigmaBaselineFlow(figmaUrls, configuration, deps, 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;