@applitools/core 4.67.2 → 4.68.1

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', 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;

package/dist/figma/index.js

@@ -0,0 +1,27 @@
+"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 });
+exports.applyFigmaBaselines = exports.runFigmaCheck = void 0;
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);
+__exportStar(require("./target-config"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./figma-images"), exports);
+__exportStar(require("./figma"), exports);
+var run_figma_check_1 = require("./run-figma-check");
+Object.defineProperty(exports, "runFigmaCheck", { enumerable: true, get: function () { return run_figma_check_1.runFigmaCheck; } });
+var seam_1 = require("./seam");
+Object.defineProperty(exports, "applyFigmaBaselines", { enumerable: true, get: function () { return seam_1.applyFigmaBaselines; } });

package/dist/figma/run-figma-check.js

@@ -0,0 +1,82 @@
+"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.runFigmaCheck = void 0;
+const utils = __importStar(require("@applitools/utils"));
+const core_1 = require("../core");
+// Cached because this runs once per open — eyes-storybook opens per story, and a fresh Core each time
+// re-initialises and forfeits HTTP agent reuse. Safe to share: all state arrives via `openEyes`.
+const getFigmaCore = utils.general.cachify(() => (0, core_1.makeCore)({ agentId: 'core.figma-baseline' }));
+/**
+ * Establishes/updates the Figma-reference baseline via a throwaway headless classic image test (checks
+ * each PNG, closes, deletes the result — the saved baseline persists). Uses core's own API, not the
+ * eyes layer (core cannot depend on `@applitools/eyes`).
+ */
+async function runFigmaCheck(config, checks) {
+    var _a;
+    const core = getFigmaCore();
+    const eyes = await core.openEyes({
+        type: 'classic',
+        settings: {
+            appName: config.appName,
+            testName: config.testName,
+            apiKey: config.apiKey,
+            eyesServerUrl: config.eyesServerUrl,
+            proxy: config.proxy,
+            baselineEnvName: config.baselineEnvName,
+            properties: config.properties,
+            batch: config.batch,
+            keepBatchOpen: config.keepBatchOpen,
+            saveDiffs: config.saveDiffs,
+            ...(config.branchName !== undefined ? { branchName: config.branchName } : {}),
+            environment: config.environment,
+            // Throwaway reference test keyed purely by baselineEnvName; skip the (slow) git extraction.
+            ignoreGitBranching: true,
+        },
+    });
+    for (const { imagePath, tag } of checks) {
+        await eyes.check({ target: { image: imagePath }, settings: { name: tag } });
+    }
+    // core's close-time equivalent of saveNewTests (defaulted true there too).
+    await eyes.close({ settings: { updateBaselineIfNew: (_a = config.saveNewTests) !== null && _a !== void 0 ? _a : true } });
+    const [result] = await eyes.getResults({ settings: { throwErr: false } });
+    try {
+        await core.deleteTest({
+            settings: {
+                testId: result.id,
+                batchId: result.batchId,
+                secretToken: result.secretToken,
+                eyesServerUrl: result.eyesServer.eyesServerUrl,
+                apiKey: result.eyesServer.apiKey,
+                proxy: result.eyesServer.proxy,
+            },
+        });
+    }
+    catch {
+        // best-effort cleanup
+    }
+    return { isNew: result.isNew, diffs: result.mismatches > 0 };
+}
+exports.runFigmaCheck = runFigmaCheck;

package/dist/figma/seam.js

@@ -0,0 +1,91 @@
+"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.applyFigmaBaselines = void 0;
+const utils = __importStar(require("@applitools/utils"));
+const figma_1 = require("./figma");
+const utils_1 = require("./utils");
+/**
+ * @internal
+ * Resolves the `figmaBaselines` / `figmaOptions` open config once per open, then always strips both — they
+ * are off-the-wire and must never be logged or sent. The resolver mutates `settings` in place.
+ *
+ * The only place the Figma feature reads the environment; everything below it takes parameters. Each
+ * `figmaOptions` field wins over its env fallback.
+ */
+async function applyFigmaBaselines(settings, logger, resolve = figma_1.setFigmaBaseline) {
+    var _a, _b, _c, _d, _e, _f;
+    const figmaBaselines = settings.figmaBaselines;
+    const figmaOptions = (_a = settings.figmaOptions) !== null && _a !== void 0 ? _a : {};
+    if (!figmaBaselines) {
+        // Undefined-valued keys must not survive to the wire/log.
+        delete settings.figmaBaselines;
+        delete settings.figmaOptions;
+        return;
+    }
+    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) {
+            logger.warn(`figmaBaselines is set but has no entry for test "${settings.testName}"; skipping Figma baseline resolution for this test.`);
+            return;
+        }
+        // skipApi has no figmaOptions equivalent by design — CI/debug switch, not a user option.
+        const skipApi = (_b = utils.general.getEnvValue('FIGMA_SKIP_API', 'boolean')) !== null && _b !== void 0 ? _b : false;
+        const envTtl = utils.general.getEnvValue('FIGMA_NODES_CACHE_TTL', 'number');
+        const tempPath = (_c = figmaOptions.tempPath) !== null && _c !== void 0 ? _c : utils.general.getEnvValue('FIGMA_TEMP_PATH');
+        // A long TTL lets a pre-warmed cache (committed fixtures) serve through the normal cache-hit path
+        // instead of the all-or-nothing skipApi bypass. Number.isFinite also rejects a non-numeric env value.
+        const nodesCacheTtlSeconds = (_d = figmaOptions.nodesCacheTtlSeconds) !== null && _d !== void 0 ? _d : envTtl;
+        // Registered with the logger the way apiKey/secretToken are elsewhere, so a token supplied through
+        // figmaOptions is redacted wherever settings are logged downstream.
+        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,
+            skipApi,
+            mode: (0, utils_1.resolveFigmaMode)((_f = figmaOptions.mode) !== null && _f !== void 0 ? _f : utils.general.getEnvValue('FIGMA_MODE')),
+            accessToken,
+            // On-prem accounts have no direct route to api.figma.com.
+            proxy: settings.proxy,
+            ...(tempPath ? { tempPath } : {}),
+            ...(Number.isFinite(nodesCacheTtlSeconds) ? { nodesCacheTtlSeconds } : {}),
+            // These three have no env fallback, so omit them when absent and let the resolver default them.
+            // `!= null` not `!== undefined`: bindings that serialize an unset nested field as null (Ruby) would
+            // otherwise reach `maxRateLimitWaitSeconds = 60`, which only defaults on undefined, and null*1000
+            // silently zeroes the rate-limit budget.
+            ...(figmaOptions.maxRateLimitWaitSeconds != null
+                ? { maxRateLimitWaitSeconds: figmaOptions.maxRateLimitWaitSeconds }
+                : {}),
+            ...(figmaOptions.maxViewportHeight != null ? { maxViewportHeight: figmaOptions.maxViewportHeight } : {}),
+            ...(figmaOptions.minViewportSize != null ? { minViewportSize: figmaOptions.minViewportSize } : {}),
+        });
+    }
+    finally {
+        delete settings.figmaBaselines;
+        delete settings.figmaOptions;
+    }
+}
+exports.applyFigmaBaselines = applyFigmaBaselines;

