unframer 2.27.2 → 3.0.0

package/esm/exporter.js

@@ -1,5 +1,4 @@
 import { build, context } from 'esbuild';
-import packageJson from '../package.json';
 import url from 'url';
 import { Sema } from 'async-sema';
 import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
@@ -10,12 +9,15 @@ import fs from 'fs';
 import path from 'path';
 import { dedent } from './utils.js';
 import { babelPluginJsxTransform, removeJsxExpressionContainer, } from './babel-jsx.js';
+import { babelPluginTypedoc } from './babel-typedoc.js';
 import { propCamelCaseJustLikeFramer } from './compat.js';
 import { breakpointsStyles, defaultBreakpointSizes, getFontsStyles, groupBy, logFontsUsage, } from './css.js';
 import { defaultExternalPackages, esbuildPluginBundleDependencies, resolveRedirect, } from './esbuild';
 import { ControlType, combinedCSSRules, } from './framer.js';
 import { notifyError } from './sentry';
 import { kebabCase, logger, spinner, 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';
 let biome;
 export async function bundle({ config, cwd: out = '', watch = false, signal = undefined, }) {
@@ -26,6 +28,24 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
         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, outDir) {
+        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((config.framerWebPages || []).map((page) => [
         page.webPageId,
@@ -42,7 +62,7 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
         };
     }
     const fn = watch ? context : fakeContext;
-    let foundError = false;
+    const missingPackages = new Set();
     const buildContext = await fn({
         absWorkingDir: out,
         entryPoints: Object.keys(components)
@@ -71,9 +91,12 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                 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({}),
@@ -88,6 +111,13 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                     });
                     build.onLoad({ 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((x) => x.componentName === name) || [];
                         const brk = breakpointSizes
@@ -109,6 +139,8 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                                 ...brk.slice(1),
                             ])
                             : {};
+                        // Use virtual routes module
+                        const routesImportPath = 'virtual:__routes';
                         return {
                             contents: /** js **/ `
                                 'use client'
@@ -119,30 +151,31 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                                 signal,
                             })}'
                                 import { WithFramerBreakpoints } from 'unframer'
+                                import { routes } from '${routesImportPath}'
                                 const locales = ${JSON.stringify(config.locales) || '[]'}
                                 const defaultResponsiveVariants = ${JSON.stringify(responsiveVariants, null, 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)}}
                                             locale={locale}
                                             locales={locales}
                                         />
                                     )
                                 }
-
-                                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)}}
                                             locale={locale}
                                             locales={locales}
@@ -150,6 +183,7 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                                     )
                                 }
                                 Object.assign(ComponentWithRoot, Component)
+                                export default ComponentWithRoot
                                 `,
                             loader: 'jsx',
                         };
@@ -162,10 +196,27 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
     });
     const doNotEditComment = `/* This file was generated by Unframer for Framer project ${config.projectId || ''} "${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.`);
                 spinner.error(`Use --external to make all npm packagess external, then install the right version`);
                 process.exit(1);
@@ -173,105 +224,31 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
             throw e;
         });
         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;
-            let formatted = file.text;
-            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');
-                }
+        // Install missing packages if any were collected
+        if (missingPackages.size > 0) {
+            const packagesToInstall = Array.from(missingPackages);
+            logger.log(`Installing missing packages: ${packagesToInstall.join(', ')}`);
+            const installResult = await installPackagesBatch({
+                packageNames: packagesToInstall,
+                cwd: out,
+                isDev: false,
+            });
+            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');
         }
@@ -287,7 +264,8 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                 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;
                 }
@@ -296,6 +274,7 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                     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);
                 if (!propertyControls) {
@@ -305,17 +284,20 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                     ...x,
                     fileName: path.basename(file.path),
                 })));
-                const types = propControlsToType({
+                const typedocComments = propControlsToTypedocComments({
                     controls: propertyControls,
                     fileName: name,
                     config,
                 });
+                logger.log(`Generated TypeDoc comments for ${name}: ${!!typedocComments.headerComment}`);
                 await fs.promises.mkdir(out, { recursive: true });
-                await fs.promises.writeFile(path.resolve(out, `${name}.d.ts`), types);
+                // .d.ts generation removed – types are now injected as typedoc
+                // comments directly inside the generated JSX file.
                 return {
                     propertyControls,
                     fonts,
                     name,
+                    typedocComments,
                 };
             }
             finally {
@@ -329,7 +311,6 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                 // Ignore error if file doesn't exist or can't be deleted
             }
         });
-        // spinner.stop()
         const cssString = doNotEditComment +
             '/* This css file has all the necessary styles to run all your components */\n' +
             '\n' +
