unframer 4.1.9 → 4.2.1

package/src/cli.ts

@@ -21,6 +21,7 @@ import {
     componentNameToPath,
     dedent,
     isTruthy,
+    kebabCase,
     logger,
     sleep,
     spinner,
@@ -42,7 +43,7 @@ export const cli = goke('unframer')
 
 let defaultOutDir = 'framer'
 
-cli.command('[projectId]', 'Run unframer with optional project ID')
+cli.command('[...projectIds]', 'Run unframer with one or more project IDs')
     .option('--outDir <dir>', 'Output directory')
     .option(
         '--external [package]',
@@ -52,7 +53,7 @@ cli.command('[projectId]', 'Run unframer with optional project ID')
     .option('--jsx', 'Output jsx code instead of minified .js code')
     .option('--debug', 'Enable debug logging')
     .option('--metafile', 'Generate meta.json file with build metadata')
-    .action(async function main(projectId, options) {
+    .action(async function main(projectIds, options) {
         const outDir = options.outDir || defaultOutDir
         const jsx = options.jsx ?? true
         const external_ = options.external
@@ -68,17 +69,35 @@ cli.command('[projectId]', 'Run unframer with optional project ID')
             const controller = new AbortController()
             const signal = controller.signal
             const watch = options.watch
-            if (projectId) {
-                const { config, cwd, websiteUrl } = await configFromFetch({
-                    allExternal,
-                    externalPackages,
-                    outDir,
-                    projectId,
-                })
+            if (projectIds.length > 0) {
+                if (watch && projectIds.length > 1) {
+                    console.error('--watch is only supported with a single project ID')
+                    process.exit(1)
+                }
+
+                // Fetch configs for all project IDs
+                const fetchResults = await Promise.all(
+                    projectIds.map((projectId) => {
+                        return configFromFetch({
+                            allExternal,
+                            externalPackages,
+                            outDir,
+                            projectId,
+                        })
+                    }),
+                )
+
+                // Merge configs when multiple projects are provided, otherwise use single config directly
+                const mergedConfig = fetchResults.length === 1
+                    ? fetchResults[0].config
+                    : mergeConfigs(fetchResults.map((r) => r.config))
+                const cwd = fetchResults[0].cwd
+                const websiteUrl = fetchResults[0].websiteUrl
+
                 const { rebuild, buildContext } = await bundle({
                     config: {
                         jsx,
-                        ...config,
+                        ...mergedConfig,
                     },
                     watch,
                     cwd,
@@ -419,14 +438,15 @@ const hasMcpCommand = cliArgs.includes('mcp')
 const hasProjectOption = cliArgs.some((arg) => {
     return arg === '--project' || arg.startsWith('--project=')
 })
-const shouldUseServerApiForProjectOption = hasMcpCommand && hasProjectOption
-const mcpMode = shouldUseServerApiForProjectOption
+const hasMcpEvalCommand = hasMcpCommand && cliArgs.includes('eval')
+const hasServerApiEnv = Boolean(process.env.FRAMER_PROJECT_URL || process.env.FRAMER_API_KEY)
+const shouldUseServerApi = hasMcpCommand && (hasProjectOption || hasMcpEvalCommand || hasServerApiEnv)
+const mcpMode = shouldUseServerApi
     ? 'server-api'
     : config.mode || (config.mcpUrl ? 'plugin' : undefined)
 
 if (mcpMode === 'server-api') {
     // Server API mode - use framer-api directly
-    // Commands are registered via registerServerApiCommands below
     await registerServerApiCommands()
 } else {
     // Plugin mode - use MCP transport
@@ -467,9 +487,112 @@ async function registerServerApiCommands() {
     // Dynamic import to avoid loading framer-api in plugin mode
     const { connect } = await import('framer-api')
 
+    // `mcp eval` — run arbitrary framer-api code against a project.
+    // Useful for testing API calls before implementing them in MCP tools.
+    // The `framer` client is available as a local variable inside the evaluated code.
+    cli.command('mcp eval [code]', 'Evaluate arbitrary framer-api code against a project')
+        .option(
+            '--project <url>',
+            'Framer project URL. Also reads FRAMER_PROJECT_URL env var.',
+        )
+        .action(async (code: string | undefined, options: { project?: string }) => {
+            // Read code from argument or stdin
+            let evalCode = code
+            if (!evalCode && !process.stdin.isTTY) {
+                const chunks: Buffer[] = []
+                for await (const chunk of process.stdin) {
+                    chunks.push(chunk)
+                }
+                evalCode = Buffer.concat(chunks).toString('utf-8').trim()
+            }
+            if (!evalCode) {
+                console.error('No code provided. Pass as argument or pipe via stdin.')
+                process.exit(1)
+            }
+
+            const projectUrl =
+                options.project ||
+                process.env.FRAMER_PROJECT_URL ||
+                loadConfig().framerProjectUrl
+            const apiKey =
+                process.env.FRAMER_API_KEY || loadConfig().framerApiKey
+
+            if (!projectUrl) {
+                console.error('Project URL required. Use --project option, FRAMER_PROJECT_URL env var, or set during login.')
+                process.exit(1)
+            }
+            if (!apiKey) {
+                console.error('API key required. Set FRAMER_API_KEY env var or run `unframer mcp login` first.')
+                process.exit(1)
+            }
+
+            let framerClient: Awaited<ReturnType<typeof connect>> | undefined
+            let actionError: unknown
+
+            try {
+                spinner.start('Connecting to Framer...')
+                framerClient = await connect(projectUrl, apiKey)
+                spinner.stop('Connected')
+
+                // Build an async function body. If the code is a single expression
+                // (no semicolons and no newlines), wrap it as a return so the result is captured.
+                const isExpression = !evalCode.includes(';') && !evalCode.includes('\n')
+                const functionBody = isExpression
+                    ? `return (${evalCode})`
+                    : evalCode
+
+                const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor as
+                    new (arg: string, body: string) => (framer: unknown) => Promise<unknown>
+                const fn = new AsyncFunction('framer', functionBody)
+                const result = await fn(framerClient)
+
+                if (result !== undefined) {
+                    const output = (() => {
+                        try {
+                            return JSON.stringify(result, null, 2)
+                        } catch {
+                            return String(result)
+                        }
+                    })()
+                    console.log(output)
+                }
+            } catch (error) {
+                actionError = error
+            } finally {
+                if (framerClient) {
+                    try {
+                        await framerClient.disconnect()
+                    } catch (disconnectError) {
+                        logger.error('Failed disconnecting from Framer:', disconnectError)
+                    }
+                }
+            }
+
+            if (actionError) {
+                console.error('Eval failed:', actionError instanceof Error ? actionError.message : actionError)
+                if (actionError instanceof Error && actionError.stack) {
+                    console.error(actionError.stack)
+                }
+                process.exit(1)
+            }
+        })
+
     // Import tool definitions and handler from plugin-mcp
     // Note: Run `pnpm --filter plugin-mcp build && pnpm --filter plugin-mcp gen-unframer` first
-    const { mcpTools, mcpToolHandler } = await import('./plugin-mcp-dist/lib/mcp-handlers.js')
+    let mcpTools: Awaited<typeof import('./plugin-mcp-dist/lib/mcp-handlers.js')>['mcpTools'] | undefined
+    let mcpToolHandler: Awaited<typeof import('./plugin-mcp-dist/lib/mcp-handlers.js')>['mcpToolHandler'] | undefined
+    try {
+        const imported = await import('./plugin-mcp-dist/lib/mcp-handlers.js')
+        mcpTools = imported.mcpTools
+        mcpToolHandler = imported.mcpToolHandler
+    } catch (error) {
+        if (hasMcpEvalCommand) {
+            // eval command only needs framer-api, not plugin-mcp handlers
+            logger.log('Could not load plugin-mcp handlers:', error instanceof Error ? error.message : error)
+        } else {
+            throw new Error('Failed to load plugin-mcp handlers. Run: pnpm --filter plugin-mcp tsc --incremental && pnpm --filter plugin-mcp gen-unframer', { cause: error })
+        }
+    }
     if (!mcpTools || !mcpToolHandler) {
         return
     }
@@ -613,6 +736,7 @@ async function registerServerApiCommands() {
             }
         })
     }
+
 }
 
 export type Config = {
@@ -662,6 +786,133 @@ type ComponentInstanceInPage = {
     webPageId: string
 }
 
+/**
+ * Merge multiple project configs into a single Config so esbuild bundles all
+ * components together and deduplicates shared chunks automatically.
+ *
+ * - Components maps are merged; on name collision the second project's component
+ *   is prefixed with the project name to disambiguate.
+ * - First project's projectId/projectName/fullFramerProjectId are used as the
+ *   primary identifiers (framerSiteId in ContextProviders).
+ * - Arrays (componentBreakpoints, tokens, locales, framerWebPages, etc.) are concatenated.
+ */
+function mergeConfigs(configs: Config[]): Config {
+    if (configs.length === 0) {
+        throw new Error('mergeConfigs called with empty array')
+    }
+    if (configs.length === 1) {
+        return configs[0]
+    }
+
+    const first = configs[0]
+
+    // Merge components maps, disambiguating name collisions.
+    // Track rename maps per config so we can update breakpoints and instances.
+    const mergedComponents: Record<string, string> = {}
+    const renameMaps: Map<string, string>[] = []
+
+    for (const config of configs) {
+        const projectSlug = kebabCase(config.projectName || config.projectId || '')
+        const renameMap = new Map<string, string>()
+        renameMaps.push(renameMap)
+
+        for (const [name, url] of Object.entries(config.components)) {
+            if (mergedComponents[name]) {
+                // Name collision: prefix with project slug, ensure uniqueness with numeric suffix
+                const base = projectSlug ? `${projectSlug}/${name}` : `${config.projectId}/${name}`
+                const disambiguated = uniqueComponentName(base, mergedComponents)
+                logger.log(`Component name collision for "${name}", renaming to "${disambiguated}"`)
+                renameMap.set(name, disambiguated)
+                mergedComponents[disambiguated] = url
+            } else {
+                mergedComponents[name] = url
+            }
+        }
+    }
+
+    // Merge componentBreakpoints, updating componentName for any renamed components
+    const mergedBreakpoints = configs.flatMap((config, i) => {
+        const renameMap = renameMaps[i]
+        return (config.componentBreakpoints || []).map((bp) => {
+            const renamed = renameMap.get(bp.componentName)
+            if (renamed) {
+                return { ...bp, componentName: renamed }
+            }
+            return bp
+        })
+    })
+
+    // Merge tokens, deduplicate by id (keep first occurrence)
+    const seenTokenIds = new Set<string>()
+    const mergedTokens = configs.flatMap((config) => {
+        return (config.tokens || []).filter((token) => {
+            if (seenTokenIds.has(token.id)) {
+                return false
+            }
+            seenTokenIds.add(token.id)
+            return true
+        })
+    })
+
+    // Merge locales, deduplicate by code
+    const seenLocaleCodes = new Set<string>()
+    const mergedLocales = configs.flatMap((config) => {
+        return (config.locales || []).filter((locale) => {
+            if (seenLocaleCodes.has(locale.code)) {
+                return false
+            }
+            seenLocaleCodes.add(locale.code)
+            return true
+        })
+    })
+
+    // Merge framerWebPages
+    const mergedWebPages = configs.flatMap((config) => {
+        return config.framerWebPages || []
+    })
+
+    // Merge componentInstancesInIndexPage, updating componentPathSlug for renamed components
+    const mergedInstances = configs.flatMap((config, i) => {
+        const renameMap = renameMaps[i]
+        return (config.componentInstancesInIndexPage || []).map((instance) => {
+            const renamed = renameMap.get(instance.componentPathSlug)
+            if (renamed) {
+                return { ...instance, componentPathSlug: renamed }
+            }
+            return instance
+        })
+    }).sort((a, b) => {
+        return a.pageOrdering - b.pageOrdering
+    })
+
+    const projectNames = configs
+        .map((c) => c.projectName)
+        .filter(isTruthy)
+    spinner.info(`Merging ${configs.length} projects: ${projectNames.join(', ')}`)
+
+    return {
+        ...first,
+        components: mergedComponents,
+        componentBreakpoints: mergedBreakpoints,
+        tokens: mergedTokens,
+        locales: mergedLocales,
+        framerWebPages: mergedWebPages,
+        componentInstancesInIndexPage: mergedInstances,
+    }
+}
+
+/** Generate a unique component name by appending a numeric suffix if the base already exists */
+function uniqueComponentName(base: string, existing: Record<string, string>): string {
+    if (!existing[base]) {
+        return base
+    }
+    let index = 2
+    while (existing[`${base}-${index}`]) {
+        index++
+    }
+    return `${base}-${index}`
+}
+
 export async function configFromFetch({
     projectId,
     externalPackages = [] as string[],

package/src/exporter.ts

@@ -8,8 +8,6 @@ const require = createRequire(import.meta.url)
 
 import { Sema } from 'async-sema'
 
-import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill'
-
 import { transform } from '@babel/core'
 import { exec } from 'child_process'
 import { error } from 'console'
@@ -219,7 +217,6 @@ export async function bundle({
                     missingPackages.add(pkg)
                 },
             }),
-            nodeModulesPolyfillPlugin({}),
             {
                 name: 'virtual loader',
                 setup(build) {
@@ -577,17 +574,28 @@ export async function bundle({
             ?.split('\n')
             .forEach((x) => logger.log(x))
 
+        function isChunkPath(filePath: string) {
+            return (
+                filePath.includes('/chunks/') ||
+                filePath.includes('\\chunks\\')
+            )
+        }
         const jsxFiles = buildResult.outputFiles
             .filter(
                 (x) =>
                     x.path.endsWith('.js') &&
+                    !isChunkPath(x.path) &&
                     fs.existsSync(getFilePaths(x.path, out).jsxPath),
             )
             .map((x) => getFilePaths(x.path, out).jsxPath)
         const outFiles = buildResult.outputFiles
             .map((x) => {
                 const paths = getFilePaths(x.path, out)
-                if (x.path.endsWith('.js') && fs.existsSync(paths.jsxPath)) {
+                if (
+                    x.path.endsWith('.js') &&
+                    !isChunkPath(x.path) &&
+                    fs.existsSync(paths.jsxPath)
+                ) {
                     return null // Will be handled by jsx files
                 }
                 return paths.finalJsPath
@@ -737,8 +745,17 @@ export async function bundle({
                         formatted = result.content
                     }
                 } catch (e) {
+                    spinner.warn(
+                        `Babel/Biome formatting failed for ${componentName}: ${e instanceof Error ? e.message : e}`,
+                    )
+                    logger.log(e instanceof Error ? e.stack : e)
                     notifyError(e, 'babel transform and format')
                 }
+            } else if (tooBig) {
+                const sizeMB = (file.text.length / (1024 * 1024)).toFixed(2)
+                spinner.warn(
+                    `Skipping JSX formatting for ${componentName} (${sizeMB} MB exceeds ${(tooBigSize / (1024 * 1024)).toFixed(2)} MB limit)`,
+                )
             }
 
             const prefix =
@@ -752,12 +769,24 @@ export async function bundle({
             // Always write the temp .js file for type extraction
             await fs.promises.writeFile(paths.tempJsPath, codeJs, 'utf-8')
 
-            // Only write .jsx file if it's different from existing or if formatting was done
+            // Write .jsx file if formatting succeeded, or fall back to writing
+            // unformatted .js content into the .jsx path when formatting fails
+            // (babel error, component too big, etc.) but a stale .jsx already
+            // exists on disk. Without this fallback the stale .jsx keeps old
+            // chunk imports while the old chunks are deleted, breaking the build.
             if (didFormat && codeJsx !== existing) {
                 await fs.promises.writeFile(paths.jsxPath, codeJsx, 'utf-8')
                 logger.log(`Updated JSX file for ${componentName}`)
             } else if (didFormat) {
                 logger.log(`JSX file unchanged for ${componentName}`)
+            } else if (existing && codeJs !== existing) {
+                // Formatting failed but .jsx exists with stale content (e.g.
+                // old chunk hashes). Overwrite with unformatted JS so imports
+                // stay in sync with the current build's chunks.
+                await fs.promises.writeFile(paths.jsxPath, codeJs, 'utf-8')
+                logger.log(
+                    `Updated JSX file (unformatted) for ${componentName}`,
+                )
             }
         }
         spinner.stop()
@@ -772,8 +801,12 @@ export async function bundle({
             if (file.path.endsWith('.js')) {
                 const paths = getFilePaths(file.path, out)
 
-                if (fs.existsSync(paths.jsxPath)) {
+                if (
+                    !isChunkPath(paths.tempJsPath) &&
+                    fs.existsSync(paths.jsxPath)
+                ) {
                     // Remove temp .js file if .jsx equivalent exists
+                    // (never applies to chunks which stay as .js)
                     logger.log(
                         'removing temp JS file with JSX equivalent:',
                         path.relative(out, paths.tempJsPath),

package/src/framer.d.ts

@@ -4859,4 +4859,132 @@ export declare const withVariantFX: <T extends MotionProps>(Component: React_2.C
 export { }
 export declare const combinedCSSRules: string[]
 
+export interface FramerMotionGlobalConfig {
+    useManualTiming?: boolean
+    instantAnimations?: boolean
+    skipAnimations?: boolean
+    mix?: unknown
+    WillChange?: new (value: string) => unknown
+}
+
+export interface FramerInjectedRuntimeImage {
+    src?: string
+    srcSet?: string
+}
+
+export interface FramerInjectedRuntimeRect {
+    width?: number
+    height?: number
+}
+
+export interface FramerInjectedRuntime {
+    imagePlaceholderSvg?: string
+    useImageSource?(image: FramerInjectedRuntimeImage, rect?: FramerInjectedRuntimeRect, nodeId?: string): string
+    useImageElement?(image: FramerInjectedRuntimeImage, rect?: FramerInjectedRuntimeRect, nodeId?: string): HTMLImageElement
+    canRenderOptimizedCanvasImage?(src?: string): boolean
+    isOnPageCanvas?: boolean
+}
+
+export interface FramerMotionFrameData {
+    delta: number
+    timestamp: number
+    isProcessing: boolean
+}
+
+export type FramerMotionFrameCallback = (frameData: FramerMotionFrameData) => void
+
+export interface FramerMotionFrameStep {
+    schedule(callback: FramerMotionFrameCallback, keepAlive?: boolean, immediate?: boolean): FramerMotionFrameCallback
+    cancel(callback: FramerMotionFrameCallback): void
+    process(frameData: FramerMotionFrameData): void
+}
+
+export type FramerMotionFrameStepName =
+    | 'setup'
+    | 'read'
+    | 'resolveKeyframes'
+    | 'preUpdate'
+    | 'update'
+    | 'preRender'
+    | 'render'
+    | 'postRender'
+
+export type FramerMotionFrameSteps = Record<FramerMotionFrameStepName, FramerMotionFrameStep>
+
+export interface FramerMotionTime {
+    now(): number
+    set(newTime: number): void
+}
+
+export interface FramerMotionGeneratorState<Value = unknown> {
+    value: Value
+    done?: boolean
+}
+
+export interface FramerMotionGenerator<Value = unknown> {
+    calculatedDuration?: number | null
+    next(time: number): FramerMotionGeneratorState<Value>
+    velocity?(time: number): number
+}
+
+export interface FramerMotionAnimationDriver {
+    now(): number
+    start(autoplay?: boolean): void
+    stop(): void
+}
+
+export interface FramerMotionAnimationOptions<Value = unknown> {
+    keyframes: Value[]
+    autoplay?: boolean
+    delay?: number
+    repeat?: number
+    repeatDelay?: number
+    repeatType?: 'loop' | 'reverse' | 'mirror'
+    velocity?: number
+    finalKeyframe?: Value
+    startTime?: number
+    allowFlatten?: boolean
+    motionValue?: { updatedAt?: number }
+    type?: (options: FramerMotionAnimationOptions<Value>) => FramerMotionGenerator<Value>
+    driver?: (update: (timestamp: number) => void) => FramerMotionAnimationDriver
+    onUpdate?(latest: Value): void
+    onPlay?(): void
+    onComplete?(): void
+    onCancel?(): void
+    onStop?(): void
+}
+
+export declare class JSAnimation<Value = unknown> implements PromiseLike<void> {
+    constructor(options: FramerMotionAnimationOptions<Value>)
+    options: FramerMotionAnimationOptions<Value>
+    state: 'idle' | 'running' | 'paused' | 'finished'
+    currentTime: number
+    playbackSpeed: number
+    readonly duration: number
+    readonly iterationDuration: number
+    time: number
+    speed: number
+    readonly finished: Promise<void>
+    then<TResult1 = void, TResult2 = never>(
+        onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: Error) => TResult2 | PromiseLike<TResult2>) | null,
+    ): Promise<TResult1 | TResult2>
+    play(): void
+    pause(): void
+    complete(): void
+    finish(): void
+    cancel(): void
+    stop(): void
+    tick(timestamp: number, sample?: boolean): FramerMotionGeneratorState<Value>
+    sample(sampleTime: number): FramerMotionGeneratorState<Value>
+    attachTimeline(timeline: { observe(animation: JSAnimation<Value>): VoidFunction }): VoidFunction
+}
+
+export declare const MotionGlobalConfig: FramerMotionGlobalConfig
+export declare const frameData: FramerMotionFrameData
+export declare const frameSteps: FramerMotionFrameSteps
+export declare const time: FramerMotionTime
+export declare const visualElementStore: WeakMap<object, unknown>
+export declare function _injectRuntime(injectedRuntime: FramerInjectedRuntime): void
+
 export * from 'real-framer-motion'