@payloadcms/figma 0.0.1-alpha.69 → 0.0.1-alpha.70

package/dist/api/control-plane.js

@@ -8,7 +8,7 @@ import * as log from '../utils/log.js';
 /**
  * Get the Control Plane API base URL based on environment
  */ function getControlPlaneBaseUrl() {
-    return process.env.FIGMA_API_BASE_URL || getEnvConfig().apiBaseUrl;
+    return getEnvConfig().apiBaseUrl;
 }
 /**
  * Error thrown when Control Plane API calls fail

package/dist/api/figma-api.js

@@ -85,7 +85,7 @@ import * as log from '../utils/log.js';
             };
         }
         // REAL API IMPLEMENTATION
-        const baseUrl = process.env.FIGMA_API_BASE_URL || getEnvConfig().apiBaseUrl;
+        const baseUrl = getEnvConfig().apiBaseUrl;
         const url = `${baseUrl}/v1/cms/${tenantId}/token/`;
         const response = await fetch(url, {
             headers: getAuthHeaders(credential),
@@ -197,7 +197,7 @@ import * as log from '../utils/log.js';
  * @returns FigmaUserInfo with user profile data
  * @throws {FigmaApiError} If the API call fails
  */ export async function getUserInfo(credential) {
-    const baseUrl = process.env.FIGMA_API_BASE_URL || getEnvConfig().apiBaseUrl;
+    const baseUrl = getEnvConfig().apiBaseUrl;
     const url = `${baseUrl}/v1/me`;
     try {
         const response = await fetch(url, {

package/dist/auth/jwt-validator.js

@@ -1,6 +1,6 @@
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 import { JWKSMultipleMatchingKeys, JWKSNoMatchingKey, JWSInvalid, JWSSignatureVerificationFailed, JWTExpired } from 'jose/errors';
-import { ENV_CONFIG } from '../constants.js';
+import { getEnvConfig } from '../constants.js';
 /**
  * JWT validation error with specific error codes
  */ export class JWTValidationError extends Error {
@@ -28,7 +28,7 @@ import { ENV_CONFIG } from '../constants.js';
  * @param environment - Figma environment ('production' or 'staging')
  * @returns JWKS resolver function
  */ function getJWKSResolver(environment) {
-    const jwksUri = ENV_CONFIG[environment].jwksUri;
+    const jwksUri = getEnvConfig(environment).jwksUri;
     if (!jwksResolvers.has(jwksUri)) {
         jwksResolvers.set(jwksUri, createRemoteJWKSet(new URL(jwksUri), {
             cacheMaxAge: 24 * 60 * 60 * 1000,

package/dist/cli.js

@@ -46,6 +46,7 @@ class Main {
             '--json': Boolean,
             '--name': String,
             '--no-skill': Boolean,
+            '--payload-version': String,
             '--skip-auth': Boolean,
             '--skip-build': Boolean,
             '--template': String,
@@ -150,6 +151,7 @@ class Main {
                         env: this.args['--env'],
                         force: this.args['--force'],
                         noSkill: this.args['--no-skill'],
+                        payloadVersion: this.args['--payload-version'],
                         skipAuth: this.args['--skip-auth'],
                         template: this.args['--template']
                     });

package/dist/commands/init.d.ts

@@ -14,6 +14,8 @@ export interface InitCommandOptions {
     name?: string;
     /** Skip Payload skill installation */
     noSkill?: boolean;
+    /** npm dist-tag or explicit version for core payload packages (e.g. 'latest', 'canary', '3.40.0'); defaults to 'latest' */
+    payloadVersion?: string;
     /** Skip authentication check (for testing/development) */
     skipAuth?: boolean;
     /** GitHub template override, e.g. "v3.80.0:website" or "owner/repo#ref:template-path" */

package/dist/commands/init.js

@@ -341,7 +341,7 @@ async function maybeInstallPayloadSkill(args) {
         };
         s.start(`Downloading template "${resolvedSource.templatePath}" from ` + `${resolvedSource.owner}/${resolvedSource.repo}@${resolvedSource.ref}...`);
         try {
-            await scaffoldProject(fullPath, projectName, packageManager, templateSource);
+            await scaffoldProject(fullPath, projectName, packageManager, templateSource, options.payloadVersion);
             s.stop(pc.green('✓ Template downloaded'));
             s.start('Installing dependencies...');
             await installDependencies(fullPath, packageManager);

package/dist/config/oauth.d.ts

@@ -4,14 +4,14 @@ export declare const DEFAULT_CALLBACK_PORT: number;
 /**
  * Get OAuth configuration for current environment.
  *
- * Honors env overrides:
- *   FIGMA_API_BASE_URL → tokenUrl, refreshUrl
- *   FIGMA_WEB_BASE_URL → authorizationUrl (appends /oauth)
+ * `apiBaseUrl` (FIGMA_API_BASE_URL) and `authorizationUrl` (FIGMA_WEB_BASE_URL)
+ * are resolved by `getEnvConfig`; this function only layers on the OAuth-client
+ * specifics it owns:
  *   FIGMA_CLIENT_ID    → clientId
  *   FIGMA_REDIRECT_URI → redirectUri
  *
  * When FIGMA_INFRA_ENV=devbox, FIGMA_API_BASE_URL and FIGMA_WEB_BASE_URL are
- * required (ENV_CONFIG.devbox has empty URL defaults to fail-closed).
+ * required (the devbox preset has empty URL defaults, to fail closed).
  */
 export declare function getOAuthConfig(): OAuthConfig;
 export declare const TOKEN_EXPIRY_BUFFER_SECONDS = 300;

package/dist/config/oauth.js

@@ -9,19 +9,16 @@ export const DEFAULT_CALLBACK_PORT = DEFAULT_CALLBACK_PORTS[0];
 /**
  * Get OAuth configuration for current environment.
  *
- * Honors env overrides:
- *   FIGMA_API_BASE_URL → tokenUrl, refreshUrl
- *   FIGMA_WEB_BASE_URL → authorizationUrl (appends /oauth)
+ * `apiBaseUrl` (FIGMA_API_BASE_URL) and `authorizationUrl` (FIGMA_WEB_BASE_URL)
+ * are resolved by `getEnvConfig`; this function only layers on the OAuth-client
+ * specifics it owns:
  *   FIGMA_CLIENT_ID    → clientId
  *   FIGMA_REDIRECT_URI → redirectUri
  *
  * When FIGMA_INFRA_ENV=devbox, FIGMA_API_BASE_URL and FIGMA_WEB_BASE_URL are
- * required (ENV_CONFIG.devbox has empty URL defaults to fail-closed).
+ * required (the devbox preset has empty URL defaults, to fail closed).
  */ export function getOAuthConfig() {
-    const { apiBaseUrl: defaultApi, authorizationUrl: defaultAuth, clientId } = getEnvConfig();
-    const apiBaseUrl = process.env.FIGMA_API_BASE_URL || defaultApi;
-    const webBase = process.env.FIGMA_WEB_BASE_URL;
-    const authorizationUrl = webBase ? `${webBase}/oauth` : defaultAuth;
+    const { apiBaseUrl, authorizationUrl, clientId } = getEnvConfig();
     if (getInfraEnvironment() === 'devbox' && (!apiBaseUrl || !authorizationUrl)) {
         throw new Error('FIGMA_API_BASE_URL and FIGMA_WEB_BASE_URL must be set when FIGMA_INFRA_ENV=devbox');
     }

package/dist/constants.d.ts

@@ -18,11 +18,6 @@ type EnvironmentConfig = {
     /** JSON Web Key Set URL for token validation */
     jwksUri: string;
 };
-/**
- * Environment-specific configuration for Figma integration.
- * Selected via FIGMA_INFRA_ENV ('production' | 'staging'), defaults to 'production'.
- */
-export declare const ENV_CONFIG: Record<Environment, EnvironmentConfig>;
 /**
  * User-facing error message when Content API returns 404 or 410.
  * Used by the db adapter for consistent messaging at runtime.
@@ -42,13 +37,36 @@ export declare function getProjectNotFoundMessage(params: {
  */
 export declare function setInfraEnvironment(env: Environment | undefined): void;
 /**
- * Get current Figma infrastructure environment
- * Priority: 1) setInfraEnvironment override, 2) FIGMA_INFRA_ENV env var, 3) .env file, 4) 'production' default
- */
-/**
- * Get the resolved EnvironmentConfig for the current infrastructure environment
+ * Resolve the EnvironmentConfig for an infrastructure environment, applying the
+ * `process.env` overrides that the Make-preview sandbox (and devbox/staging)
+ * depend on. This is a FUNCTION, not a populated constant, because those env
+ * vars may be set after module load — resolving them lazily at call time keeps
+ * the values current (the empty `devbox` preset is filled here, not at import).
+ *
+ * This is the single place these `process.env` overrides are parsed; callers
+ * (including `getOAuthConfig`) read the resolved values from here rather than
+ * re-parsing the env vars themselves. Three overrides, each keyed off the axis
+ * it belongs to:
+ *
+ * - `apiBaseUrl` ← `FIGMA_API_BASE_URL` (Control Plane / token host).
+ *
+ * - `authorizationUrl` / `identityMetadata` ← `FIGMA_WEB_BASE_URL`. The
+ *   authorization code is minted by the SAME Figma host the editor runs on, so
+ *   the token exchange / OIDC discovery must hit THAT host. Without this the
+ *   plugin falls back to `www.figma.com`, the devbox-minted code is rejected
+ *   with `invalid_grant`, and the admin login loops forever.
+ *
+ * - `jwksUri` ← `FIGMA_CONTENT_API_URL` (the content backend that signs the
+ *   project token, independent of the OAuth host — see `deriveContentJwksUri`).
+ *
+ * In production the platform injects `FIGMA_WEB_BASE_URL=https://www.figma.com`
+ * and a `figmacontent.com` content URL, so the derived values equal the presets
+ * and behavior is unchanged.
+ *
+ * @param environment - the infrastructure environment to resolve; defaults to
+ *   the one reported by `getInfraEnvironment()`.
  */
-export declare function getEnvConfig(): EnvironmentConfig;
+export declare function getEnvConfig(environment?: Environment): EnvironmentConfig;
 export declare function getInfraEnvironment(): Environment;
 export {};
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -2,7 +2,7 @@ import { getEnvVarSync } from './utils/env-management.js';
 /**
  * Environment-specific configuration for Figma integration.
  * Selected via FIGMA_INFRA_ENV ('production' | 'staging'), defaults to 'production'.
- */ export const ENV_CONFIG = {
+ */ const ENV_CONFIG = {
     production: {
         apiBaseUrl: 'https://api.figma.com',
         authorizationUrl: 'https://www.figma.com/oauth',
@@ -60,9 +60,78 @@ let envOverride;
  * Get current Figma infrastructure environment
  * Priority: 1) setInfraEnvironment override, 2) FIGMA_INFRA_ENV env var, 3) .env file, 4) 'production' default
  */ /**
- * Get the resolved EnvironmentConfig for the current infrastructure environment
- */ export function getEnvConfig() {
-    return ENV_CONFIG[getInfraEnvironment()];
+ * Derive the project-token JWKS URI from the content/CMS API domain
+ * (`FIGMA_CONTENT_API_URL`), or `undefined` when it is unset or malformed.
+ *
+ * The project token is signed by the content backend, whose JWKS host tracks
+ * the content env — NOT the OAuth/infra env. A devbox or staging tenant runs
+ * on the staging content backend (`*.figmacontentstaging.com`) even when OAuth
+ * points at a devbox host, so its tokens are signed by the staging key and must
+ * validate against `static.figmacontentstaging.com`. Returning `undefined` lets
+ * the caller fall back to the per-env preset.
+ */ function deriveContentJwksUri() {
+    const contentApiUrl = process.env.FIGMA_CONTENT_API_URL;
+    if (!contentApiUrl) {
+        return undefined;
+    }
+    try {
+        const host = new URL(contentApiUrl).hostname;
+        const match = host.match(/(figmacontentstaging\.com|figmacontent\.com)$/);
+        if (match) {
+            return `https://static.${match[1]}/.well_known/jwks.json`;
+        }
+    } catch  {
+    // Malformed URL — fall through to the per-env preset.
+    }
+    return undefined;
+}
+/**
+ * Resolve the EnvironmentConfig for an infrastructure environment, applying the
+ * `process.env` overrides that the Make-preview sandbox (and devbox/staging)
+ * depend on. This is a FUNCTION, not a populated constant, because those env
+ * vars may be set after module load — resolving them lazily at call time keeps
+ * the values current (the empty `devbox` preset is filled here, not at import).
+ *
+ * This is the single place these `process.env` overrides are parsed; callers
+ * (including `getOAuthConfig`) read the resolved values from here rather than
+ * re-parsing the env vars themselves. Three overrides, each keyed off the axis
+ * it belongs to:
+ *
+ * - `apiBaseUrl` ← `FIGMA_API_BASE_URL` (Control Plane / token host).
+ *
+ * - `authorizationUrl` / `identityMetadata` ← `FIGMA_WEB_BASE_URL`. The
+ *   authorization code is minted by the SAME Figma host the editor runs on, so
+ *   the token exchange / OIDC discovery must hit THAT host. Without this the
+ *   plugin falls back to `www.figma.com`, the devbox-minted code is rejected
+ *   with `invalid_grant`, and the admin login loops forever.
+ *
+ * - `jwksUri` ← `FIGMA_CONTENT_API_URL` (the content backend that signs the
+ *   project token, independent of the OAuth host — see `deriveContentJwksUri`).
+ *
+ * In production the platform injects `FIGMA_WEB_BASE_URL=https://www.figma.com`
+ * and a `figmacontent.com` content URL, so the derived values equal the presets
+ * and behavior is unchanged.
+ *
+ * @param environment - the infrastructure environment to resolve; defaults to
+ *   the one reported by `getInfraEnvironment()`.
+ */ export function getEnvConfig(environment = getInfraEnvironment()) {
+    const config = {
+        ...ENV_CONFIG[environment]
+    };
+    const apiBaseUrl = process.env.FIGMA_API_BASE_URL?.replace(/\/+$/, '');
+    if (apiBaseUrl) {
+        config.apiBaseUrl = apiBaseUrl;
+    }
+    const webBaseUrl = process.env.FIGMA_WEB_BASE_URL?.replace(/\/+$/, '');
+    if (webBaseUrl) {
+        config.authorizationUrl = `${webBaseUrl}/oauth`;
+        config.identityMetadata = `${webBaseUrl}/.well-known/openid-configuration`;
+    }
+    const jwksUri = deriveContentJwksUri();
+    if (jwksUri) {
+        config.jwksUri = jwksUri;
+    }
+    return config;
 }
 export function getInfraEnvironment() {
     if (envOverride) {

package/dist/db-content-api/index.js

@@ -225,6 +225,13 @@ async function queryDrafts(args) {
     };
 }
 async function createVersion(args) {
+    const versionContent = dataToContentAPI(this.payload, args.collectionSlug, args.versionData, {
+        applyDefaults: true,
+        publishedLocale: args.publishedLocale
+    });
+    if (args.autosave) {
+        versionContent._payloadAutosave = true;
+    }
     const { data: response, error } = await this.client.POST('/api/v0/document_versions:create', {
         body: {
             collection: args.collectionSlug,
@@ -234,10 +241,7 @@ async function createVersion(args) {
                 latest: true,
                 parent: String(args.parent),
                 updatedAt: args.updatedAt,
-                version: dataToContentAPI(this.payload, args.collectionSlug, args.versionData, {
-                    applyDefaults: true,
-                    publishedLocale: args.publishedLocale
-                })
+                version: versionContent
             }
         }
     });
@@ -262,6 +266,9 @@ async function updateVersion(args) {
     const locale = addFallbackLocale(args.locale, this.payload);
     const { publishedLocale, version, ...versionMeta } = args.versionData;
     const resolvedVersion = resolveVersionContent(version, versionMeta);
+    const versionContent = dataToContentAPI(this.payload, args.collection, resolvedVersion, {
+        publishedLocale
+    });
     const { data: response, error } = await this.client.POST('/api/v0/document_versions:update', {
         body: {
             collection: args.collection,
@@ -273,9 +280,7 @@ async function updateVersion(args) {
                 latest: versionMeta.latest,
                 parent: versionMeta.parent != null ? String(versionMeta.parent) : undefined,
                 updatedAt: versionMeta.updatedAt,
-                version: dataToContentAPI(this.payload, args.collection, resolvedVersion, {
-                    publishedLocale
-                })
+                version: versionContent
             },
             where: convertPayloadWhereToContentAPI(where, {
                 stripVersionPrefix: true
@@ -620,6 +625,7 @@ async function countVersions(args) {
             contentSystemId: this.contentSystemId,
             locale,
             where: convertPayloadWhereToContentAPI(args.where, {
+                parentToDocumentId: true,
                 stripVersionPrefix: true
             }),
             ...buildMeta(this.payload, {

package/dist/db-content-api/temp-utilities/unwrapDocument.js

@@ -19,6 +19,11 @@ export function unwrapDocument(args) {
         const baseDoc = {
             ...versionDoc
         };
+        const versionData = baseDoc.version;
+        if (versionData && '_payloadAutosave' in versionData) {
+            baseDoc.autosave = versionData._payloadAutosave;
+            delete versionData._payloadAutosave;
+        }
         // Transform data from Content API format to Payload format
         if (collectionSlug) {
             // Only transform the nested 'version' field

package/dist/oauth/components/LoginButton/index.js

@@ -9,7 +9,7 @@ const baseClass = 'oauth-login';
 // Max time we wait for the parent (figma.com) to respond with a code after
 // posting `mint-cms-oauth-code`. If we hit this without a reply, we assume
 // the parent isn't going to respond and fall back to the manual login button.
-const AUTO_LOGIN_PARENT_REPLY_TIMEOUT_MS = 5000;
+const AUTO_LOGIN_PARENT_REPLY_TIMEOUT_MS = 10000;
 // Figma logo SVG colored version
 // const FigmaIcon: React.FC = () => (
 //   <svg fill="none" height="27" viewBox="0 0 400 600" width="18">

package/dist/oauth/endpoints/getLoginEndpoint.js

@@ -36,7 +36,17 @@ export const getLoginEndpoint = ({ collection, collectionOptions, endpointSlug,
                 }
                 const stateRaw = jsonBody.state;
                 const state = JSON.parse(Buffer.from(stateRaw, 'base64').toString('utf-8'));
-                const redirectServerURL = state.serverURL || pluginOptions.redirectServerURL || config.serverURL;
+                // Resolve the post-login redirect base. This MUST match the precedence
+                // used when the OAuth `redirect_uri` is minted at `/meta`
+                // (`getAuthorizeURL`: redirectServerURL → config.serverURL →
+                // state.serverURL). `state.serverURL` is the iframe's untrusted
+                // `window.location.origin` (a `/meta` query param), so it must rank
+                // LAST: trusting it first lets the redirect target diverge from the
+                // server-configured origin — in the Make preview that origin is http
+                // (mixed content) and, more visibly, it isn't in Payload's auto-derived
+                // `config.csrf` allowlist (sanitizeConfig pushes `config.serverURL`),
+                // so the CSRF origin check below 403s the callback.
+                const redirectServerURL = pluginOptions.redirectServerURL || config.serverURL || state.serverURL;
                 let failedRedirect = formatAdminURL({
                     adminRoute,
                     path: '/login',

package/dist/oauth/utilities/getAuthorizeURL.d.ts

@@ -59,11 +59,22 @@ export declare const OAUTH_STATE_CSRF_COOKIE_NAME = "__Host-payload-oauth-state_
  * /sso/login, AND so the iframe auto-login path works (the iframe is a
  * third-party context from the top-level Figma page). Path=/ is required
  * by the `__Host-` prefix.
+ *
+ * `Partitioned` (CHIPS) is required because the Make preview embeds the
+ * admin panel in a cross-site iframe. Under Chrome's third-party-cookie
+ * restrictions a `SameSite=None` cookie set in a third-party context is
+ * NOT sent back unless it is partitioned by the top-level site. Without it
+ * the `__Host-payload-oauth-state_csrf` cookie is dropped on the way back
+ * to /sso/login, the cookie↔state.csrf binding check fails, and login dies
+ * with "CSRF cookie mismatch" (intermittent sign-in loop). `__Host-` and
+ * `Partitioned` are mutually compatible.
  */
 export declare const buildCsrfCookieHeader: (nonce: string) => string;
 /**
  * `Set-Cookie` header to clear the CSRF cookie after a successful (or
  * failed) callback. Same attributes as the set version, plus Max-Age=0.
+ * Must include `Partitioned` so the clear targets the same partitioned
+ * cookie jar the set wrote to (an unpartitioned clear would not match).
  */
 export declare const buildCsrfCookieClearHeader: () => string;
 export {};

package/dist/oauth/utilities/getAuthorizeURL.js

@@ -64,22 +64,35 @@ export const getAuthorizeURL = async ({ collection, collectionOptions, endpointS
  * /sso/login, AND so the iframe auto-login path works (the iframe is a
  * third-party context from the top-level Figma page). Path=/ is required
  * by the `__Host-` prefix.
+ *
+ * `Partitioned` (CHIPS) is required because the Make preview embeds the
+ * admin panel in a cross-site iframe. Under Chrome's third-party-cookie
+ * restrictions a `SameSite=None` cookie set in a third-party context is
+ * NOT sent back unless it is partitioned by the top-level site. Without it
+ * the `__Host-payload-oauth-state_csrf` cookie is dropped on the way back
+ * to /sso/login, the cookie↔state.csrf binding check fails, and login dies
+ * with "CSRF cookie mismatch" (intermittent sign-in loop). `__Host-` and
+ * `Partitioned` are mutually compatible.
  */ export const buildCsrfCookieHeader = (nonce)=>[
         `${OAUTH_STATE_CSRF_COOKIE_NAME}=${nonce}`,
         'HttpOnly',
         'Secure',
         'SameSite=None',
+        'Partitioned',
         'Path=/',
         'Max-Age=600'
     ].join('; ');
 /**
  * `Set-Cookie` header to clear the CSRF cookie after a successful (or
  * failed) callback. Same attributes as the set version, plus Max-Age=0.
+ * Must include `Partitioned` so the clear targets the same partitioned
+ * cookie jar the set wrote to (an unpartitioned clear would not match).
  */ export const buildCsrfCookieClearHeader = ()=>[
         `${OAUTH_STATE_CSRF_COOKIE_NAME}=`,
         'HttpOnly',
         'Secure',
         'SameSite=None',
+        'Partitioned',
         'Path=/',
         'Max-Age=0'
     ].join('; ');

package/dist/utils/messages.js

@@ -41,6 +41,7 @@ export function helpMessage() {
       ${pc.dim('--force')}                               Force reconfiguration of existing project
       ${pc.dim('--no-skill')}                            Skip installing the Payload skill into .claude/skills/payload/
       ${pc.dim('--template, -t <spec>')}                  Override scaffold template (e.g. v3.80.0:website, owner/repo#ref:path)
+      ${pc.dim('--payload-version <tag|version>')}        Core Payload npm dist-tag or version (default latest; e.g. canary, 3.40.0)
 
   ${pc.bold('BOOTSTRAP COMMAND')}
 

package/dist/utils/payload-package-check.js

@@ -57,8 +57,11 @@ import * as log from './log.js';
     return new Promise((resolve, reject)=>{
         const command = packageManager;
         const packageSpecs = packages.map(({ name, version })=>name.endsWith('.tgz') ? name : `${name}@${version ?? 'latest'}`);
+        const installVerb = packageManager === 'npm' ? 'install' : 'add';
+        // -E pins exact version
         const args = [
-            packageManager === 'npm' ? 'install' : 'add',
+            installVerb,
+            '-E',
             ...packageSpecs
         ];
         log.debug(`Running: ${command} ${args.join(' ')} in ${projectPath}`);

package/dist/utils/project.d.ts

@@ -23,8 +23,11 @@ export declare function validatePayloadVersion(version: string): boolean;
  *
  * @param projectPath - Path where to create the project
  * @param projectName - Name for the project
+ * @param packageManager - Package manager to use
+ * @param templateSource - Optional template source override
+ * @param payloadVersion - npm dist-tag or explicit version for core payload packages (default 'latest')
  */
-export declare function scaffoldProject(projectPath: string, projectName: string, packageManager?: PackageManager, templateSource?: Partial<TemplateSource>): Promise<void>;
+export declare function scaffoldProject(projectPath: string, projectName: string, packageManager?: PackageManager, templateSource?: Partial<TemplateSource>, payloadVersion?: string): Promise<void>;
 /**
  * Initialize git repository after all setup is complete
  *

package/dist/utils/project.js

@@ -67,27 +67,38 @@ import { getOwnVersion } from './version-check.js';
     return majorVersion === 3;
 }
 /**
- * Fetch the latest version of a package from npm registry
+ * Resolve a package version from an npm dist-tag or an explicit version.
  *
- * @param packageName - Package name to fetch version for
- * @returns Latest version string
- */ async function getLatestPackageVersion(packageName) {
-    const response = await fetch(`https://registry.npmjs.org/-/package/${packageName}/dist-tags`);
-    if (!response.ok) {
-        throw new Error(`Failed to fetch version for ${packageName}: ${response.statusText}`);
+ * A value matching a published dist-tag (e.g. 'latest', 'canary') resolves to
+ * that tag's concrete version. Any other value is treated as an explicit version
+ * and verified against the registry.
+ *
+ * @param packageName - Package name to look up
+ * @param versionOrTag - npm dist-tag or explicit semver version; defaults to 'latest'
+ * @returns The concrete version string to pin
+ */ async function resolvePackageVersion(packageName, versionOrTag = 'latest') {
+    const distTagsResponse = await fetch(`https://registry.npmjs.org/-/package/${packageName}/dist-tags`);
+    if (!distTagsResponse.ok) {
+        throw new Error(`Failed to fetch versions for ${packageName}: ${distTagsResponse.statusText}`);
+    }
+    const distTags = await distTagsResponse.json();
+    const tagged = distTags[versionOrTag];
+    if (typeof tagged === 'string') {
+        return tagged;
     }
-    const data = await response.json();
-    if (typeof data.latest !== 'string') {
-        throw new Error(`Invalid version data received for ${packageName}`);
+    // Not a dist-tag — treat as an explicit version and verify it's published.
+    const versionResponse = await fetch(`https://registry.npmjs.org/${packageName}/${versionOrTag}`);
+    if (versionResponse.ok) {
+        return versionOrTag;
     }
-    return data.latest;
+    throw new Error(`No "${versionOrTag}" version or dist-tag published for ${packageName}. Available dist-tags: ${Object.keys(distTags).join(', ')}`);
 }
 /**
  * Replace workspace versions in package.json with actual versions
  *
  * @param packageJson - Package JSON object to update
- * @param latestVersion - Latest Payload version to use
- */ function replaceWorkspaceVersions(packageJson, latestVersion, figmaVersion) {
+ * @param coreVersion - Resolved core Payload version to use
+ */ function replaceWorkspaceVersions(packageJson, coreVersion, figmaVersion) {
     const deps = packageJson.dependencies;
     if (!deps) {
         return;
@@ -96,9 +107,9 @@ import { getOwnVersion } from './version-check.js';
         if (key === '@payloadcms/figma') {
             deps[key] = figmaVersion;
         } else if (typeof value === 'string' && value.startsWith('workspace:')) {
-            deps[key] = latestVersion;
+            deps[key] = coreVersion;
         } else if (key === 'payload' || key.startsWith('@payloadcms/')) {
-            deps[key] = latestVersion;
+            deps[key] = coreVersion;
         }
     }
     const devDeps = packageJson.devDependencies;
@@ -109,9 +120,9 @@ import { getOwnVersion } from './version-check.js';
         if (key === '@payloadcms/figma') {
             devDeps[key] = figmaVersion;
         } else if (typeof value === 'string' && value.startsWith('workspace:')) {
-            devDeps[key] = latestVersion;
+            devDeps[key] = coreVersion;
         } else if (key === 'payload' || key.startsWith('@payloadcms/')) {
-            devDeps[key] = latestVersion;
+            devDeps[key] = coreVersion;
         }
     }
 }
@@ -120,7 +131,10 @@ import { getOwnVersion } from './version-check.js';
  *
  * @param projectPath - Path where to create the project
  * @param projectName - Name for the project
- */ export async function scaffoldProject(projectPath, projectName, packageManager = 'npm', templateSource) {
+ * @param packageManager - Package manager to use
+ * @param templateSource - Optional template source override
+ * @param payloadVersion - npm dist-tag or explicit version for core payload packages (default 'latest')
+ */ export async function scaffoldProject(projectPath, projectName, packageManager = 'npm', templateSource, payloadVersion = 'latest') {
     // Create project directory if it doesn't exist
     await fs.mkdir(projectPath, {
         recursive: true
@@ -130,9 +144,9 @@ import { getOwnVersion } from './version-check.js';
     // Apply Lambda modifications BEFORE updating package.json
     // This ensures we don't overwrite version replacements
     await applyLambdaModifications(projectPath, packageManager);
-    // Get latest Payload version from npm and CLI's own version
-    const [latestVersion, figmaVersion] = await Promise.all([
-        getLatestPackageVersion('payload'),
+    // Resolve core Payload version from the selected dist-tag or version; figma uses CLI version
+    const [coreVersion, figmaVersion] = await Promise.all([
+        resolvePackageVersion('payload', payloadVersion),
         getOwnVersion()
     ]);
     // Delete any existing lock files from template (they reference workspace:* versions)
@@ -156,7 +170,7 @@ import { getOwnVersion } from './version-check.js';
     const packageJson = JSON.parse(packageJsonContent);
     packageJson.name = projectName;
     // Replace workspace:* versions with actual versions
-    replaceWorkspaceVersions(packageJson, latestVersion, figmaVersion);
+    replaceWorkspaceVersions(packageJson, coreVersion, figmaVersion);
     await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf-8');
     // Ensure .gitignore has required entries
     // Note: .env file is created by init command with FIGMA_CONTENT_API_CONTENT_SYSTEM_ID

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/figma",
-  "version": "0.0.1-alpha.69",
+  "version": "0.0.1-alpha.70",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "exports": {
@@ -99,6 +99,8 @@
     "test": "TEST_UNIT=true vitest run",
     "test:int": "TEST_INT=true vitest run --config vitest.config.int.ts",
     "test:int:watch": "TEST_INT=true vitest --config vitest.config.int.ts",
+    "test:e2e": "TEST_E2E=true vitest run --config vitest.config.e2e.ts",
+    "test:e2e:watch": "TEST_E2E=true vitest --config vitest.config.e2e.ts",
     "test:watch": "TEST_UNIT=true vitest"
   }
 }