package/dist/figma/target-config.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTargetTestConfig = exports.deduplicateBrowsers = exports.PLACEHOLDER_TAG = exports.DEFAULT_MAX_VIEWPORT_HEIGHT = void 0;
+const utils_1 = require("./utils");
+// Default height cap (overridable via opts.maxViewportHeight): designs can be arbitrarily tall, so
+// height is capped but width never is — width is the form factor the design and real test must share.
+exports.DEFAULT_MAX_VIEWPORT_HEIGHT = 800;
+// Dashboard tag for a '' (placeholder) step; real steps use the Figma URL as the tag.
+exports.PLACEHOLDER_TAG = '(no design)';
+// UFG opens request per-browser environments; classic sizes a single viewport instead.
+function deduplicateBrowsers(environments, targetWidth, targetHeight) {
+    const desktop = new Map();
+    for (const environment of environments) {
+        const db = environment;
+        const entry = typeof db.width === 'number'
+            ? db
+            : { name: 'iosDeviceInfo' in environment ? 'safari' : 'chrome', width: targetWidth, height: targetHeight };
+        desktop.set(String(entry.name), { ...entry, width: targetWidth, height: targetHeight });
+    }
+    return [...desktop.values()];
+}
+exports.deduplicateBrowsers = deduplicateBrowsers;
+// baselineLink is null in "test-baseline" mode: baselineEnvName is left untouched (no change detection
+// happened to justify linking), but viewport/properties are still adjusted. figmaViewport always wins.
+function buildTargetTestConfig(originalConfig, metadata, figmaViewport, baselineLink, mode) {
+    var _a, _b, _c;
+    const isUFG = ((_b = (_a = originalConfig.environments) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0;
+    const mergedProperties = [...((_c = originalConfig.properties) !== null && _c !== void 0 ? _c : []), ...(0, utils_1.figmaMetadataToProperties)(metadata, mode)];
+    // baselineEnvOptions is the internal field backing Configuration.setBaselineEnvName(name, {useLatestEnvBaseline}) — same effect without a live Configuration.
+    const baselineFields = baselineLink
+        ? {
+            baselineEnvName: baselineLink.figmaEnvName,
+            baselineEnvOptions: { useLatestEnvBaseline: baselineLink.useLatestEnvBaseline },
+        }
+        : {};
+    // The figma viewport always wins; merged into environment.viewportSize so os/hostingApp survive.
+    const environment = { ...originalConfig.environment, viewportSize: figmaViewport };
+    if (isUFG) {
+        return {
+            ...baselineFields,
+            properties: mergedProperties,
+            environments: deduplicateBrowsers(originalConfig.environments, figmaViewport.width, figmaViewport.height),
+            environment,
+        };
+    }
+    return {
+        ...baselineFields,
+        properties: mergedProperties,
+        environment,
+    };
+}
+exports.buildTargetTestConfig = buildTargetTestConfig;

package/dist/figma/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/figma/utils.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paddedDesignSize = exports.computeFigmaViewport = exports.boundingViewport = exports.figmaMetadataToProperties = exports.resolveFigmaMode = exports.FIGMA_MODES = exports.resolveFigmaUrls = exports.figmaStepTag = exports.parseFigmaNodeUrl = exports.isFigmaUrl = void 0;
+// ---------------------------------------------------------------------------
+// URL detection and parsing
+// ---------------------------------------------------------------------------
+function isFigmaUrl(url) {
+    try {
+        const { hostname } = new URL(url);
+        return hostname === 'figma.com' || hostname === 'www.figma.com';
+    }
+    catch {
+        return false;
+    }
+}
+exports.isFigmaUrl = isFigmaUrl;
+function parseFigmaNodeUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: "${url}"`);
+    }
+    if (!isFigmaUrl(url)) {
+        throw new Error(`Not a Figma URL: "${url}"`);
+    }
+    // Pathname: /{type}/{fileId}/{title}  e.g. /design/abc123/Untitled
+    const segments = u.pathname.split('/').filter(Boolean);
+    const fileId = segments[1];
+    if (!fileId) {
+        throw new Error(`Could not extract file ID from Figma URL: "${url}"`);
+    }
+    const rawNodeId = u.searchParams.get('node-id');
+    if (!rawNodeId) {
+        throw new Error(`No node-id parameter in Figma URL: "${url}"`);
+    }
+    // Figma encodes "1:2" as "1-2" in URLs; %3A is decoded to ":" automatically by URLSearchParams
+    const nodeId = rawNodeId.includes(':') ? rawNodeId : rawNodeId.replace('-', ':');
+    return { fileId, nodeId };
+}
+exports.parseFigmaNodeUrl = parseFigmaNodeUrl;
+/**
+ * The tag becomes the Eyes baseline step name, and Eyes matches steps by name, so it must derive only from
+ * stable identity. Figma's "Copy link to selection" appends a `t=` param that differs on every copy —
+ * keeping it means re-copying the link renames the step and orphans its accepted baseline.
+ *
+ * Drop only `t`: `node-id` is what distinguishes two frames of the same file, so stripping the whole query
+ * would give every frame in a file the same step name.
+ */
+function figmaStepTag(figmaUrl) {
+    const url = new URL(figmaUrl);
+    url.searchParams.delete('t');
+    return url.toString();
+}
+exports.figmaStepTag = figmaStepTag;
+// ---------------------------------------------------------------------------
+// figmaBaselines / mode resolution
+// ---------------------------------------------------------------------------
+// Resolves figmaBaselines + testName to the list of Figma URLs, or null when the test opts out.
+function resolveFigmaUrls(figmaBaselines, testName) {
+    if (typeof figmaBaselines === 'string') {
+        return figmaBaselines === '' ? null : [figmaBaselines];
+    }
+    // No testName (should be set upstream) → no matching entry → falls through to the no-entry throw below.
+    const entry = testName === undefined ? undefined : figmaBaselines[testName];
+    if (entry === '' || (Array.isArray(entry) && entry.length === 0))
+        return null;
+    // An all-'' array (no real design anywhere) is treated as a missing entry, not an opt-out.
+    const isAllPlaceholders = Array.isArray(entry) && entry.every((url) => url === '');
+    if (entry === undefined || isAllPlaceholders) {
+        throw new Error(`setFigmaBaseline: no Figma URL configured for test "${testName}". ` +
+            `Add an entry in the figmaBaselines config option.`);
+    }
+    return Array.isArray(entry) ? entry : [entry];
+}
+exports.resolveFigmaUrls = resolveFigmaUrls;
+exports.FIGMA_MODES = ['figma-baseline', 'test-baseline', 'auto-baseline', 'disabled'];
+// The value can arrive from figmaOptions.mode or the env var, so the error names both.
+function resolveFigmaMode(value) {
+    if (value === undefined)
+        return 'auto-baseline';
+    if (!exports.FIGMA_MODES.includes(value)) {
+        throw new Error(`setFigmaBaseline: invalid Figma mode "${value}". Expected one of: ${exports.FIGMA_MODES.join(', ')}. ` +
+            `Set it via figmaOptions.mode or APPLITOOLS_FIGMA_MODE.`);
+    }
+    return value;
+}
+exports.resolveFigmaMode = resolveFigmaMode;
+// figma:mode is last because the cross-language generic tests assert the earlier properties by index —
+// emitters can only translate index access, not a lookup by name. Reordering breaks 4 languages' CI.
+function figmaMetadataToProperties(metadata, mode) {
+    return [
+        { name: 'figma:name', value: metadata.name },
+        { name: 'figma:type', value: metadata.type },
+        { name: 'figma:file-revision', value: metadata.revision },
+        { name: 'figma:file-last-modified', value: metadata.lastModifiedAt },
+        { name: 'figma:mode', value: mode },
+    ];
+}
+exports.figmaMetadataToProperties = figmaMetadataToProperties;
+// ---------------------------------------------------------------------------
+// Viewport math
+// ---------------------------------------------------------------------------
+// The smallest box that fits every given viewport (max width, max height).
+function boundingViewport(viewports) {
+    return {
+        width: Math.max(...viewports.map(v => v.width)),
+        height: Math.max(...viewports.map(v => v.height)),
+    };
+}
+exports.boundingViewport = boundingViewport;
+// THE figma viewport: bounding box across every step, height capped at maxViewportHeight. Drives the
+// baseline env label, the reference Eyes session, and the user's test viewport — so everything renders at one size.
+function computeFigmaViewport(stepViewports, maxViewportHeight) {
+    const bounds = boundingViewport(stepViewports);
+    return { width: bounds.width, height: Math.min(bounds.height, maxViewportHeight) };
+}
+exports.computeFigmaViewport = computeFigmaViewport;
+// minViewportSize floors a design's dimensions so a consumer with a minimum viewport (e.g. the UFG on a
+// small Storybook component) won't reject it; padding centers the design on a >=minSize white canvas.
+function paddedDesignSize(width, height, minSize) {
+    return {
+        width: Math.max(width, minSize),
+        height: Math.max(height, minSize),
+    };
+}
+exports.paddedDesignSize = paddedDesignSize;