@@ -347,24 +328,27 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
             .forEach((x) => logger.log(x));
         const jsxFiles = buildResult.outputFiles
             .filter((x) => x.path.endsWith('.js') &&
-            fs.existsSync(x.path.replace(/\.js$/, '.jsx')))
-            .map((x) => x.path.replace(/\.js$/, '.jsx'));
+            fs.existsSync(getFilePaths(x.path, out).jsxPath))
+            .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'),
             path.resolve(out, '.cursorignore'),
             path.resolve(out, 'styles.css'),
         ])
-            .concat(jsxFiles)
-            .concat(buildResult.outputFiles.map((x) => path.resolve(out, x.path.replace(/\.jsx?$/, '.d.ts'))));
+            .concat(jsxFiles);
         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));
             try {
@@ -381,12 +365,6 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
         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 = {
             components: Object.entries(components).map(([name, v]) => {
                 const propControls = propControlsData.find((x) => x?.name === name);
@@ -399,6 +377,131 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
                 };
             }),
         };
+        // 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;
     }
@@ -424,8 +527,11 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
     const result = await rebuild();
     console.log();
     console.log();
-    const outDirForExample = path.posix.relative(process.cwd(), out).replace(/^src\//, '') ||
-        'framer'; // remove src so file works inside src
+    const outDirForExample = 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,
@@ -438,38 +544,31 @@ export async function bundle({ config, cwd: out = '', watch = false, signal = un
         });
         await fs.promises.writeFile(stackblitzDemoExample, exampleCode);
     }
-    if (!foundError) {
-        console.log(terminalMarkdown(dedent `
-        # How to use the Framer components
+    console.log(terminalMarkdown(dedent `
+    # How to use the Framer components
 
-        Your components are exported to \`${outDirForExample}\` folder. Now please install the \`unframer\` runtime dependency:
+    Your components are exported to \`${outDirForExample}\` folder.
 
-        \`\`\`sh
-        npm install unframer
-        \`\`\`
+    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();
-export function resolvePackage({ cwd, pkg }) {
+export function resolvePackageVersion({ cwd, pkg }) {
     if (packageVersionCache.has(pkg)) {
         return Promise.resolve(packageVersionCache.get(pkg));
     }
@@ -484,7 +583,7 @@ export function resolvePackage({ cwd, pkg }) {
             cwd,
         }, (error, stdout, stderr) => {
             if (error) {
-                logger.log(stderr);
+                // Package not installed - this is expected and handled by auto-install
                 reject(new Error(`${pkg} is not installed in your project`));
                 return;
             }
@@ -494,17 +593,25 @@ export function resolvePackage({ cwd, pkg }) {
         });
     });
 }
-export async function checkUnframerVersion({ cwd }) {
-    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((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) {
     const { darkModeType = 'class', content } = opts;
@@ -598,7 +705,7 @@ async function extractPropControlsSafe(text, name) {
         logger.error(`Cannot get property controls for ${name}`, e.stack);
     }
 }
-function getTokensCss({ out, result, }) {
+async function getTokensCss({ out, result, }) {
     const allTokens = [];
     for (let file of result.outputFiles) {
         const code = fs.readFileSync(path.resolve(out, file.path), 'utf-8');
@@ -728,7 +835,11 @@ function safeJsonParse(text) {
         return null;
     }
 }
-export function propControlsToType({ config, fileName, controls, }) {
+/**
+ * Generates TypeDoc comments that will be injected into JSX files
+ * instead of generating separate .d.ts files
+ */
+export function propControlsToTypedocComments({ config, fileName, controls, }) {
     try {
         const types = Object.entries(controls || {})
             .map(([key, value]) => {
@@ -786,40 +897,76 @@ export function propControlsToType({ config, fileName, controls, }) {
             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) {
-        logger.error('cannot generate types', e.stack);
-        return '';
+        logger.error(e.message);
+        logger.error('cannot generate typedoc comments', e.stack);
+        return {
+            headerComment: '',
+            responsiveComment: '',
+            defaultExportComment: '',
+        };
     }
 }
 export function parsePropertyControls(code) {
@@ -995,7 +1142,7 @@ async function recursiveReaddir(dir) {
     }));
     return files.flat();
 }
-function indentWithTabs(str, tabs) {
+export function indentWithTabs(str, tabs) {
     if (!str)
         return '';
     return str
@@ -1004,8 +1151,10 @@ function indentWithTabs(str, tabs) {
         .join('\n');
 }
 export async function createExampleComponentCode({ outDir, 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)
@@ -1051,7 +1200,42 @@ export async function createExampleComponentCode({ outDir, config, }) {
       };
       `;
     return {
+        outDirForExample,
         exampleCode,
     };
 }
+/**
+ * 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, versionB) {
+    try {
+        function parseVersion(version) {
+            // 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;
+    }
+}
 //# sourceMappingURL=exporter.js.map