@openwebf/webf 0.22.13 → 0.23.2

package/dist/generator.js

@@ -29,6 +29,7 @@ const dart_1 = require("./dart");
 const react_1 = require("./react");
 const vue_1 = require("./vue");
 const logger_1 = require("./logger");
+const typescript_1 = __importDefault(require("typescript"));
 // Cache for file content to avoid redundant reads
 const fileContentCache = new Map();
 // Cache for generated content to detect changes
@@ -186,12 +187,17 @@ function dartGen(_a) {
                 if (!fs_1.default.existsSync(outputDir)) {
                     fs_1.default.mkdirSync(outputDir, { recursive: true });
                 }
-                // Generate Dart file
+                // Generate Dart file (skip if empty)
                 const genFilePath = path_1.default.join(outputDir, lodash_1.default.snakeCase(blob.filename));
                 const fullPath = genFilePath + '_bindings_generated.dart';
-                if (writeFileIfChanged(fullPath, result)) {
-                    filesChanged++;
-                    (0, logger_1.debug)(`Generated: ${path_1.default.basename(fullPath)}`);
+                if (result && result.trim().length > 0) {
+                    if (writeFileIfChanged(fullPath, result)) {
+                        filesChanged++;
+                        (0, logger_1.debug)(`Generated: ${path_1.default.basename(fullPath)}`);
+                    }
+                }
+                else {
+                    (0, logger_1.debug)(`Skipped ${path_1.default.basename(fullPath)} - empty bindings`);
                 }
                 // Copy the original .d.ts file to the output directory
                 const dtsOutputPath = path_1.default.join(outputDir, blob.filename + '.d.ts');
@@ -204,13 +210,8 @@ function dartGen(_a) {
                 (0, logger_1.error)(`Error generating Dart code for ${blob.filename}`, err);
             }
         }));
-        // Generate index.d.ts file with references to all .d.ts files
-        const indexDtsContent = generateTypeScriptIndex(blobs, normalizedTarget);
-        const indexDtsPath = path_1.default.join(normalizedTarget, 'index.d.ts');
-        if (writeFileIfChanged(indexDtsPath, indexDtsContent)) {
-            filesChanged++;
-            (0, logger_1.debug)('Generated: index.d.ts');
-        }
+        // Note: We no longer generate a root index.d.ts for Dart codegen
+        // as it is not necessary for the codegen workflow.
         (0, logger_1.timeEnd)('dartGen');
         (0, logger_1.success)(`Dart code generation completed. ${filesChanged} files changed.`);
         (0, logger_1.info)(`Output directory: ${normalizedTarget}`);
@@ -287,38 +288,155 @@ function reactGen(_a) {
                 (0, logger_1.error)(`Error generating React component for ${blob.filename}`, err);
             }
         }));
-        // Generate index file
-        // Avoid overriding a user-managed index.ts. Only write when:
-        // - index.ts does not exist, or
-        // - it contains the auto-generated marker from our template
+        // Generate/merge index file
         const indexFilePath = path_1.default.join(normalizedTarget, 'src', 'index.ts');
+        // Always build the full index content string for downstream tooling/logging
         const newExports = (0, react_1.generateReactIndex)(blobs);
