unframer 2.27.2 → 3.0.0

package/src/exporter.ts

@@ -19,6 +19,7 @@ import {
     babelPluginJsxTransform,
     removeJsxExpressionContainer,
 } from './babel-jsx.js'
+import { babelPluginTypedoc } from './babel-typedoc.js'
 import { propCamelCaseJustLikeFramer } from './compat.js'
 import {
     ComponentFontBundle,
@@ -48,6 +49,8 @@ import {
     stackblitzDemoExample,
     terminalMarkdown,
 } from './utils.js'
+import { installPackagesBatch } from './package-manager.js'
+import { version as currentUnframerVersion } from './version.js'
 
 import { Biome, Distribution } from '@biomejs/js-api'
 
@@ -78,6 +81,27 @@ export async function bundle({
         await fs.promises.mkdir(out, { recursive: true })
     } catch (e) {}
 
+    // Prefix for temporary .js files to avoid HMR issues
+    const tempJsPrefix = 'temp_'
+
+    // Helper function to handle file path transformations with temp prefix
+    function getFilePaths(filePath: string, outDir: string) {
+        const baseName = path.basename(filePath)
+        const dirName = path.dirname(filePath)
+        const tempFileName = tempJsPrefix + baseName
+        const tempFilePath = path.join(dirName, tempFileName)
+
+        return {
+            originalPath: filePath,
+            tempJsPath: path.resolve(outDir, tempFilePath),
+            finalJsPath: path.resolve(outDir, filePath),
+            jsxPath: path.resolve(outDir, filePath.replace(/\.js$/, '.jsx')),
+            tempFilePath,
+            baseName,
+            dirName,
+        }
+    }
+
     spinner.start('exporting components...')
 
     const otherRoutes = Object.fromEntries(
@@ -100,7 +124,7 @@ export async function bundle({
         }
     }
     const fn = watch ? context : fakeContext
-    let foundError = false
+    const missingPackages = new Set<string>()
 
     const buildContext = await fn({
         absWorkingDir: out,
@@ -130,9 +154,12 @@ export async function bundle({
                 signal,
                 externalPackages: config.externalPackages,
                 externalizeNpm: config.allExternal,
-                outDir: config.outDir,
+                outDir: out,
                 onMissingPackage: (e) => {
-                    foundError = true
+                    // No longer needed - packages are auto-installed
+                },
+                onCollectMissingPackage: (pkg) => {
+                    missingPackages.add(pkg)
                 },
             }),
             nodeModulesPolyfillPlugin({}),
@@ -150,6 +177,15 @@ export async function bundle({
                         { filter: /.*/, namespace: 'virtual' },
                         async (args) => {
                             const name = args.path
+
+                            // Handle virtual routes module
+                            if (name === '__routes') {
+                                return {
+                                    contents: `export const routes = ${JSON.stringify(otherRoutes, null, 2)};`,
+                                    loader: 'js',
+                                }
+                            }
+
                             const url = components[name]
                             const componentBreakpoints =
                                 config.componentBreakpoints?.filter(
@@ -184,6 +220,9 @@ export async function bundle({
                                       ])
                                     : {}
 
+                            // Use virtual routes module
+                            const routesImportPath = 'virtual:__routes'
+
                             return {
                                 contents: /** js **/ `
                                 'use client'
@@ -194,6 +233,7 @@ export async function bundle({
                                     signal,
                                 })}'
                                 import { WithFramerBreakpoints } from 'unframer'
+                                import { routes } from '${routesImportPath}'
                                 const locales = ${
                                     JSON.stringify(config.locales) || '[]'
                                 }
@@ -203,17 +243,12 @@ export async function bundle({
                                     2,
                                 )}
 
-                                Component.Responsive = ({ locale, ...rest }) => {
+
+                                function ComponentWithRoot({ locale, ...rest }) {
                                     return (
                                         <ContextProviders
-                                            routes={${JSON.stringify(
-                                                otherRoutes,
-                                            )}}
-                                            children={<WithFramerBreakpoints
-                                                        Component={Component}
-                                                        variants={defaultResponsiveVariants}
-                                                        {...rest}
-                                                    />}
+                                            routes={routes}
+                                            children={<Component {...rest} />}
                                             framerSiteId={${JSON.stringify(
                                                 config.fullFramerProjectId,
                                             )}}
@@ -222,16 +257,15 @@ export async function bundle({
                                         />
                                     )
                                 }
-
-                                export default function ComponentWithRoot({ locale, ...rest }) {
+                                ComponentWithRoot.Responsive = ({ locale, ...rest }) => {
                                     return (
                                         <ContextProviders
-                                            routes={${JSON.stringify(
-                                                otherRoutes,
-                                                null,
-                                                2,
-                                            )}}
-                                            children={<Component {...rest} />}
+                                            routes={routes}
+                                            children={<WithFramerBreakpoints
+                                                        Component={Component}
+                                                        variants={defaultResponsiveVariants}
+                                                        {...rest}
+                                                    />}
                                             framerSiteId={${JSON.stringify(
                                                 config.fullFramerProjectId,
                                             )}}
@@ -241,6 +275,7 @@ export async function bundle({
                                     )
                                 }
                                 Object.assign(ComponentWithRoot, Component)
+                                export default ComponentWithRoot
                                 `,
                                 loader: 'jsx',
                             }
@@ -258,10 +293,35 @@ export async function bundle({
     } "${config.projectName}", do not edit manually */\n`
 
     async function rebuild() {
+        // Clear missing packages for each rebuild (important for watch mode)
+        missingPackages.clear()
+        try {
+            const installedVersion = await resolvePackageVersion({
+                cwd: out,
+                pkg: 'unframer',
+            })
+            if (
+                isVersionGreater(
+                    installedVersion || '0.0.0',
+                    currentUnframerVersion || '0.0.0',
+                )
+            ) {
+                // Version mismatch, add with specific version
+                missingPackages.add(`unframer@${currentUnframerVersion}`)
+                spinner.info(
+                    `Different unframer version detected (${installedVersion}), will install unframer@${currentUnframerVersion}`,
+                )
+            }
+        } catch (e) {
+            // Unframer not installed, add with specific version
+            missingPackages.add(`unframer@${currentUnframerVersion}`)
+            spinner.info(
+                `Missing package detected: unframer@${currentUnframerVersion}`,
+            )
+        }
         const prevFiles = await recursiveReaddir(out)
         const buildResult = await buildContext.rebuild().catch((e) => {
             if (e.message.includes('No matching export ')) {
-                foundError = true
                 spinner.error(
                     `esbuild failed to import from an external package, this usually means that the npm package version in Framer is older than the latest.`,
                 )
@@ -275,117 +335,43 @@ export async function bundle({
 
         spinner.update('Finished build')
 
-        for (let file of buildResult.outputFiles!) {
-            const resultPathAbsJs = path.resolve(out, file.path)
-            const resultPathAbsJsx = resultPathAbsJs.replace(/\.js$/, '.jsx')
-
-            const existing = await fs.promises
-                .readFile(resultPathAbsJsx, 'utf-8')
-                .catch(() => null)
-            const tooBigSize = 0.7 * 1024 * 1024
+        // Install missing packages if any were collected
+        if (missingPackages.size > 0) {
+            const packagesToInstall = Array.from(missingPackages)
+            logger.log(
+                `Installing missing packages: ${packagesToInstall.join(', ')}`,
+            )
 
-            let formatted = file.text
+            const installResult = await installPackagesBatch({
+                packageNames: packagesToInstall,
+                cwd: out,
+                isDev: false,
+            })
 
-            let tooBig = file.text.length >= tooBigSize
-            let didFormat = false
-            if (
-                config.jsx &&
-                !tooBig &&
-                !resultPathAbsJs.includes('/chunks/') &&
-                !resultPathAbsJs.includes('\\chunks\\')
-            ) {
-                try {
-                    let res = transform(file.text || '', {
-                        babelrc: false,
-                        sourceType: 'module',
-                        plugins: [
-                            // babelPluginDeduplicateImports,
-                            babelPluginJsxTransform,
-                            removeJsxExpressionContainer,
-                        ],
-                        // ast: true,
-                        // code: false,
-                        filename: 'x.jsx',
-                        compact: false,
-                        sourceMaps: false,
-                    })
-                    if (res?.code) {
-                        if (!biome) {
-                            biome = await Biome.create({
-                                distribution: Distribution.NODE,
-                            })
-                        }
-                        let result = biome.formatContent(res.code, {
-                            filePath: 'example.jsx',
-                        })
-                        didFormat = true
-                        formatted = result.content
-                    }
-                } catch (e) {
-                    notifyError(e, 'babel transform and format')
-                }
+            if (!installResult.success) {
+                spinner.error(
+                    `Failed to install packages: ${installResult.error}`,
+                )
+                // Don't fail the build, just warn
             }
+        }
 
-            // let inputCode = res!.code!
-            // let shouldFormat = !tooBig && !file.path.includes('chunks')
-            // if (shouldFormat) {
-            //     spinner.update(`Formatting ${path.relative(out, file.path)}`)
-            //     formatted = dprint.format('file.jsx', file.text, {
-            //         lineWidth: 140,
-            //         quoteStyle: 'alwaysSingle',
-            //         trailingCommas: 'always',
-            //         semiColons: 'always',
-            //     })
-            // }
-            // if (tooBig) {
-            //     spinner.info(
-            //         `skipping formatting ${path.relative(
-            //             out,
-            //             file.path,
-            //         )}, too big`,
-            //     )
-            // }
-
-            // if (framerWebPages?.length) {
-            //     codeNew = replaceWebPageIds({
-            //         code: codeNew,
-            //         elements: framerWebPages,
-            //     })
-            // }
-            // const lines = findRelativeLinks(codeNew)
-            // if (lines.length) {
-            //     spinner.error(
-            //         `found broken links for ${path.relative(out, file.path)}`,
-            //     )
-            //     lines.forEach((line) => {
-            //         logger.log(`${path.resolve(out, file.path)}:${line + 1}`)
-            //     })
-            // }
-
+        // First, write raw JS files for type extraction with temp prefix
+        for (let file of buildResult.outputFiles!) {
+            const paths = getFilePaths(file.path, out)
             const prefix =
                 `// @ts-nocheck\n` + `/* eslint-disable */\n` + doNotEditComment
-            const codeJsx = prefix + formatted
             const codeJs = prefix + file.text
-            // if (existing === codeJsx) {
-            //     continue
-            // }
-            logger.log(`writing`, path.relative(out, file.path))
-            await fs.promises.mkdir(path.dirname(resultPathAbsJsx), {
+
+            logger.log(
+                `writing temp JS`,
+                path.relative(out, paths.tempFilePath),
+            )
+            await fs.promises.mkdir(path.dirname(paths.tempJsPath), {
                 recursive: true,
             })
-            if (codeJs !== codeJsx || !didFormat) {
-                await fs.promises.writeFile(resultPathAbsJs, codeJs, 'utf-8')
-            }
-            if (didFormat) {
-                await fs.promises.writeFile(resultPathAbsJsx, codeJsx, 'utf-8')
-            }
+            await fs.promises.writeFile(paths.tempJsPath, codeJs, 'utf-8')
         }
-        spinner.stop()
-        await fs.promises.writeFile(
-            path.resolve(out, '.cursorignore'),
-            `**/*.js\nchunks\n`,
-            'utf-8',
-        )
 
         if (!buildResult?.outputFiles) {
             throw new Error('Failed to generate result')
@@ -408,7 +394,8 @@ export async function bundle({
                     const name = path
                         .relative(out, file.path)
                         .replace(/\.jsx?$/, '')
-                    const resultPathAbs = path.resolve(out, file.path)
+                    const paths = getFilePaths(file.path, out)
+                    const resultPathAbs = paths.tempJsPath
                     if (!components[name]) {
                         return
                     }
@@ -419,6 +406,7 @@ export async function bundle({
                         return
                     }
                     logger.log(`extracting types for ${name}`)
+                    spinner.info(`Extracting types for component: ${name}`)
                     spinner.update(`Extracting types for ${name}`)
                     const { propertyControls, fonts } =
                         await extractPropControlsUnsafe(resultPathAbs, name)
@@ -432,21 +420,23 @@ export async function bundle({
                             fileName: path.basename(file.path),
                         })),
                     )
-                    const types = propControlsToType({
+                    const typedocComments = propControlsToTypedocComments({
                         controls: propertyControls!,
                         fileName: name,
                         config,
                     })
-                    await fs.promises.mkdir(out, { recursive: true })
-                    await fs.promises.writeFile(
-                        path.resolve(out, `${name}.d.ts`),
-                        types,
+                    logger.log(
+                        `Generated TypeDoc comments for ${name}: ${!!typedocComments.headerComment}`,
                     )
+                    await fs.promises.mkdir(out, { recursive: true })
+                    // .d.ts generation removed – types are now injected as typedoc
+                    // comments directly inside the generated JSX file.
 
                     return {
                         propertyControls,
                         fonts,
                         name,
+                        typedocComments,
                     }
                 } finally {
                     sema.release()
@@ -459,7 +449,6 @@ export async function bundle({
                 // Ignore error if file doesn't exist or can't be deleted
             }
         })
-        // spinner.stop()
 
         const cssString =
             doNotEditComment +
@@ -487,11 +476,18 @@ export async function bundle({
             .filter(
                 (x) =>
                     x.path.endsWith('.js') &&
-                    fs.existsSync(x.path.replace(/\.js$/, '.jsx')),
+                    fs.existsSync(getFilePaths(x.path, out).jsxPath),
             )
-            .map((x) => x.path.replace(/\.js$/, '.jsx'))
+            .map((x) => getFilePaths(x.path, out).jsxPath)
         const outFiles = buildResult.outputFiles
-            .map((x) => path.resolve(out, x.path))
+            .map((x) => {
+                const paths = getFilePaths(x.path, out)
+                if (x.path.endsWith('.js') && fs.existsSync(paths.jsxPath)) {
+                    return null // Will be handled by jsx files
+                }
+                return paths.finalJsPath
+            })
+            .filter(Boolean)
             .concat([
                 path.resolve(out, 'meta.json'),
                 path.resolve(out, 'tokens.css'),
@@ -499,23 +495,10 @@ export async function bundle({
                 path.resolve(out, 'styles.css'),
             ])
             .concat(jsxFiles)
-            .concat(
-                buildResult.outputFiles.map((x) =>
-                    path.resolve(out, x.path.replace(/\.jsx?$/, '.d.ts')),
-                ),
-            )
 
         const filesToDelete = prevFiles
             .filter((x) => !outFiles.includes(x))
-            .concat(
-                buildResult.outputFiles
-                    .map((x) => x.path)
-                    .filter(
-                        (js) =>
-                            js.endsWith('.js') &&
-                            jsxFiles.some((x) => x.startsWith(js)),
-                    ),
-            )
+            .filter((x) => !x.includes(tempJsPrefix)) // Don't delete temp files here, they're handled separately
 
         for (let file of filesToDelete) {
             logger.log('deleting', path.relative(out, file))
@@ -539,17 +522,7 @@ export async function bundle({
         if (watch) {
             logger.log('waiting for components or config changes')
         }
-        if (!tokens?.length) {
-            const tokensCss =
-                "/* This css file contains your color variables, sometimes these get desynced when updated in Framer so it's good that you copy and paste this snippet into your app css */\n" +
-                '/* Bug: https://www.framer.community/c/bugs/color-style-unlinks-when-copying-component-between-projects-resulting-in-potential-value-discrepancy */\n' +
-                getTokensCss({ out, result: buildResult })
-            await fs.promises.writeFile(
-                path.resolve(out, 'tokens.css'),
-                tokensCss,
-                'utf-8',
-            )
-        }
+
         const res: BundleResult = {
             components: Object.entries(components).map(([name, v]) => {
                 const propControls = propControlsData.find(
@@ -566,6 +539,160 @@ export async function bundle({
             }),
         }
 
+        // Process and write JSX files with TypeDoc comments
+        spinner.update('Processing JSX files with TypeDoc comments')
+        for (let file of buildResult.outputFiles!) {
+            const paths = getFilePaths(file.path, out)
+
+            const componentName = path
+                .relative(out, file.path)
+                .replace(/\.js$/, '')
+            const propData = propControlsData.find(
+                (p) => p?.name === componentName,
+            )
+            const typedocComments = propData?.typedocComments
+
+            logger.log(`Processing component: ${componentName}`)
+            spinner.update(`Processing JSX for ${componentName}`)
+            if (!propData) {
+                logger.log(`  No propData found for ${componentName}`)
+            } else {
+                logger.log(
+                    `  PropData found for ${componentName}, has propertyControls: ${!!propData.propertyControls}`,
+                )
+                if (!typedocComments) {
+                    logger.log(`  No typedocComments for ${componentName}`)
+                } else {
+                    logger.log(
+                        `  TypeDoc comments available for ${componentName}`,
+                    )
+                }
+            }
+
+            const existing = await fs.promises
+                .readFile(paths.jsxPath, 'utf-8')
+                .catch(() => null)
+            const tooBigSize = 0.7 * 1024 * 1024
+
+            let formatted = file.text
+
+            let tooBig = file.text.length >= tooBigSize
+            let didFormat = false
+            if (
+                config.jsx &&
+                !tooBig &&
+                !paths.tempJsPath.includes('/chunks/') &&
+                !paths.tempJsPath.includes('\\chunks\\')
+            ) {
+                try {
+                    const plugins = [
+                        // babelPluginDeduplicateImports,
+                        babelPluginJsxTransform,
+                        removeJsxExpressionContainer,
+                    ]
+
+                    // Add TypeDoc plugin if we have comments for this component
+                    if (typedocComments) {
+                        logger.log(
+                            `  Adding TypeDoc plugin for ${componentName}`,
+                        )
+                        plugins.push(babelPluginTypedoc(typedocComments))
+                    } else {
+                        logger.log(
+                            `  No TypeDoc comments to add for ${componentName}`,
+                        )
+                    }
+
+                    let res = transform(file.text || '', {
+                        babelrc: false,
+                        sourceType: 'module',
+                        parserOpts: {
+                            plugins: ['jsx'],
+                        },
+                        plugins,
+                        // ast: true,
+                        // code: false,
+                        filename: 'x.jsx',
+                        compact: false,
+                        sourceMaps: false,
+                    })
+                    if (res?.code) {
+                        if (!biome) {
+                            biome = await Biome.create({
+                                distribution: Distribution.NODE,
+                            })
+                        }
+                        let result = biome.formatContent(res.code, {
+                            filePath: 'example.jsx',
+                        })
+                        didFormat = true
+                        formatted = result.content
+                    }
+                } catch (e) {
+                    notifyError(e, 'babel transform and format')
+                }
+            }
+
+            const prefix =
+                `// @ts-nocheck\n` + `/* eslint-disable */\n` + doNotEditComment
+            const codeJsx = prefix + formatted
+            const codeJs = prefix + file.text
+            logger.log(`writing`, path.relative(out, file.path))
+            await fs.promises.mkdir(path.dirname(paths.jsxPath), {
+                recursive: true,
+            })
+            // 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
+            if (didFormat && codeJsx !== existing) {
+                await fs.promises.writeFile(paths.jsxPath, codeJsx, 'utf-8')
+            }
+        }
+        spinner.stop()
+        // await fs.promises.writeFile(
+        //     path.resolve(out, '.cursorignore'),
+        //     `**/*.js\nchunks\n`,
+        //     'utf-8',
+        // )
+
+        // Clean up temp .js files and handle prefixes
+        for (let file of buildResult.outputFiles!) {
+            if (file.path.endsWith('.js')) {
+                const paths = getFilePaths(file.path, out)
+
+                if (fs.existsSync(paths.jsxPath)) {
+                    // Remove temp .js file if .jsx equivalent exists
+                    logger.log(
+                        'removing temp JS file with JSX equivalent:',
+                        path.relative(out, paths.tempJsPath),
+                    )
+                    try {
+                        await fs.promises.rm(paths.tempJsPath)
+                        await fs.promises.rm(paths.finalJsPath)
+                    } catch (error) {
+                        // Ignore error if file doesn't exist
+                    }
+                } else {
+                    // Rename temp .js file to final name if no .jsx equivalent
+                    logger.log(
+                        'renaming temp JS file to final name:',
+                        path.relative(out, paths.tempJsPath),
+                        '->',
+                        path.relative(out, paths.finalJsPath),
+                    )
+                    try {
+                        await fs.promises.rename(
+                            paths.tempJsPath,
+                            paths.finalJsPath,
+                        )
+                    } catch (error) {
+                        // Ignore error if file doesn't exist
+                    }
+                }
+            }
+        }
+
         spinner.info(`Build completed`)
         return res
     }
@@ -594,8 +721,11 @@ export async function bundle({
     console.log()
     console.log()
     const outDirForExample =
-        path.posix.relative(process.cwd(), out).replace(/^src\//, '') ||
-        'framer' // remove src so file works inside src
+        path
+            .relative(process.cwd(), out)
+            .split(path.sep)
+            .join('/')
+            .replace(/^src\//, '') || 'framer' // remove src so file works inside src
     const { exampleCode } = await createExampleComponentCode({
         outDir: out,
         // buildResult: result,
@@ -608,42 +738,35 @@ export async function bundle({
         })
         await fs.promises.writeFile(stackblitzDemoExample, exampleCode)
     }
-    if (!foundError) {
-        console.log(
-            terminalMarkdown(dedent`
-        # How to use the Framer components
-
-        Your components are exported to \`${outDirForExample}\` folder. Now please install the \`unframer\` runtime dependency:
+    console.log(
+        terminalMarkdown(dedent`
+    # How to use the Framer components
 
-        \`\`\`sh
-        npm install unframer
-        \`\`\`
+    Your components are exported to \`${outDirForExample}\` folder.
 
-        Each component has a \`.Responsive\` variant that allows you to specify different variants for different breakpoints.
+    Each component has a \`.Responsive\` variant that allows you to specify different variants for different breakpoints.
 
-        You can use the components like this (try copy pasting the code below into your React app):
+    You can use the components like this (try copy pasting the code below into your React app):
 
-        \`\`\`jsx
-        ${exampleCode}
-        \`\`\`
+    \`\`\`jsx
+    ${exampleCode}
+    \`\`\`
 
-        It's very important to import the \`styles.css\` file to include the necessary styles for the components.
+    It's very important to import the \`styles.css\` file to include the necessary styles for the components.
 
-        To style components you can pass a \`style\` or \`className\` prop (but remember to use !important to increase the specificity).
+    To style components you can pass a \`style\` or \`className\` prop (but remember to use !important to increase the specificity).
 
-        Read more on GitHub: https://github.com/remorses/unframer
+    Read more on GitHub: https://github.com/remorses/unframer
 
-        `),
-        )
-    }
-    await checkUnframerVersion({ cwd: out })
+    `),
+    )
     console.log()
     return { result, rebuild, buildContext }
 }
 
 const packageVersionCache = new Map<string, string>()
 
-export function resolvePackage({ cwd, pkg }) {
+export function resolvePackageVersion({ cwd, pkg }) {
     if (packageVersionCache.has(pkg)) {
         return Promise.resolve(packageVersionCache.get(pkg))
     }
@@ -664,10 +787,8 @@ export function resolvePackage({ cwd, pkg }) {
             },
             (error, stdout, stderr) => {
                 if (error) {
-                    logger.log(stderr)
-                    reject(
-                        new Error(`${pkg} is not installed in your project`),
-                    )
+                    // Package not installed - this is expected and handled by auto-install
+                    reject(new Error(`${pkg} is not installed in your project`))
                     return
                 }
                 const version = stdout.trim()
@@ -678,20 +799,31 @@ export function resolvePackage({ cwd, pkg }) {
     })
 }
 
-export async function checkUnframerVersion({ cwd }: { cwd: string }) {
-    const currentVersion = packageJson.version
-    try {
-        const installedVersion = await resolvePackage({ cwd, pkg: 'unframer' })
-        if (installedVersion !== currentVersion) {
-            spinner.error(
-                `IMPORTANT: Unframer version mismatch. Please run: npm update unframer@latest`,
-            )
-        }
-    } catch (e) {
-        spinner.error(
-            'IMPORTANT: Unframer is not installed in your project. Please run: npm install unframer',
+export function resolvePackage({ cwd, pkg }) {
+    return new Promise<boolean>((resolve) => {
+        const code = `import('${pkg}/package.json', { with: { type: 'json' } }).then(()=>console.log('true')).catch(()=>import('${pkg}').then(()=>console.log('true')).catch(()=>console.log('false')));`
+
+        const command = [
+            JSON.stringify(nodePath),
+            '-e',
+            JSON.stringify(code),
+        ].join(' ')
+
+        exec(
+            command,
+            {
+                cwd,
+            },
+            (error, stdout) => {
+                if (error) {
+                    resolve(false)
+                    return
+                }
+                const exists = stdout.trim().split('\n').pop() === 'true'
+                resolve(exists)
+            },
         )
-    }
+    })
 }
 
 export function getDarkModeSelector(opts: {
@@ -820,7 +952,7 @@ async function extractPropControlsSafe(text, name) {
     }
 }
 
-function getTokensCss({
+async function getTokensCss({
     out,
     result,
 }: {
@@ -1007,14 +1139,18 @@ function safeJsonParse(text) {
     }
 }
 
-export function propControlsToType({
+/**
+ * Generates TypeDoc comments that will be injected into JSX files
+ * instead of generating separate .d.ts files
+ */
+export function propControlsToTypedocComments({
     config,
     fileName,
     controls,
 }: {
     controls: PropertyControls
-    fileName
-    config
+    fileName: string
+    config: Config
 }) {
     try {
         const types = Object.entries(controls || ({} as PropertyControls))
@@ -1074,46 +1210,86 @@ export function propControlsToType({
                 if (!name) {
                     return ''
                 }
-                return `    ${JSON.stringify(name)}?: ${typescriptType(value)}`
+                return ` * ${name}?: ${typescriptType(value)} // ${value.title || name}`
             })
             .filter(Boolean)
             .join('\n')
 
         const componentName = componentCamelCase(fileName)
 
-        const defaultPropsTypes =
-            [
-                'children?: React.ReactNode',
-                'locale?: Locale',
-                'style?: React.CSSProperties',
-                'className?: string',
-                'id?: string',
-                'width?: any',
-                'height?: any',
-                'layoutId?: string',
-            ]
-                .map((line) => `    ${line}`)
-                .join('\n') + '\n'
-        let t = ''
-        t += '/* This file was generated by Unframer, do not edit manually */\n'
-
-        t += 'import * as React from "react"\n\n'
-        t += 'import { UnframerBreakpoint } from "unframer"\n\n'
-        t += `type Locale = ${
-            config.locales?.length
-                ? config.locales.map((l) => `'${l.code}'`).join(' | ')
-                : 'string'
-        }\n`
-        t += `export interface Props {\n${defaultPropsTypes}${types}\n}\n\n`
-        t += `const ${componentName} = (props: Props) => any\n\n`
-        t += `type VariantsMap = Partial<Record<UnframerBreakpoint, Props['variant']>> & { base: Props['variant'] }\n\n`
-        t += `${componentName}.Responsive = (props: Omit<Props, 'variant'> & {variants?: VariantsMap}) => any\n\n`
-        t += `export default ${componentName}\n\n`
-
-        return t
+        const defaultPropsJsDoc = [
+            ' * children?: React.ReactNode',
+            ' * locale?: Locale',
+            ' * style?: React.CSSProperties',
+            ' * className?: string',
+            ' * id?: string',
+            ' * ref?: any',
+            ' * width?: any',
+            ' * height?: any',
+            ' * layoutId?: string',
+        ].join('\n')
+
+        // Generate header comment with type definitions
+        let headerComment = '/**\n'
+        headerComment += ' * @typedef Locale\n'
+
+        // Generate union type from config.locales if available
+        const localeType = (() => {
+            if (
+                config?.locales &&
+                Array.isArray(config.locales) &&
+                config.locales.length > 0
+            ) {
+                return config.locales
+                    .map((locale) => `'${locale.slug}'`)
+                    .join(' | ')
+            }
+            return 'string'
+        })()
+
+        headerComment += ` * ${localeType}\n`
+        headerComment += ' */\n\n'
+        headerComment += '/**\n'
+        headerComment +=
+            ' * @typedef {{\n'
+        headerComment += defaultPropsJsDoc
+
+        if (types) {
+            headerComment += '\n' + types
+        }
+        headerComment += `\n}} Props\n`
+        headerComment += '\n */\n\n'
+        headerComment += '/**\n'
+        headerComment += ' * @type {import("unframer").UnframerBreakpoint}\n'
+        headerComment += ' * Represents a responsive breakpoint for unframer.\n'
+        headerComment += ' */\n\n'
+        headerComment += '/**\n'
+        headerComment += ' * @typedef VariantsMap\n'
+        headerComment +=
+            " * Partial record of UnframerBreakpoint to Props.variant, with a mandatory 'base' key.\n"
+        headerComment +=
+            " * { [key in UnframerBreakpoint]?: Props['variant'] } & { base: Props['variant'] }\n"
+        headerComment += ' */'
+
+        // Generate responsive comment
+        const responsiveComment = `/**\n * Renders ${componentName} for all breakpoints with a variants map. Variant prop is inferred per breakpoint.\n * @function\n * @param {Omit<Props, 'variant'> & {variants?: VariantsMap}} props\n * @returns {any}\n */`
+
+        // Generate default export comment - use inline function type instead of referencing undefined type
+        const defaultExportComment = `/** @type {function(Props): any} */`
+
+        return {
+            headerComment,
+            responsiveComment,
+            defaultExportComment,
+        }
     } catch (e: any) {
-        logger.error('cannot generate types', e.stack)
-        return ''
+        logger.error(e.message)
+        logger.error('cannot generate typedoc comments', e.stack)
+        return {
+            headerComment: '',
+            responsiveComment: '',
+            defaultExportComment: '',
+        }
     }
 }
 
@@ -1322,7 +1498,7 @@ async function recursiveReaddir(dir: string): Promise<string[]> {
     return files.flat()
 }
 
-function indentWithTabs(str: string, tabs: string) {
+export function indentWithTabs(str: string, tabs: string) {
     if (!str) return ''
     return str
         .split('\n')
@@ -1337,8 +1513,10 @@ export async function createExampleComponentCode({
     outDir: string
     config: Config
 }) {
-    const outDirForExample = path.posix
+    const outDirForExample = path
         .relative(process.cwd(), outDir)
+        .split(path.sep)
+        .join('/')
         .replace(/^src\//, '') // remove src so file works inside src
     const instances = config?.componentInstancesInIndexPage?.sort((a, b) => {
         // Order first by nodeDepth (lower is better)
@@ -1391,6 +1569,7 @@ export async function createExampleComponentCode({
       };
       `
     return {
+        outDirForExample,
         exampleCode,
     }
 }
@@ -1404,3 +1583,35 @@ type BundleResult = {
         propertyControls?: PropertyControls
     }>
 }
+
+/**
+ * Compares two semantic version strings.
+ * Returns true if versionB is greater than versionA.
+ * Handles x.y.z, x.y, x, and optional pre-release (-alpha, etc).
+ */
+export function isVersionGreater(versionA: string, versionB: string): boolean {
+    try {
+        function parseVersion(version: string) {
+            // Remove pre-release (e.g. -alpha.1)
+            let [core] = version.trim().split('-')
+            return core.split('.').map((x) => parseInt(x, 10))
+        }
+        const [a1 = 0, a2 = 0, a3 = 0] = parseVersion(versionA)
+        const [b1 = 0, b2 = 0, b3 = 0] = parseVersion(versionB)
+
+        if (b1 > a1) return true
+        if (b1 < a1) return false
+        if (b2 > a2) return true
+        if (b2 < a2) return false
+        if (b3 > a3) return true
+        if (b3 < a3) return false
+
+        // If all equal, not greater
+        return false
+    } catch (error) {
+        spinner.error(
+            `Error comparing versions "${versionA}" and "${versionB}": ${error?.stack || error?.message || error}`,
+        )
+        return true
+    }
+}