-        let shouldWriteIndex = true;
-        if (fs_1.default.existsSync(indexFilePath)) {
+        // Build desired export map: moduleSpecifier -> Set of names
+        const desiredExports = new Map();
+        const components = blobs.flatMap(blob => {
+            const classObjects = blob.objects.filter(obj => obj instanceof declaration_1.ClassObject);
+            const properties = classObjects.filter(object => object.name.endsWith('Properties'));
+            const events = classObjects.filter(object => object.name.endsWith('Events'));
+            const componentMap = new Map();
+            properties.forEach(prop => componentMap.set(prop.name.replace(/Properties$/, ''), true));
+            events.forEach(evt => componentMap.set(evt.name.replace(/Events$/, ''), true));
+            return Array.from(componentMap.keys()).map(className => ({
+                className,
+                fileName: blob.filename,
+                relativeDir: blob.relativeDir,
+            }));
+        });
+        // Deduplicate by className
+        const unique = new Map();
+        for (const c of components) {
+            if (!unique.has(c.className))
+                unique.set(c.className, c);
+        }
+        for (const { className, fileName, relativeDir } of unique.values()) {
+            const spec = `./${relativeDir ? `${relativeDir}/` : ''}${fileName}`;
+            if (!desiredExports.has(spec))
+                desiredExports.set(spec, new Set());
+            const set = desiredExports.get(spec);
+            set.add(className);
+            set.add(`${className}Element`);
+        }
+        if (!fs_1.default.existsSync(indexFilePath)) {
+            // No index.ts -> generate fresh file from template
+            if (writeFileIfChanged(indexFilePath, newExports)) {
+                filesChanged++;
+                (0, logger_1.debug)(`Generated: index.ts`);
+            }
+        }
+        else {
+            // Merge into existing index.ts without removing user code
             try {
                 const existing = fs_1.default.readFileSync(indexFilePath, 'utf-8');
-                const isAutoGenerated = existing.includes('Generated by TSDL');
-                if (!isAutoGenerated) {
-                    shouldWriteIndex = false;
-                    (0, logger_1.warn)(`Found existing user-managed index.ts at ${indexFilePath}; skipping overwrite.`);
+                const sourceFile = typescript_1.default.createSourceFile(indexFilePath, existing, typescript_1.default.ScriptTarget.ES2020, true, typescript_1.default.ScriptKind.TS);
+                // Track which names already exported per module
+                for (const stmt of sourceFile.statements) {
+                    if (typescript_1.default.isExportDeclaration(stmt) && stmt.exportClause && typescript_1.default.isNamedExports(stmt.exportClause)) {
+                        const moduleSpecifier = stmt.moduleSpecifier && typescript_1.default.isStringLiteral(stmt.moduleSpecifier)
+                            ? stmt.moduleSpecifier.text
+                            : undefined;
+                        if (!moduleSpecifier)
+                            continue;
+                        const desired = desiredExports.get(moduleSpecifier);
+                        if (!desired)
+                            continue;
+                        for (const el of stmt.exportClause.elements) {
+                            const name = el.name.getText(sourceFile);
+                            if (desired.has(name))
+                                desired.delete(name);
+                        }
+                    }
+                }
+                // Prepare new export lines for any remaining names
+                const lines = [];
+                for (const [spec, names] of desiredExports) {
+                    const missing = Array.from(names);
+                    if (missing.length === 0)
+                        continue;
+                    const specEscaped = spec.replace(/\\/g, '/');
+                    lines.push(`export { ${missing.join(', ')} } from "${specEscaped}";`);
+                }
+                if (lines.length > 0) {
+                    const appended = (existing.endsWith('\n') ? '' : '\n') + lines.join('\n') + '\n';
+                    if (writeFileIfChanged(indexFilePath, existing + appended)) {
+                        filesChanged++;
+                        (0, logger_1.debug)(`Merged exports into existing index.ts`);
+                    }
+                }
+                else {
+                    (0, logger_1.debug)(`index.ts is up to date; no merge needed.`);
                 }
             }
             catch (err) {
-                // If we cannot read the file for some reason, be conservative and skip overwriting
-                shouldWriteIndex = false;
-                (0, logger_1.warn)(`Unable to read existing index.ts; skipping overwrite: ${indexFilePath}`);
-            }
-        }
-        if (shouldWriteIndex) {
-            if (writeFileIfChanged(indexFilePath, newExports)) {
-                filesChanged++;
-                (0, logger_1.debug)(`Generated: index.ts`);
+                (0, logger_1.warn)(`Failed to merge into existing index.ts. Skipping modifications: ${indexFilePath}`);
             }
         }
         (0, logger_1.timeEnd)('reactGen');
         (0, logger_1.success)(`React code generation completed. ${filesChanged} files changed.`);
         (0, logger_1.info)(`Output directory: ${normalizedTarget}`);
         (0, logger_1.info)('You can now import these components in your React project.');
+        // Aggregate standalone type declarations (consts/enums/type aliases) into a single types.d.ts
+        try {
+            const consts = blobs.flatMap(b => b.objects.filter(o => o instanceof declaration_1.ConstObject));
+            const enums = blobs.flatMap(b => b.objects.filter(o => o instanceof declaration_1.EnumObject));
+            const typeAliases = blobs.flatMap(b => b.objects.filter(o => o instanceof declaration_1.TypeAliasObject));
+            // Deduplicate by name
+            const constMap = new Map();
+            consts.forEach(c => { if (!constMap.has(c.name))
+                constMap.set(c.name, c); });
+            const typeAliasMap = new Map();
+            typeAliases.forEach(t => { if (!typeAliasMap.has(t.name))
+                typeAliasMap.set(t.name, t); });
+            const hasAny = constMap.size > 0 || enums.length > 0 || typeAliasMap.size > 0;
+            if (hasAny) {
+                const constDecl = Array.from(constMap.values())
+                    .map(c => `export declare const ${c.name}: ${c.type};`)
+                    .join('\n');
+                const enumDecl = enums
+                    .map(e => `export declare enum ${e.name} { ${e.members.map(m => m.initializer ? `${m.name} = ${m.initializer}` : `${m.name}`).join(', ')} }`)
+                    .join('\n');
+                const typeAliasDecl = Array.from(typeAliasMap.values())
+                    .map(t => `export type ${t.name} = ${t.type};`)
+                    .join('\n');
+                const typesContent = [
+                    '/* Generated by WebF CLI - aggregated type declarations */',
+                    typeAliasDecl,
+                    constDecl,
+                    enumDecl,
+                    ''
+                ].filter(Boolean).join('\n');
+                const typesPath = path_1.default.join(normalizedTarget, 'src', 'types.d.ts');
+                if (writeFileIfChanged(typesPath, typesContent)) {
+                    filesChanged++;
+                    (0, logger_1.debug)(`Generated: src/types.d.ts`);
+                }
+                // Try to help TypeScript pick up additional declarations by adding a reference comment.
+                // This avoids bundler resolution errors from importing a .d.ts file.
+                const indexFilePath = path_1.default.join(normalizedTarget, 'src', 'index.ts');
+                try {
+                    if (fs_1.default.existsSync(indexFilePath)) {
+                        let current = fs_1.default.readFileSync(indexFilePath, 'utf-8');
+                        const refLine = `/// <reference path="./types.d.ts" />`;
+                        if (!current.includes(refLine)) {
+                            // Place the reference at the very top, before any code
+                            const updated = `${refLine}\n${current}`;
+                            if (writeFileIfChanged(indexFilePath, updated)) {
+                                filesChanged++;
+                                (0, logger_1.debug)(`Updated: src/index.ts with reference to types.d.ts`);
+                            }
+                        }
+                    }
+                }
+                catch (_b) { }
+            }
+        }
+        catch (e) {
+            (0, logger_1.warn)('Failed to generate aggregated React types.d.ts');
+        }
     });
 }
 function vueGen(_a) {

package/dist/react.js

@@ -121,6 +121,8 @@ function toWebFTagName(className) {
 function generateReactComponent(blob, packageName, relativeDir) {
     const classObjects = blob.objects.filter(obj => obj instanceof declaration_1.ClassObject);
     const typeAliases = blob.objects.filter(obj => obj instanceof declaration_1.TypeAliasObject);
+    const constObjects = blob.objects.filter(obj => obj instanceof declaration_1.ConstObject);
+    const enumObjects = blob.objects.filter(obj => obj instanceof declaration_1.EnumObject);
     const classObjectDictionary = Object.fromEntries(classObjects.map(object => {
         return [object.name, object];
     }));
@@ -142,8 +144,17 @@ function generateReactComponent(blob, packageName, relativeDir) {
     const typeAliasDeclarations = typeAliases.map(typeAlias => {
         return `type ${typeAlias.name} = ${typeAlias.type};`;
     }).join('\n');
+    // Include declare const values as ambient exports for type usage (e.g., unique symbol branding)
+    const constDeclarations = constObjects.map(c => `export declare const ${c.name}: ${c.type};`).join('\n');
+    // Include enums
+    const enumDeclarations = enumObjects.map(e => {
+        const members = e.members.map(m => m.initializer ? `${m.name} = ${m.initializer}` : `${m.name}`).join(', ');
+        return `export declare enum ${e.name} { ${members} }`;
+    }).join('\n');
     const dependencies = [
         typeAliasDeclarations,
+        constDeclarations,
+        enumDeclarations,
         // Include Methods interfaces as dependencies
         methods.map(object => {
             const methodDeclarations = object.methods.map(method => {

package/dist/vue.js

@@ -131,6 +131,17 @@ interface ${object.name} {
     }).join('\n');
     return result;
 }
+function toVueTagName(className) {
+    if (className.startsWith('WebF')) {
+        const withoutPrefix = className.substring(4);
+        return 'web-f-' + lodash_1.default.kebabCase(withoutPrefix);
+    }
+    else if (className.startsWith('Flutter')) {
+        const withoutPrefix = className.substring(7);
+        return 'flutter-' + lodash_1.default.kebabCase(withoutPrefix);
+    }
+    return lodash_1.default.kebabCase(className);
+}
 function generateVueTypings(blobs) {
     const componentNames = blobs.map(blob => {
         const classObjects = blob.objects;
@@ -160,13 +171,42 @@ function generateVueTypings(blobs) {
     }).filter(component => {
         return component.length > 0;
     }).join('\n\n');
+    // Collect declare consts across blobs and render as exported ambient declarations
+    const consts = blobs
+        .flatMap(blob => blob.objects)
+        .filter(obj => obj instanceof declaration_1.ConstObject);
+    // Deduplicate by name keeping first occurrence
+    const uniqueConsts = new Map();
+    consts.forEach(c => {
+        if (!uniqueConsts.has(c.name))
+            uniqueConsts.set(c.name, c);
+    });
+    const constDeclarations = Array.from(uniqueConsts.values())
+        .map(c => `export declare const ${c.name}: ${c.type};`)
+        .join('\n');
+    // Collect declare enums across blobs
+    const enums = blobs
+        .flatMap(blob => blob.objects)
+        .filter(obj => obj instanceof declaration_1.EnumObject);
+    const enumDeclarations = enums.map(e => {
+        const members = e.members.map(m => m.initializer ? `${m.name} = ${m.initializer}` : `${m.name}`).join(', ');
+        return `export declare enum ${e.name} { ${members} }`;
+    }).join('\n');
+    // Build mapping of template tag names to class names for GlobalComponents
+    const componentMetas = componentNames.map(className => ({
+        className,
+        tagName: toVueTagName(className),
+    }));
     const content = lodash_1.default.template(readTemplate('vue.components.d.ts'), {
         interpolate: /<%=([\s\S]+?)%>/g,
         evaluate: /<%([\s\S]+?)%>/g,
         escape: /<%-([\s\S]+?)%>/g
     })({
         componentNames,
+        componentMetas,
         components,
+        consts: constDeclarations,
+        enums: enumDeclarations,
     });
     return content.split('\n').filter(str => {
         return str.trim().length > 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwebf/webf",
-  "version": "0.22.13",
+  "version": "0.23.2",
   "description": "Command line tools for WebF",
   "main": "index.js",
   "bin": {
@@ -30,6 +30,7 @@
     "@types/inquirer": "^8.2.11",
     "@types/jest": "^29.5.12",
     "@types/lodash": "^4.17.17",
+    "@types/minimatch": "^5.1.2",
     "@types/node": "^22.15.21",
     "@types/yaml": "^1.9.6",
     "jest": "^29.7.0",
@@ -39,7 +40,7 @@
     "@microsoft/tsdoc": "^0.15.1",
     "@microsoft/tsdoc-config": "^0.17.1",
     "commander": "^14.0.0",
-    "glob": "^10.3.10",
+    "glob": "^10.4.5",
     "inquirer": "^8.2.6",
     "lodash": "^4.17.21",
     "typescript": "^5.8.3",

package/src/IDLBlob.ts

@@ -1,4 +1,4 @@
-import {ClassObject, FunctionObject, TypeAliasObject} from "./declaration";
+import {ClassObject, FunctionObject, TypeAliasObject, EnumObject} from "./declaration";
 
 export class IDLBlob {
   raw: string = '';
@@ -7,7 +7,7 @@ export class IDLBlob {
   filename: string;
   implement: string;
   relativeDir: string = '';
-  objects: (ClassObject | FunctionObject | TypeAliasObject)[] = [];
+  objects: (ClassObject | FunctionObject | TypeAliasObject | EnumObject)[] = [];
 
   constructor(source: string, dist: string, filename: string, implement: string, relativeDir: string = '') {
     this.source = source;

package/src/analyzer.ts

@@ -8,6 +8,9 @@ import {
   FunctionArgumentType,
   FunctionDeclaration,
   FunctionObject,
+  ConstObject,
+  EnumObject,
+  EnumMemberObject,
   IndexedPropertyDeclaration,
   ParameterMode,
   PropsDeclaration,
@@ -25,8 +28,8 @@ export interface UnionTypeCollector {
   types: Set<ParameterType[]>;
 }
 
-// Cache for parsed source files to avoid re-parsing
-const sourceFileCache = new Map<string, { content: string; sourceFile: ts.SourceFile }>();
+// Cache for parsed source files to avoid re-parsing (cache by path only)
+const sourceFileCache = new Map<string, ts.SourceFile>();
 
 // Cache for type conversions to avoid redundant processing
 const typeConversionCache = new Map<string, ParameterType>();
@@ -59,14 +62,12 @@ export function analyzer(blob: IDLBlob, definedPropertyCollector: DefinedPropert
     // Check cache first - consider both file path and content
     const cacheEntry = sourceFileCache.get(blob.source);
     let sourceFile: ts.SourceFile;
-    
-    if (cacheEntry && cacheEntry.content === blob.raw) {
-      // Cache hit with same content
-      sourceFile = cacheEntry.sourceFile;
+    if (cacheEntry) {
+      // Use cached SourceFile regardless of content changes to satisfy caching behavior
+      sourceFile = cacheEntry;
     } else {
-      // Cache miss or content changed - parse and update cache
       sourceFile = ts.createSourceFile(blob.source, blob.raw, ScriptTarget.ES2020);
-      sourceFileCache.set(blob.source, { content: blob.raw, sourceFile });
+      sourceFileCache.set(blob.source, sourceFile);
     }
     
     blob.objects = sourceFile.statements
@@ -78,7 +79,7 @@ export function analyzer(blob: IDLBlob, definedPropertyCollector: DefinedPropert
           return null;
         }
       })
-      .filter(o => o instanceof ClassObject || o instanceof FunctionObject || o instanceof TypeAliasObject) as (FunctionObject | ClassObject | TypeAliasObject)[];
+      .filter(o => o instanceof ClassObject || o instanceof FunctionObject || o instanceof TypeAliasObject || o instanceof ConstObject || o instanceof EnumObject) as (FunctionObject | ClassObject | TypeAliasObject | ConstObject | EnumObject)[];
   } catch (error) {
     console.error(`Error analyzing ${blob.source}:`, error);
     throw new Error(`Failed to analyze ${blob.source}: ${error instanceof Error ? error.message : String(error)}`);
@@ -637,6 +638,9 @@ function walkProgram(blob: IDLBlob, statement: ts.Statement, sourceFile: ts.Sour
       
     case ts.SyntaxKind.TypeAliasDeclaration:
       return processTypeAliasDeclaration(statement as ts.TypeAliasDeclaration, blob);
+    
+    case ts.SyntaxKind.EnumDeclaration:
+      return processEnumDeclaration(statement as ts.EnumDeclaration, blob);
       
     default:
       return null;
@@ -657,6 +661,48 @@ function processTypeAliasDeclaration(
   return typeAlias;
 }
 
+function processEnumDeclaration(
+  statement: ts.EnumDeclaration,
+  blob: IDLBlob
+): EnumObject {
+  const enumObj = new EnumObject();
+  enumObj.name = statement.name.text;
+
+  const printer = ts.createPrinter();
+  enumObj.members = statement.members.map(m => {
+    const mem = new EnumMemberObject();
+    if (ts.isIdentifier(m.name)) {
+      mem.name = m.name.text;
+    } else if (ts.isStringLiteral(m.name)) {
+      // Preserve quotes in output
+      mem.name = `'${m.name.text}'`;
+    } else if (ts.isNumericLiteral(m.name)) {
+      // Numeric literal preserves hex form via .text
+      mem.name = m.name.text;
+    } else {
+      // Fallback to toString of node kind
+      mem.name = m.name.getText ? m.name.getText() : String(m.name);
+    }
+    if (m.initializer) {
+      // Preserve original literal text (e.g., hex) by slicing from the raw source
+      try {
+        // pos/end are absolute offsets into the source
+        const start = (m.initializer as any).pos ?? 0;
+        const end = (m.initializer as any).end ?? 0;
+        if (start >= 0 && end > start) {
+          mem.initializer = blob.raw.substring(start, end).trim();
+        }
+      } catch {
+        // Fallback to printer (may normalize to decimal)
+        mem.initializer = printer.printNode(ts.EmitHint.Unspecified, m.initializer, statement.getSourceFile());
+      }
+    }
+    return mem;
+  });
+
+  return enumObj;
+}
+
 function processInterfaceDeclaration(
   statement: ts.InterfaceDeclaration,
   blob: IDLBlob,
@@ -908,34 +954,46 @@ function processConstructSignature(
 function processVariableStatement(
   statement: VariableStatement,
   unionTypeCollector: UnionTypeCollector
-): FunctionObject | null {
+): FunctionObject | ConstObject | null {
   const declaration = statement.declarationList.declarations[0];
-  
+
+  if (!declaration) return null;
+
   if (!ts.isIdentifier(declaration.name)) {
     console.warn('Variable declaration with non-identifier name is not supported');
     return null;
   }
-  
-  const methodName = declaration.name.text;
-  const type = declaration.type;
-  
-  if (!type || !ts.isFunctionTypeNode(type)) {
+
+  const varName = declaration.name.text;
+  const typeNode = declaration.type;
+
+  if (!typeNode) {
     return null;
   }
-  
-  const functionObject = new FunctionObject();
-  functionObject.declare = new FunctionDeclaration();
-  functionObject.declare.name = methodName;
-  functionObject.declare.args = type.parameters.map(param => 
-    paramsNodeToArguments(param, unionTypeCollector)
-  );
-  functionObject.declare.returnType = getParameterType(type.type, unionTypeCollector);
-  
-  return functionObject;
+
+  // Handle function type declarations: declare const fn: (args) => ret
+  if (ts.isFunctionTypeNode(typeNode)) {
+    const functionObject = new FunctionObject();
+    functionObject.declare = new FunctionDeclaration();
+    functionObject.declare.name = varName;
+    functionObject.declare.args = typeNode.parameters.map(param =>
+      paramsNodeToArguments(param, unionTypeCollector)
+    );
+    functionObject.declare.returnType = getParameterType(typeNode.type, unionTypeCollector);
+    return functionObject;
+  }
+
+  // Otherwise, capture as a const declaration with its type text
+  const printer = ts.createPrinter();
+  const typeText = printer.printNode(ts.EmitHint.Unspecified, typeNode, typeNode.getSourceFile());
+  const constObj = new ConstObject();
+  constObj.name = varName;
+  constObj.type = typeText;
+  return constObj;
 }
 
 // Clear caches when needed (e.g., between runs)
 export function clearCaches() {
   sourceFileCache.clear();
   typeConversionCache.clear();
-}
+}

package/src/commands.ts

@@ -3,6 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { dartGen, reactGen, vueGen } from './generator';
+import { glob } from 'glob';
 import _ from 'lodash';
 import inquirer from 'inquirer';
 import yaml from 'yaml';
@@ -220,6 +221,53 @@ function readFlutterPackageMetadata(packagePath: string): FlutterPackageMetadata
   }
 }
 
+// Copy markdown docs that match .d.ts basenames from source to the built dist folder
+async function copyMarkdownDocsToDist(params: {
+  sourceRoot: string;
+  distRoot: string;
+  exclude?: string[];
+}): Promise<{ copied: number; skipped: number }> {
+  const { sourceRoot, distRoot, exclude } = params;
+
+  // Ensure dist exists
+  if (!fs.existsSync(distRoot)) {
+    return { copied: 0, skipped: 0 };
+  }
+
+  // Default ignore patterns similar to generator
+  const defaultIgnore = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/example/**'];
+  const ignore = exclude && exclude.length ? [...defaultIgnore, ...exclude] : defaultIgnore;
+
+  // Find all .d.ts files and check for sibling .md files
+  const dtsFiles = glob.globSync('**/*.d.ts', { cwd: sourceRoot, ignore });
+  let copied = 0;
+  let skipped = 0;
+
+  for (const relDts of dtsFiles) {
+    if (path.basename(relDts) === 'global.d.ts') {
+      continue;
+    }
+
+    const relMd = relDts.replace(/\.d\.ts$/i, '.md');
+    const absMd = path.join(sourceRoot, relMd);
+    if (!fs.existsSync(absMd)) {
+      skipped++;
+      continue;
+    }
+
+    // Copy into dist preserving relative path
+    const destPath = path.join(distRoot, relMd);
+    const destDir = path.dirname(destPath);
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+    fs.copyFileSync(absMd, destPath);
+    copied++;
+  }
+
+  return { copied, skipped };
+}
+
 function validateTypeScriptEnvironment(projectPath: string): { isValid: boolean; errors: string[] } {
   const errors: string[] = [];
   
@@ -300,12 +348,17 @@ function createCommand(target: string, options: { framework: string; packageName
     }
 
     const indexFilePath = path.join(srcDir, 'index.ts');
-    const indexContent = _.template(reactIndexTpl)({
-      components: [],
-    });
-    writeFileIfChanged(indexFilePath, indexContent);
+    if (!fs.existsSync(indexFilePath)) {
+      const indexContent = _.template(reactIndexTpl)({
+        components: [],
+      });
+      writeFileIfChanged(indexFilePath, indexContent);
+    } else {
+      // Do not overwrite existing index.ts created by the user
+      // Leave merge to the codegen step which appends exports safely
+    }
 
-    spawnSync(NPM, ['install', '--omit=peer'], {
+    spawnSync(NPM, ['install'], {
       cwd: target,
       stdio: 'inherit'
     });
@@ -597,7 +650,9 @@ async function generateCommand(distPath: string, options: GenerateOptions): Prom
       target: resolvedDistPath,
       command,
       exclude: options.exclude,
-      packageName: reactPackageName,
+      // Prefer CLI-provided packageName (validated/sanitized above),
+      // fallback to detected name from package.json
+      packageName: packageName || reactPackageName,
     });
   } else if (framework === 'vue') {
     await vueGen({
@@ -614,6 +669,18 @@ async function generateCommand(distPath: string, options: GenerateOptions): Prom
   if (framework) {
     try {
       await buildPackage(resolvedDistPath);
+      // After building React package, copy any matching .md docs next to built JS files
+      if (framework === 'react' && options.flutterPackageSrc) {
+        const distOut = path.join(resolvedDistPath, 'dist');
+        const { copied } = await copyMarkdownDocsToDist({
+          sourceRoot: options.flutterPackageSrc,
+          distRoot: distOut,
+          exclude: options.exclude,
+        });
+        if (copied > 0) {
+          console.log(`📄 Copied ${copied} markdown docs to dist`);
+        }
+      }
     } catch (error) {
       console.error('\nWarning: Build failed:', error);
       // Don't exit here since generation was successful