@pie-element/cli 0.1.1

package/src/commands/upstream/analyze-esm.ts

@@ -0,0 +1,1973 @@
+import { Command, Flags } from '@oclif/core';
+import { Logger } from '../../utils/logger.js';
+import { loadPackageJson, type PackageJson } from '../../utils/package-json.js';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type {
+  CompatibilityReport,
+  ElementDetail,
+  EsmPackageValidation,
+  EsmRuntimeValidationResult,
+  EsmValidationResult,
+} from '../../utils/compatibility.js';
+import { assertReposExist } from '../../lib/upstream/repo-utils.js';
+
+// PIE elements that are actively used in pie-elements-ng
+// Only these elements will be analyzed
+const ACTIVE_ELEMENTS = [
+  'categorize',
+  'charting',
+  'complex-rubric',
+  'drag-in-the-blank',
+  'drawing-response',
+  'ebsr',
+  'explicit-constructed-response',
+  'extended-text-entry',
+  'fraction-model',
+  'graphing',
+  'graphing-solution-set',
+  'hotspot',
+  'image-cloze-association',
+  'inline-dropdown',
+  'likert',
+  'match',
+  'match-list',
+  'math-inline',
+  'math-templated',
+  'matrix',
+  'multi-trait-rubric',
+  'multiple-choice',
+  'number-line',
+  'passage',
+  'placement-ordering',
+  'rubric',
+  'select-text',
+];
+
+// Known ESM blockers - packages that prevent ESM builds
+const ESM_BLOCKERS = [
+  // Old Slate editor (v0.36.x) - not ESM compatible
+  { pattern: /^slate@0\.[0-4]\d/, reason: 'Slate v0.x is not ESM compatible' },
+  { pattern: /^slate-/, reason: 'Slate v0.x plugins are not ESM compatible' },
+
+  // Known CommonJS-only packages (add more as discovered)
+  { pattern: /^enzyme/, reason: 'Enzyme is not ESM compatible' },
+];
+
+// PIE lib packages that should always be included if compatible
+// These are packages that may be imported directly in code (e.g., controllers)
+// but not declared in package.json dependencies
+const ALWAYS_INCLUDE_PIE_LIB = [
+  'controller-utils', // Used in controller code via direct imports
+];
+
+export default class AnalyzeEsm extends Command {
+  static override description = 'Analyze PIE elements for ESM compatibility';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %>',
+    '<%= config.bin %> <%= command.id %> --verbose',
+    '<%= config.bin %> <%= command.id %> --output=./.compatibility/custom-report.json',
+  ];
+
+  static override flags = {
+    verbose: Flags.boolean({
+      char: 'v',
+      description: 'Show detailed analysis output',
+      default: false,
+    }),
+    'pie-elements': Flags.string({
+      description: 'Path to pie-elements repo',
+      default: '../pie-elements',
+    }),
+    'pie-lib': Flags.string({
+      description: 'Path to pie-lib repo',
+      default: '../pie-lib',
+    }),
+    output: Flags.string({
+      description: 'Output JSON file path',
+      default: './.compatibility/report.json',
+    }),
+    'include-dev-deps': Flags.boolean({
+      description:
+        'Include devDependencies in blocker analysis (usually unnecessary since pie-elements-ng does not sync upstream tests)',
+      default: false,
+    }),
+    'validate-esm-player': Flags.boolean({
+      description: 'Validate ESM player compatibility (package.json structure, exports).',
+      default: true,
+      allowNo: true,
+    }),
+    'runtime-cdn-base-url': Flags.string({
+      description: 'CDN base URL to use for runtime probes (e.g. https://esm.sh)',
+      default: 'https://esm.sh',
+    }),
+    'runtime-local-pie-elements-path': Flags.string({
+      description: 'Path to sibling pie-elements repo used for local PIE resolution during probes.',
+      default: '../pie-elements',
+    }),
+    'runtime-local-pie-lib-path': Flags.string({
+      description: 'Path to sibling pie-lib repo used for local PIE resolution during probes.',
+      default: '../pie-lib',
+    }),
+    'runtime-timeout-ms': Flags.integer({
+      description: 'Timeout for each runtime probe request (ms)',
+      default: 6000,
+    }),
+    'runtime-concurrency': Flags.integer({
+      description: 'Max concurrent runtime probes',
+      default: 8,
+    }),
+    'runtime-max-depth': Flags.integer({
+      description: 'Max import graph depth for the deep runtime probe',
+      default: 6,
+    }),
+    'runtime-max-modules': Flags.integer({
+      description: 'Max total modules fetched per element for the deep runtime probe',
+      default: 250,
+    }),
+    'runtime-cache-file': Flags.string({
+      description:
+        'Optional JSON cache file path for runtime probe results (speeds up repeated runs)',
+      default: './.cache/analyze-esm.runtime-cache.json',
+    }),
+  };
+
+  private logger = new Logger();
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(AnalyzeEsm);
+
+    this.logger = new Logger(flags.verbose);
+
+    if (flags.verbose) {
+      this.logger.section('🔍 Analyzing ESM Compatibility');
+      this.logger.info(`   PIE Elements: ${flags['pie-elements']}`);
+      this.logger.info(`   PIE Lib:      ${flags['pie-lib']}\n`);
+    }
+
+    // Verify repos exist
+    try {
+      assertReposExist([
+        { label: 'pie-elements', path: flags['pie-elements'] },
+        { label: 'pie-lib', path: flags['pie-lib'] },
+      ]);
+    } catch (error) {
+      this.error(error instanceof Error ? error.message : String(error));
+    }
+
+    const report = await this.analyzeCompatibility(
+      flags['pie-elements'],
+      flags['pie-lib'],
+      flags.verbose,
+      flags['include-dev-deps'],
+      flags['validate-esm-player'],
+      flags['runtime-cdn-base-url'],
+      flags['runtime-local-pie-elements-path'],
+      flags['runtime-local-pie-lib-path'],
+      flags['runtime-timeout-ms'],
+      flags['runtime-concurrency'],
+      flags['runtime-max-depth'],
+      flags['runtime-max-modules'],
+      flags['runtime-cache-file']
+    );
+
+    // Save JSON report
+    const outputDir = join(flags.output, '..');
+    await mkdir(outputDir, { recursive: true });
+    await writeFile(flags.output, JSON.stringify(report, null, 2), 'utf-8');
+
+    // Print summary
+    this.printReport(report, flags.output);
+  }
+
+  private async analyzeCompatibility(
+    pieElementsPath: string,
+    pieLibPath: string,
+    verbose: boolean,
+    includeDevDeps: boolean,
+    validateEsmPlayer: boolean,
+    runtimeCdnBaseUrl: string,
+    runtimeLocalPieElementsPath: string,
+    runtimeLocalPieLibPath: string,
+    runtimeTimeoutMs: number,
+    runtimeConcurrency: number,
+    runtimeMaxDepth: number,
+    runtimeMaxModules: number,
+    runtimeCacheFile: string
+  ): Promise<CompatibilityReport> {
+    if (!verbose) {
+      this.logger.progressStart('Analyzing ESM compatibility...');
+    }
+
+    const report: CompatibilityReport = {
+      elements: [],
+      pieLibPackages: [],
+      blockedElements: {},
+      esmPlayerReady: [],
+      esmValidation: {},
+      esmPlayerValidationEnabled: validateEsmPlayer,
+      esmRuntimeValidationEnabled: true,
+      esmRuntimeCdnBaseUrl: runtimeCdnBaseUrl,
+      esmRuntimeValidation: {},
+      elementDetails: {},
+      pieLibDetails: {},
+      lastAnalyzed: new Date().toISOString(),
+      summary: {
+        totalElements: 0,
+        compatibleElements: 0,
+        blockedElements: 0,
+        esmPlayerReady: 0,
+        esmRuntimeReady: 0,
+        totalPieLibPackages: 0,
+        compatiblePieLibPackages: 0,
+      },
+    };
+
+    // Cache for pie-lib compatibility checks
+    const pieLibCache = new Map<
+      string,
+      {
+        compatible: boolean;
+        blockers: string[];
+      }
+    >();
+
+    // Get all element packages
+    const elementsDir = join(pieElementsPath, 'packages');
+    const allElements = await readdir(elementsDir);
+
+    // Filter to only active elements used in pie-elements-ng
+    const elements = allElements.filter((name) => ACTIVE_ELEMENTS.includes(name));
+
+    report.summary.totalElements = elements.length;
+
+    if (verbose) {
+      this.logger.info(`📊 Analyzing ${elements.length} elements...\n`);
+    }
+
+    // Track which elements use which pie-lib packages
+    const pieLibUsage = new Map<string, Set<string>>();
+
+    // Analyze each element
+    for (const element of elements.sort()) {
+      const result = await this.checkElementCompatibility(
+        element,
+        pieElementsPath,
+        pieLibPath,
+        pieLibCache,
+        verbose,
+        includeDevDeps
+      );
+
+      // Check subdirectories separately
+      const srcCheck = await this.checkSubdirectoryCompatibility(
+        element,
+        'src',
+        pieElementsPath,
+        pieLibPath,
+        pieLibCache,
+        verbose,
+        includeDevDeps
+      );
+
+      const configureCheck = await this.checkSubdirectoryCompatibility(
+        element,
+        'configure',
+        pieElementsPath,
+        pieLibPath,
+        pieLibCache,
+        verbose,
+        includeDevDeps
+      );
+
+      const controllerCheck = await this.checkSubdirectoryCompatibility(
+        element,
+        'controller',
+        pieElementsPath,
+        pieLibPath,
+        pieLibCache,
+        verbose,
+        includeDevDeps
+      );
+
+      // Add subdirectory results to element details
+      if (srcCheck !== null) {
+        result.studentUI = srcCheck;
+      }
+      if (configureCheck !== null) {
+        result.configure = configureCheck;
+      }
+      if (controllerCheck !== null) {
+        result.controller = controllerCheck;
+      }
+
+      report.elementDetails[element] = result;
+
+      if (result.compatible) {
+        report.elements.push(element);
+        report.summary.compatibleElements++;
+
+        // Track pie-lib usage (including transitive deps)
+        // For example: if element uses text-select, and text-select uses style-utils,
+        // we need to sync both text-select AND style-utils
+        const allPieLibDeps = await this.collectAllTransitivePieLibDeps(
+          result.pieLibDeps,
+          pieLibPath,
+          includeDevDeps
+        );
+
+        for (const pieLibDep of allPieLibDeps) {
+          if (!pieLibUsage.has(pieLibDep)) {
+            pieLibUsage.set(pieLibDep, new Set());
+          }
+          const usageSet = pieLibUsage.get(pieLibDep);
+          if (usageSet) {
+            usageSet.add(element);
+          }
+        }
+      } else {
+        report.blockedElements[element] = result.blockers;
+        report.summary.blockedElements++;
+      }
+    }
+
+    // Second pass: Check element-to-element dependencies
+    // Elements can only be compatible if all their element dependencies are also compatible
+    if (verbose) {
+      this.logger.info('\n🔗 Checking element-to-element dependencies...\n');
+    }
+
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const element of elements) {
+        const details = report.elementDetails[element];
+        if (!details?.compatible) continue; // Already blocked, skip
+
+        // Check if this element depends on any blocked elements
+        for (const depElement of details.pieElementDeps) {
+          const depDetails = report.elementDetails[depElement];
+
+          if (!depDetails?.compatible) {
+            // This element depends on a blocked element
+            const blocker = `@pie-element/${depElement} - dependency is not ESM compatible`;
+            details.blockers.push(blocker);
+            details.compatible = false;
+
+            // Move from compatible to blocked
+            const idx = report.elements.indexOf(element);
+            if (idx !== -1) {
+              report.elements.splice(idx, 1);
+              report.summary.compatibleElements--;
+            }
+            report.blockedElements[element] = details.blockers;
+            report.summary.blockedElements++;
+
+            changed = true;
+
+            if (verbose) {
+              this.logger.info(`  ❌ ${element}: depends on blocked element ${depElement}`);
+            }
+            break;
+          }
+        }
+      }
+    }
+
+    // Build pie-lib report
+    for (const [pieLibPkg, usedBy] of pieLibUsage.entries()) {
+      const check = pieLibCache.get(pieLibPkg);
+      if (check?.compatible) {
+        report.pieLibPackages.push(pieLibPkg);
+        report.pieLibDetails[pieLibPkg] = {
+          compatible: true,
+          usedBy: Array.from(usedBy),
+          blockers: [],
+        };
+      } else if (check) {
+        report.pieLibDetails[pieLibPkg] = {
+          compatible: false,
+          usedBy: Array.from(usedBy),
+          blockers: check.blockers,
+        };
+      }
+    }
+
+    // Add always-include pie-lib packages if they're compatible
+    for (const pieLibPkg of ALWAYS_INCLUDE_PIE_LIB) {
+      // Skip if already in the report
+      if (pieLibUsage.has(pieLibPkg)) {
+        continue;
+      }
+
+      // Check if this package exists and is compatible
+      let check = pieLibCache.get(pieLibPkg);
+      if (!check) {
+        check = await this.checkPieLibCompatibility(
+          pieLibPkg,
+          pieLibPath,
+          verbose,
+          includeDevDeps,
+          pieLibCache
+        );
+        pieLibCache.set(pieLibPkg, check);
+      }
+
+      if (check.compatible) {
+        report.pieLibPackages.push(pieLibPkg);
+        report.pieLibDetails[pieLibPkg] = {
+          compatible: true,
+          usedBy: ['(always included)'], // Mark as always included
+          blockers: [],
+        };
+        if (verbose) {
+          this.logger.info(`  ✅ ${pieLibPkg}: always included (compatible)`);
+        }
+      } else if (verbose) {
+        this.logger.info(`  ⏭️  ${pieLibPkg}: skipped (not compatible)`);
+      }
+    }
+
+    report.summary.totalPieLibPackages = pieLibUsage.size + ALWAYS_INCLUDE_PIE_LIB.length;
+    report.summary.compatiblePieLibPackages = report.pieLibPackages.length;
+
+    // Identify student-UI-only elements (blocked overall but student UI is compatible)
+    report.studentUIOnly = [];
+    for (const element of elements) {
+      const details = report.elementDetails[element];
+      if (!details?.compatible && details?.studentUI?.compatible) {
+        report.studentUIOnly.push(element);
+      }
+    }
+    report.summary.studentUIOnlyElements = report.studentUIOnly.length;
+
+    if (verbose && report.studentUIOnly.length > 0) {
+      this.logger.info(
+        `\n📱 Found ${report.studentUIOnly.length} elements with student-UI-only support:\n`
+      );
+      for (const element of report.studentUIOnly) {
+        this.logger.info(`  ${element}`);
+      }
+    }
+
+    // ESM player validation (only for compatible elements)
+    if (validateEsmPlayer) {
+      if (verbose) {
+        this.logger.info('\n🎮 Validating ESM player compatibility...\n');
+      }
+
+      for (const element of report.elements) {
+        const validation = await this.validateEsmPlayerCompatibility(
+          element,
+          pieElementsPath,
+          verbose
+        );
+
+        report.esmValidation[element] = validation;
+
+        if (validation.compatible) {
+          report.esmPlayerReady.push(element);
+          report.summary.esmPlayerReady++;
+        }
+      }
+    }
+
+    // Runtime-ish CDN probes (production-like signal)
+    const base = runtimeCdnBaseUrl.replace(/\/+$/, '');
+
+    // Probe all CommonJS-free elements by default.
+    // Rationale: "ESM ready in production" is primarily about whether the CDN can resolve
+    // the package + transitives into browser-loadable ESM, not whether upstream package.json
+    // has ideal exports metadata (which we often rewrite during sync).
+    const elementsToProbe = report.elements.slice();
+
+    const cache = await this.loadRuntimeCache(runtimeCacheFile);
+
+    if (verbose) {
+      this.logger.info(
+        `\n🌐 Probing ESM runtime readiness via CDN (${elementsToProbe.length} elements, concurrency=${runtimeConcurrency})...\n`
+      );
+      this.logger.info(`   CDN base: ${base}\n`);
+      this.logger.info(
+        `   Mode: deep (maxDepth=${runtimeMaxDepth}, maxModules=${runtimeMaxModules})\n`
+      );
+      this.logger.info(
+        `   Local PIE resolution: enabled (pie-elements=${runtimeLocalPieElementsPath}, pie-lib=${runtimeLocalPieLibPath})\n`
+      );
+    } else {
+      this.logger.info(
+        `🌐 Probing ESM runtime readiness via CDN (${elementsToProbe.length} elements, concurrency=${runtimeConcurrency})...`
+      );
+    }
+
+    const results = await this.probeElementsRuntime({
+      elements: elementsToProbe,
+      pieElementsPath,
+      cdnBaseUrl: base,
+      localPieEnabled: true,
+      localPieElementsPath: runtimeLocalPieElementsPath,
+      localPieLibPath: runtimeLocalPieLibPath,
+      timeoutMs: runtimeTimeoutMs,
+      concurrency: runtimeConcurrency,
+      deep: true,
+      maxDepth: runtimeMaxDepth,
+      maxModules: runtimeMaxModules,
+      cache,
+      verbose,
+    });
+
+    let okCount = 0;
+    for (const [element, result] of Object.entries(results)) {
+      report.esmRuntimeValidation ??= {};
+      report.esmRuntimeValidation[element] = result;
+      if (result.compatible) okCount++;
+    }
+    report.summary.esmRuntimeReady = okCount;
+
+    await this.saveRuntimeCache(runtimeCacheFile, cache);
+
+    if (!verbose) {
+      this.logger.info(`   Runtime-ready: ${okCount}/${elementsToProbe.length}\n`);
+    }
+
+    if (!verbose) {
+      this.logger.progressComplete();
+      this.logger.info('');
+      this.logger.success(`${report.summary.compatibleElements} elements compatible`);
+      if (report.summary.blockedElements > 0) {
+        this.logger.warn(`${report.summary.blockedElements} elements blocked`);
+      }
+      if (report.summary.compatiblePieLibPackages > 0) {
+        this.logger.info(`${report.summary.compatiblePieLibPackages} @pie-lib packages compatible`);
+      }
+      if (report.summary.totalPieLibPackages - report.summary.compatiblePieLibPackages > 0) {
+        this.logger.warn(
+          `${report.summary.totalPieLibPackages - report.summary.compatiblePieLibPackages} @pie-lib packages blocked`
+        );
+      }
+      this.logger.info('');
+      this.logger.info('Run with --verbose to see detailed blocker information');
+      this.logger.info('');
+    }
+
+    return report;
+  }
+
+  private async loadRuntimeCache(
+    filePath: string
+  ): Promise<Record<string, EsmRuntimeValidationResult>> {
+    try {
+      if (!existsSync(filePath)) return {};
+      const raw = await readFile(filePath, 'utf-8');
+      return JSON.parse(raw) as Record<string, EsmRuntimeValidationResult>;
+    } catch {
+      return {};
+    }
+  }
+
+  private async saveRuntimeCache(
+    filePath: string,
+    cache: Record<string, EsmRuntimeValidationResult>
+  ): Promise<void> {
+    try {
+      const dir = filePath.includes('/') ? filePath.split('/').slice(0, -1).join('/') : '.';
+      if (dir && dir !== '.' && !existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+      }
+      await writeFile(filePath, JSON.stringify(cache, null, 2), 'utf-8');
+    } catch {
+      // Best-effort cache only.
+    }
+  }
+
+  private async parseAsEsm(code: string): Promise<boolean> {
+    try {
+      const mod = (await import('es-module-lexer')) as unknown as {
+        init: Promise<void>;
+        parse: (source: string) => [unknown[], unknown];
+      };
+      await mod.init;
+      mod.parse(code);
+      return true;
+    } catch {
+      // Fallback: very light heuristic (still useful signal for obvious non-JS responses).
+      return typeof code === 'string' && code.length > 0;
+    }
+  }
+
+  private async getImportSpecifiers(code: string): Promise<string[]> {
+    try {
+      const mod = (await import('es-module-lexer')) as unknown as {
+        init: Promise<void>;
+        parse: (source: string) => [{ s: number; e: number }[], unknown];
+      };
+      await mod.init;
+      const [imports] = mod.parse(code);
+      const specs: string[] = [];
+      for (const i of imports) {
+        const spec = code.slice(i.s, i.e);
+        if (spec) specs.push(spec);
+      }
+      return specs;
+    } catch {
+      return [];
+    }
+  }
+
+  private resolveImportUrl(fromUrl: string, spec: string, cdnBaseUrl: string): string | null {
+    if (!spec) return null;
+    if (spec.startsWith('data:')) return null;
+    if (spec.startsWith('http://') || spec.startsWith('https://')) return spec;
+    if (spec.startsWith('//')) return `https:${spec}`;
+    if (spec.startsWith('/')) return `${cdnBaseUrl.replace(/\/+$/, '')}${spec}`;
+    if (spec.startsWith('./') || spec.startsWith('../')) return new URL(spec, fromUrl).toString();
+    // Bare specifiers shouldn't typically appear in CDN output; best-effort map to base.
+    return `${cdnBaseUrl.replace(/\/+$/, '')}/${spec}`;
+  }
+
+  private isPiePackageSpecifier(spec: string): boolean {
+    return (
+      spec.startsWith('@pie-lib/') ||
+      spec.startsWith('@pie-element/') ||
+      spec.startsWith('@pie-element/')
+    );
+  }
+
+  private tryResolvePieToLocalFile(
+    spec: string,
+    pieElementsPath: string,
+    pieLibPath: string
+  ): string | null {
+    // Map PIE package specifiers to sibling upstream source trees.
+    // Supports:
+    //  - @pie-lib/<name>[/subpath]        -> <pie-lib>/packages/<name>/src/...
+    //  - @pie-element/<name>[/subpath]   -> <pie-elements>/packages/<name>/src/... (and controller/configure sources)
+    const [scope, name, ...rest] = spec.split('/');
+    const subpath = rest.join('/');
+
+    if (scope === '@pie-lib') {
+      const base = join(pieLibPath, 'packages', name, 'src');
+      return this.resolveLocalEntrypoint(base, subpath);
+    }
+
+    if (scope === '@pie-element') {
+      // Special-case known subpaths that live outside src/ in upstream.
+      if (subpath === 'controller' || subpath.startsWith('controller/')) {
+        const controllerSub = subpath === 'controller' ? '' : subpath.replace(/^controller\//, '');
+        const base = join(pieElementsPath, 'packages', name, 'controller', 'src');
+        return this.resolveLocalEntrypoint(base, controllerSub);
+      }
+      if (subpath === 'configure' || subpath.startsWith('configure/')) {
+        const cfgSub = subpath === 'configure' ? '' : subpath.replace(/^configure\//, '');
+        const base = join(pieElementsPath, 'packages', name, 'configure', 'src');
+        return this.resolveLocalEntrypoint(base, cfgSub);
+      }
+
+      const base = join(pieElementsPath, 'packages', name, 'src');
+      return this.resolveLocalEntrypoint(base, subpath);
+    }
+
+    return null;
+  }
+
+  private resolveLocalEntrypoint(srcBaseDir: string, subpath: string): string | null {
+    const candidates: string[] = [];
+    if (!subpath) {
+      candidates.push(join(srcBaseDir, 'index.ts'));
+      candidates.push(join(srcBaseDir, 'index.tsx'));
+      candidates.push(join(srcBaseDir, 'index.js'));
+      candidates.push(join(srcBaseDir, 'index.jsx'));
+    } else {
+      const normalized = subpath.replace(/^\/+/, '');
+      // common convention: <subpath>/index.*
+      candidates.push(join(srcBaseDir, normalized, 'index.ts'));
+      candidates.push(join(srcBaseDir, normalized, 'index.tsx'));
+      candidates.push(join(srcBaseDir, normalized, 'index.js'));
+      candidates.push(join(srcBaseDir, normalized, 'index.jsx'));
+      // direct file
+      candidates.push(join(srcBaseDir, `${normalized}.ts`));
+      candidates.push(join(srcBaseDir, `${normalized}.tsx`));
+      candidates.push(join(srcBaseDir, `${normalized}.js`));
+      candidates.push(join(srcBaseDir, `${normalized}.jsx`));
+    }
+
+    for (const c of candidates) {
+      if (existsSync(c)) return `file://${c}`;
+    }
+    return null;
+  }
+
+  private resolveLocalImport(fromFileUrl: string, spec: string): string | null {
+    // Supports extensionless TS/JS imports and index resolution.
+    const fromPath = fromFileUrl.startsWith('file://')
+      ? fromFileUrl.slice('file://'.length)
+      : fromFileUrl;
+    const baseDir = join(fromPath, '..');
+    const tryPaths: string[] = [];
+
+    const resolved = join(baseDir, spec);
+    if (
+      spec.endsWith('.ts') ||
+      spec.endsWith('.tsx') ||
+      spec.endsWith('.js') ||
+      spec.endsWith('.jsx')
+    ) {
+      tryPaths.push(resolved);
+    } else {
+      tryPaths.push(resolved + '.ts');
+      tryPaths.push(resolved + '.tsx');
+      tryPaths.push(resolved + '.js');
+      tryPaths.push(resolved + '.jsx');
+      tryPaths.push(join(resolved, 'index.ts'));
+      tryPaths.push(join(resolved, 'index.tsx'));
+      tryPaths.push(join(resolved, 'index.js'));
+      tryPaths.push(join(resolved, 'index.jsx'));
+    }
+
+    for (const p of tryPaths) {
+      if (existsSync(p)) return `file://${p}`;
+    }
+    return null;
+  }
+
+  private getTsImportSpecifiers(code: string): string[] {
+    // Minimal TS import extractor that handles import ... from "x" and export ... from "x".
+    // We do not attempt full TS AST walking here to keep dependencies minimal.
+    const specs = new Set<string>();
+    const re = /\b(?:import|export)\s+(?:type\s+)?(?:[^'"]*?\s+from\s+)?['"]([^'"]+)['"]/g;
+    for (const m of code.matchAll(re)) {
+      if (m[1]) specs.add(m[1]);
+    }
+    // dynamic import("x")
+    const reDyn = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    for (const m of code.matchAll(reDyn)) {
+      if (m[1]) specs.add(m[1]);
+    }
+    return Array.from(specs);
+  }
+
+  private async deepProbeFromUrl(opts: {
+    entryUrl: string;
+    cdnBaseUrl: string;
+    timeoutMs: number;
+    maxDepth: number;
+    maxModules: number;
+    logPrefix: string;
+    localPieEnabled: boolean;
+    localPieElementsPath: string;
+    localPieLibPath: string;
+  }): Promise<{
+    ok: boolean;
+    fetched: number;
+    fetchedOk: number;
+    firstFailingUrl?: string;
+    errors: string[];
+  }> {
+    const {
+      entryUrl,
+      cdnBaseUrl,
+      timeoutMs,
+      maxDepth,
+      maxModules,
+      logPrefix,
+      localPieEnabled,
+      localPieElementsPath,
+      localPieLibPath,
+    } = opts;
+    const visited = new Set<string>();
+    const errors: string[] = [];
+    let fetched = 0;
+    let fetchedOk = 0;
+    let firstFailingUrl: string | undefined;
+    let lastLogAt = 0;
+
+    const queue: Array<{ url: string; depth: number }> = [{ url: entryUrl, depth: 0 }];
+    while (queue.length > 0) {
+      const next = queue.shift();
+      if (!next) break;
+      if (next.depth > maxDepth) continue;
+      if (visited.has(next.url)) continue;
+      if (visited.size >= maxModules) break;
+      visited.add(next.url);
+
+      fetched++;
+      // Periodic progress logging (deep probe can take a while)
+      // Log at most every ~2s, and also on notable milestones.
+      const now = Date.now();
+      if (fetched === 1 || fetched % 50 === 0 || now - lastLogAt > 2000) {
+        lastLogAt = now;
+        this.logger.info(
+          `   ⏳ ${logPrefix}: fetched ${fetched}/${maxModules} modules (ok ${fetchedOk}), queue ${queue.length}, depth ${next.depth}/${maxDepth}`
+        );
+      }
+      const res = await this.fetchTextWithTimeout(next.url, timeoutMs);
+      if (!res.ok) {
+        const baseMsg = `fetch ${next.url} -> ${res.status || 'error'} (${res.text.slice(0, 120)})`;
+        const jsxHint =
+          typeof res.text === 'string' &&
+          res.text.includes('The JSX syntax extension is not currently enabled')
+            ? ' Hint: CDN failed parsing JSX in a .js/.mjs file. This usually means the published package contains uncompiled JSX; fix build output or file extensions.'
+            : '';
+        const msg = baseMsg + jsxHint;
+        errors.push(msg);
+        if (!firstFailingUrl) firstFailingUrl = next.url;
+        continue;
+      }
+      fetchedOk++;
+
+      // For local file:// sources, parse imports in a TS-friendly way (regex-based).
+      // For CDN URLs, parse as ESM and use es-module-lexer import locations.
+      const isFile = next.url.startsWith('file://');
+      if (!isFile) {
+        const parses = await this.parseAsEsm(res.text);
+        if (!parses) {
+          const msg = `parse ${next.url} -> non-parseable JS`;
+          errors.push(msg);
+          if (!firstFailingUrl) firstFailingUrl = next.url;
+          continue;
+        }
+      }
+
+      const specs = isFile
+        ? this.getTsImportSpecifiers(res.text)
+        : await this.getImportSpecifiers(res.text);
+      for (const spec of specs) {
+        let resolved: string | null = null;
+
+        // Prefer local resolution for PIE packages when enabled.
+        if (localPieEnabled && this.isPiePackageSpecifier(spec)) {
+          resolved = this.tryResolvePieToLocalFile(spec, localPieElementsPath, localPieLibPath);
+        }
+
+        if (!resolved) {
+          if (isFile && (spec.startsWith('./') || spec.startsWith('../'))) {
+            resolved = this.resolveLocalImport(next.url, spec);
+          } else {
+            resolved = this.resolveImportUrl(next.url, spec, cdnBaseUrl);
+          }
+        }
+
+        if (!resolved) continue;
+        if (!visited.has(resolved)) queue.push({ url: resolved, depth: next.depth + 1 });
+      }
+    }
+
+    return { ok: errors.length === 0, fetched, fetchedOk, firstFailingUrl, errors };
+  }
+
+  private async fetchTextWithTimeout(
+    url: string,
+    timeoutMs: number
+  ): Promise<{ ok: boolean; status: number; text: string }> {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, { signal: controller.signal });
+      const text = await res.text();
+      return { ok: res.ok, status: res.status, text };
+    } catch (e: any) {
+      return { ok: false, status: 0, text: String(e?.message || e) };
+    } finally {
+      clearTimeout(t);
+    }
+  }
+
+  private async probeElementsRuntime(opts: {
+    elements: string[];
+    pieElementsPath: string;
+    cdnBaseUrl: string;
+    localPieEnabled: boolean;
+    localPieElementsPath: string;
+    localPieLibPath: string;
+    timeoutMs: number;
+    concurrency: number;
+    deep: boolean;
+    maxDepth: number;
+    maxModules: number;
+    cache: Record<string, EsmRuntimeValidationResult>;
+    verbose: boolean;
+  }): Promise<Record<string, EsmRuntimeValidationResult>> {
+    const {
+      elements,
+      pieElementsPath,
+      cdnBaseUrl,
+      localPieEnabled,
+      localPieElementsPath,
+      localPieLibPath,
+      timeoutMs,
+      concurrency,
+      deep,
+      maxDepth,
+      maxModules,
+      cache,
+      verbose,
+    } = opts;
+
+    const results: Record<string, EsmRuntimeValidationResult> = {};
+    const queue = elements.slice();
+    let done = 0;
+
+    const worker = async () => {
+      while (queue.length > 0) {
+        const element = queue.shift();
+        if (!element) return;
+
+        const pkgPath = join(pieElementsPath, 'packages', element, 'package.json');
+        const pkg = (await loadPackageJson(pkgPath)) as PackageJson;
+        const pkgName = `@pie-element/${element}`;
+        const version = String((pkg as any).version || 'latest');
+        // Cache key must include probe mode + limits, otherwise a shallow cached result
+        // would incorrectly satisfy a deep/transitive run.
+        const cacheKey = `${cdnBaseUrl}|${pkgName}@${version}|mode=${deep ? 'deep' : 'shallow'}|depth=${maxDepth}|modules=${maxModules}`;
+
+        if (cache[cacheKey]) {
+          results[element] = cache[cacheKey];
+          done++;
+          if (!verbose && done % 5 === 0)
+            this.logger.info(`   Progress: ${done}/${elements.length}`);
+          continue;
+        }
+
+        const entryUrl = `${cdnBaseUrl}/${pkgName}@${version}`;
+        const controllerUrl = `${cdnBaseUrl}/${pkgName}@${version}/controller`;
+
+        const out: EsmRuntimeValidationResult = {
+          compatible: false,
+          cdnBaseUrl,
+          version,
+          entryOk: false,
+          controllerOk: false,
+          entryParseOk: false,
+          controllerParseOk: false,
+          errors: [],
+          probeMode: deep ? 'deep' : 'shallow',
+          maxDepth: deep ? maxDepth : undefined,
+          maxModules: deep ? maxModules : undefined,
+        };
+
+        if (!deep) {
+          const entry = await this.fetchTextWithTimeout(entryUrl, timeoutMs);
+          out.entryOk = entry.ok;
+          if (!entry.ok) {
+            out.errors.push(
+              `entry ${entryUrl} -> ${entry.status || 'error'} (${entry.text.slice(0, 120)})`
+            );
+          } else {
+            out.entryParseOk = await this.parseAsEsm(entry.text);
+            if (!out.entryParseOk) out.errors.push(`entry ${entryUrl} returned non-parseable JS`);
+          }
+
+          const ctrl = await this.fetchTextWithTimeout(controllerUrl, timeoutMs);
+          out.controllerOk = ctrl.ok;
+          if (!ctrl.ok) {
+            out.errors.push(
+              `controller ${controllerUrl} -> ${ctrl.status || 'error'} (${ctrl.text.slice(0, 120)})`
+            );
+          } else {
+            out.controllerParseOk = await this.parseAsEsm(ctrl.text);
+            if (!out.controllerParseOk)
+              out.errors.push(`controller ${controllerUrl} returned non-parseable JS`);
+          }
+
+          out.compatible =
+            out.entryOk && out.entryParseOk && out.controllerOk && out.controllerParseOk;
+        } else {
+          // Deep probe: walk import graphs for entry and controller
+          // Still record the top-level entry/controller status for readability.
+          const entryTop = await this.fetchTextWithTimeout(entryUrl, timeoutMs);
+          out.entryOk = entryTop.ok;
+          out.entryParseOk = entryTop.ok ? await this.parseAsEsm(entryTop.text) : false;
+
+          const ctrlTop = await this.fetchTextWithTimeout(controllerUrl, timeoutMs);
+          out.controllerOk = ctrlTop.ok;
+          out.controllerParseOk = ctrlTop.ok ? await this.parseAsEsm(ctrlTop.text) : false;
+
+          const entryDeep = await this.deepProbeFromUrl({
+            entryUrl,
+            cdnBaseUrl,
+            timeoutMs,
+            maxDepth,
+            maxModules,
+            logPrefix: `${element} entry`,
+            localPieEnabled,
+            localPieElementsPath,
+            localPieLibPath,
+          });
+          const ctrlDeep = await this.deepProbeFromUrl({
+            entryUrl: controllerUrl,
+            cdnBaseUrl,
+            timeoutMs,
+            maxDepth,
+            maxModules,
+            logPrefix: `${element} controller`,
+            localPieEnabled,
+            localPieElementsPath,
+            localPieLibPath,
+          });
+
+          out.fetchedModules = (entryDeep.fetched || 0) + (ctrlDeep.fetched || 0);
+          out.fetchedOk = (entryDeep.fetchedOk || 0) + (ctrlDeep.fetchedOk || 0);
+          out.firstFailingUrl = entryDeep.firstFailingUrl || ctrlDeep.firstFailingUrl;
+          out.errors.push(...entryDeep.errors.slice(0, 5));
+          out.errors.push(...ctrlDeep.errors.slice(0, 5));
+
+          out.compatible =
+            out.entryOk &&
+            out.entryParseOk &&
+            out.controllerOk &&
+            out.controllerParseOk &&
+            entryDeep.ok &&
+            ctrlDeep.ok;
+        }
+
+        cache[cacheKey] = out;
+        results[element] = out;
+
+        done++;
+        if (verbose) {
+          this.logger.info(
+            `   • ${element} -> ${out.compatible ? '✅' : '❌'} (entry:${out.entryOk ? 'ok' : 'bad'}, controller:${out.controllerOk ? 'ok' : 'bad'})`
+          );
+          if (!out.compatible && out.errors.length > 0) {
+            this.logger.info(`     - ${out.errors[0]}`);
+          }
+        } else if (done % 5 === 0 || done === elements.length) {
+          this.logger.info(`   Progress: ${done}/${elements.length}`);
+        }
+      }
+    };
+
+    await Promise.all(
+      Array.from({ length: Math.max(1, Math.min(concurrency, elements.length)) }, () => worker())
+    );
+    return results;
+  }
+
+  private async checkElementCompatibility(
+    elementName: string,
+    pieElementsPath: string,
+    pieLibPath: string,
+    pieLibCache: Map<string, { compatible: boolean; blockers: string[] }>,
+    verbose: boolean,
+    includeDevDeps: boolean
+  ): Promise<ElementDetail> {
+    const blockers: string[] = [];
+    const elementPath = join(pieElementsPath, 'packages', elementName, 'package.json');
+    const pkg = await loadPackageJson(elementPath);
+
+    if (!pkg) {
+      blockers.push(`Package.json not found at ${elementPath}`);
+      return { compatible: false, directDeps: [], pieLibDeps: [], pieElementDeps: [], blockers };
+    }
+
+    const deps = this.getAllDeps(pkg, includeDevDeps);
+    const directDeps = Object.keys(deps);
+    const pieLibDeps = this.extractPieLibDeps(deps);
+    const pieElementDeps = this.extractPieElementDeps(deps);
+
+    if (verbose) {
+      this.logger.info(`\n  📦 ${elementName}:`);
+      this.logger.info(`    Direct deps: ${directDeps.length}`);
+      this.logger.info(`    PIE Lib deps: ${pieLibDeps.join(', ') || 'none'}`);
+      this.logger.info(`    PIE Element deps: ${pieElementDeps.join(', ') || 'none'}`);
+    }
+
+    // Deep scan all dependencies recursively
+    const depCache = new Map<string, { compatible: boolean; blockers: string[] }>();
+    for (const [dep, version] of Object.entries(deps)) {
+      // Skip pie-lib packages - we'll check those separately
+      if (dep.startsWith('@pie-lib/')) {
+        continue;
+      }
+
+      await this.checkDependencyDeep(
+        dep,
+        version,
+        pieElementsPath,
+        pieLibPath,
+        depCache,
+        blockers,
+        verbose,
+        includeDevDeps,
+        []
+      );
+    }
+
+    // Check transitive pie-lib dependencies
+    for (const pieLibDep of pieLibDeps) {
+      let pieLibCheck = pieLibCache.get(pieLibDep);
+
+      if (!pieLibCheck) {
+        pieLibCheck = await this.checkPieLibCompatibility(
+          pieLibDep,
+          pieLibPath,
+          verbose,
+          includeDevDeps,
+          pieLibCache
+        );
+        pieLibCache.set(pieLibDep, pieLibCheck);
+      }
+
+      if (!pieLibCheck.compatible) {
+        for (const blocker of pieLibCheck.blockers) {
+          const transitiveBlocker = `@pie-lib/${pieLibDep} -> ${blocker}`;
+          blockers.push(transitiveBlocker);
+          if (verbose) {
+            this.logger.info(`    ❌ Transitive: ${transitiveBlocker}`);
+          }
+        }
+      }
+    }
+
+    const compatible = blockers.length === 0;
+
+    if (verbose && compatible) {
+      this.logger.info('    ✅ Compatible!');
+    }
+
+    return {
+      compatible,
+      directDeps,
+      pieLibDeps,
+      pieElementDeps,
+      blockers,
+    };
+  }
+
+  /**
+   * Check subdirectory compatibility (src/, configure/, controller/)
+   * Returns compatibility status for each subdirectory that has its own package.json
+   */
+  private async checkSubdirectoryCompatibility(
+    elementName: string,
+    subdirName: 'src' | 'configure' | 'controller',
+    pieElementsPath: string,
+    pieLibPath: string,
+    pieLibCache: Map<string, { compatible: boolean; blockers: string[] }>,
+    verbose: boolean,
+    includeDevDeps: boolean
+  ): Promise<{ compatible: boolean; blockers: string[] } | null> {
+    const subdirPath = join(pieElementsPath, 'packages', elementName, subdirName);
+    const pkgJsonPath = join(subdirPath, 'package.json');
+
+    // If no package.json in subdirectory, it's part of the main element
+    if (!existsSync(pkgJsonPath)) {
+      return null;
+    }
+
+    const blockers: string[] = [];
+    const pkg = await loadPackageJson(pkgJsonPath);
+
+    if (!pkg) {
+      return null;
+    }
+
+    const deps = this.getAllDeps(pkg, includeDevDeps);
+    const pieLibDeps = this.extractPieLibDeps(deps);
+
+    if (verbose) {
+      this.logger.info(`    📁 ${subdirName}/: checking ${Object.keys(deps).length} dependencies`);
+    }
+
+    // Deep scan all dependencies
+    const depCache = new Map<string, { compatible: boolean; blockers: string[] }>();
+    for (const [dep, version] of Object.entries(deps)) {
+      if (dep.startsWith('@pie-lib/')) {
+        continue;
+      }
+
+      await this.checkDependencyDeep(
+        dep,
+        version,
+        pieElementsPath,
+        pieLibPath,
+        depCache,
+        blockers,
+        verbose,
+        includeDevDeps,
+        []
+      );
+    }
+
+    // Check pie-lib dependencies
+    for (const pieLibDep of pieLibDeps) {
+      let pieLibCheck = pieLibCache.get(pieLibDep);
+
+      if (!pieLibCheck) {
+        pieLibCheck = await this.checkPieLibCompatibility(
+          pieLibDep,
+          pieLibPath,
+          verbose,
+          includeDevDeps,
+          pieLibCache
+        );
+        pieLibCache.set(pieLibDep, pieLibCheck);
+      }
+
+      if (!pieLibCheck.compatible) {
+        for (const blocker of pieLibCheck.blockers) {
+          const transitiveBlocker = `@pie-lib/${pieLibDep} -> ${blocker}`;
+          blockers.push(transitiveBlocker);
+          if (verbose) {
+            this.logger.info(`      ❌ ${subdirName}/: ${transitiveBlocker}`);
+          }
+        }
+      }
+    }
+
+    const compatible = blockers.length === 0;
+
+    if (verbose) {
+      if (compatible) {
+        this.logger.info(`      ✅ ${subdirName}/: Compatible`);
+      } else {
+        this.logger.info(`      ❌ ${subdirName}/: Blocked`);
+      }
+    }
+
+    return { compatible, blockers };
+  }
+
+  private async checkDependencyDeep(
+    depName: string,
+    version: string,
+    pieElementsPath: string,
+    pieLibPath: string,
+    cache: Map<string, { compatible: boolean; blockers: string[] }>,
+    blockers: string[],
+    verbose: boolean,
+    includeDevDeps: boolean,
+    depChain: string[]
+  ): Promise<void> {
+    const depKey = `${depName}@${version}`;
+
+    // Check cache
+    if (cache.has(depKey)) {
+      const cached = cache.get(depKey);
+      if (cached && !cached.compatible) {
+        for (const blocker of cached.blockers) {
+          const chain = [...depChain, blocker].join(' -> ');
+          if (!blockers.includes(chain)) {
+            blockers.push(chain);
+          }
+        }
+      }
+      return;
+    }
+
+    // Check if this is a known ESM blocker
+    const blocker = this.checkEsmBlocker(depName, version);
+    if (blocker) {
+      const chain = [...depChain, blocker].join(' -> ');
+      if (!blockers.includes(chain)) {
+        blockers.push(chain);
+        if (verbose) {
+          this.logger.info(`    ❌ Transitive: ${chain}`);
+        }
+      }
+      cache.set(depKey, { compatible: false, blockers: [blocker] });
+      return;
+    }
+
+    // Try to load package.json from upstream repos to get transitive deps
+    // Look in pie-elements node_modules first, then pie-lib node_modules
+    let pkg: PackageJson | null = null;
+    const possiblePaths = [
+      join(pieElementsPath, 'node_modules', depName, 'package.json'),
+      join(pieLibPath, 'node_modules', depName, 'package.json'),
+    ];
+
+    for (const path of possiblePaths) {
+      if (existsSync(path)) {
+        pkg = await loadPackageJson(path);
+        if (pkg) break;
+      }
+    }
+
+    if (!pkg) {
+      // Can't resolve - assume compatible (will be caught by runtime validation if problematic)
+      cache.set(depKey, { compatible: true, blockers: [] });
+      return;
+    }
+
+    // Check transitive dependencies
+    const transitiveDeps = this.getAllDeps(pkg, false); // Don't include devDeps for transitive checks
+    const hasBlockers = false;
+
+    for (const [transitiveDep, transitiveVersion] of Object.entries(transitiveDeps)) {
+      // Skip PIE packages in transitive scan
+      if (
+        transitiveDep.startsWith('@pie-lib/') ||
+        transitiveDep.startsWith('@pie-element/') ||
+        transitiveDep.startsWith('@pie-element/')
+      ) {
+        continue;
+      }
+
+      await this.checkDependencyDeep(
+        transitiveDep,
+        transitiveVersion,
+        pieElementsPath,
+        pieLibPath,
+        cache,
+        blockers,
+        verbose,
+        includeDevDeps,
+        [...depChain, `${depName}@${version}`]
+      );
+    }
+
+    cache.set(depKey, { compatible: !hasBlockers, blockers: [] });
+  }
+
+  private async checkPieLibCompatibility(
+    pkgName: string,
+    pieLibPath: string,
+    verbose: boolean,
+    includeDevDeps: boolean,
+    pieLibCache?: Map<string, { compatible: boolean; blockers: string[] }>
+  ): Promise<{
+    compatible: boolean;
+    blockers: string[];
+  }> {
+    // Check cache first to avoid infinite recursion
+    if (pieLibCache?.has(pkgName)) {
+      const cached = pieLibCache.get(pkgName);
+      if (cached) return cached;
+    }
+
+    const blockers: string[] = [];
+    const pkgPath = join(pieLibPath, 'packages', pkgName, 'package.json');
+    const pkg = await loadPackageJson(pkgPath);
+
+    if (!pkg) {
+      blockers.push(`Package.json not found at ${pkgPath}`);
+      return { compatible: false, blockers };
+    }
+
+    const deps = this.getAllDeps(pkg, includeDevDeps);
+
+    // Check direct dependencies for blockers
+    for (const [dep, version] of Object.entries(deps)) {
+      // Check for direct ESM blockers (non pie-lib packages)
+      if (!dep.startsWith('@pie-lib/')) {
+        const blocker = this.checkEsmBlocker(dep, version);
+        if (blocker) {
+          blockers.push(blocker);
+          if (verbose) {
+            this.logger.info(`    ❌ ${pkgName}: ${blocker}`);
+          }
+        }
+      }
+    }
+
+    // Store preliminary result in cache to prevent infinite recursion
+    const preliminaryResult = {
+      compatible: blockers.length === 0,
+      blockers: [...blockers],
+    };
+    if (pieLibCache) {
+      pieLibCache.set(pkgName, preliminaryResult);
+    }
+
+    // Recursively check transitive pie-lib dependencies
+    const pieLibDeps = this.extractPieLibDeps(deps);
+    for (const transitivePieLib of pieLibDeps) {
+      const transitiveCheck = await this.checkPieLibCompatibility(
+        transitivePieLib,
+        pieLibPath,
+        verbose,
+        includeDevDeps,
+        pieLibCache
+      );
+
+      if (!transitiveCheck.compatible) {
+        for (const blocker of transitiveCheck.blockers) {
+          const transitiveBlocker = `@pie-lib/${transitivePieLib} -> ${blocker}`;
+          blockers.push(transitiveBlocker);
+          if (verbose) {
+            this.logger.info(`    ❌ ${pkgName}: transitive ${transitiveBlocker}`);
+          }
+        }
+      }
+    }
+
+    // Update cache with final result
+    const finalResult = {
+      compatible: blockers.length === 0,
+      blockers,
+    };
+    if (pieLibCache) {
+      pieLibCache.set(pkgName, finalResult);
+    }
+
+    return finalResult;
+  }
+
+  /**
+   * Collect all transitive pie-lib dependencies recursively.
+   * For example, if text-select depends on style-utils, we need style-utils too.
+   */
+  private async collectAllTransitivePieLibDeps(
+    pieLibDeps: string[],
+    pieLibPath: string,
+    includeDevDeps: boolean,
+    visited = new Set<string>()
+  ): Promise<string[]> {
+    const allDeps = new Set<string>(pieLibDeps);
+
+    for (const dep of pieLibDeps) {
+      if (visited.has(dep)) {
+        continue;
+      }
+      visited.add(dep);
+
+      const pkgPath = join(pieLibPath, 'packages', dep, 'package.json');
+      let pkg: PackageJson | null = null;
+      try {
+        pkg = await loadPackageJson(pkgPath);
+      } catch (error) {
+        // Package doesn't exist or can't be read, skip it
+        continue;
+      }
+      if (!pkg) continue;
+
+      const deps = this.getAllDeps(pkg, includeDevDeps);
+      const transitivePieLibDeps = this.extractPieLibDeps(deps);
+
+      // Recursively collect transitive deps
+      const deepDeps = await this.collectAllTransitivePieLibDeps(
+        transitivePieLibDeps,
+        pieLibPath,
+        includeDevDeps,
+        visited
+      );
+
+      for (const transitiveDep of deepDeps) {
+        allDeps.add(transitiveDep);
+      }
+    }
+
+    return Array.from(allDeps);
+  }
+
+  private getAllDeps(pkg: PackageJson, includeDevDeps: boolean): Record<string, string> {
+    const optionalDependencies =
+      (pkg.optionalDependencies as Record<string, string> | undefined) ?? {};
+    return {
+      ...pkg.dependencies,
+      ...optionalDependencies,
+      ...(includeDevDeps ? pkg.devDependencies : {}),
+    };
+  }
+
+  private extractPieLibDeps(deps: Record<string, string>): string[] {
+    return Object.keys(deps)
+      .filter((dep) => dep.startsWith('@pie-lib/'))
+      .map((dep) => dep.replace('@pie-lib/', ''));
+  }
+
+  private extractPieElementDeps(deps: Record<string, string>): string[] {
+    return Object.keys(deps)
+      .filter((dep) => dep.startsWith('@pie-element/'))
+      .map((dep) => dep.replace('@pie-element/', ''));
+  }
+
+  private checkEsmBlocker(dep: string, version: string): string | null {
+    const depVersion = `${dep}@${version}`;
+
+    for (const blocker of ESM_BLOCKERS) {
+      if (blocker.pattern.test(depVersion) || blocker.pattern.test(dep)) {
+        return `${dep}@${version} - ${blocker.reason}`;
+      }
+    }
+
+    return null;
+  }
+
+  private async validateEsmPlayerCompatibility(
+    elementName: string,
+    pieElementsPath: string,
+    verbose: boolean
+  ): Promise<EsmValidationResult> {
+    const blockers: string[] = [];
+    const warnings: string[] = [];
+
+    const elementPath = join(pieElementsPath, 'packages', elementName, 'package.json');
+    const pkg = await loadPackageJson(elementPath);
+
+    if (!pkg) {
+      blockers.push(`Package.json not found at ${elementPath}`);
+      return {
+        compatible: false,
+        packageJson: {
+          hasTypeModule: false,
+          hasExportsField: false,
+          hasMainExport: false,
+          hasControllerExport: false,
+          sideEffectsFree: false,
+          mainExportIsEsm: false,
+          controllerExportIsEsm: false,
+        },
+        blockers,
+        warnings,
+      };
+    }
+
+    // Check 1: type: "module"
+    const hasTypeModule = pkg.type === 'module';
+    if (!hasTypeModule) {
+      blockers.push('Missing "type": "module" in package.json');
+    }
+
+    // Check 2: exports field exists
+    const hasExportsField = !!pkg.exports;
+    if (!hasExportsField) {
+      blockers.push('Missing "exports" field in package.json');
+    }
+
+    // Check 3: main export (".")
+    const exportsObj = pkg.exports as Record<string, unknown> | undefined;
+    const mainExport = exportsObj?.['.'];
+    const hasMainExport = !!mainExport;
+    if (!hasMainExport && hasExportsField) {
+      blockers.push('Missing "." export in package.json exports field');
+    }
+
+    // Check 4: controller export ("./controller")
+    const controllerExport = exportsObj?.['./controller'];
+    const hasControllerExport = !!controllerExport;
+    if (!hasControllerExport && hasExportsField) {
+      warnings.push('Missing "./controller" export - ESM player needs controller subpath');
+    }
+
+    // Check 5: sideEffects
+    const sideEffectsFree = pkg.sideEffects === false;
+    if (!sideEffectsFree) {
+      warnings.push('Consider adding "sideEffects": false for better tree-shaking');
+    }
+
+    // Check 6: main export points to .js file
+    let mainExportIsEsm = false;
+    if (mainExport) {
+      const exportObj = mainExport as Record<string, unknown> | string;
+      const mainPath =
+        typeof exportObj === 'string'
+          ? exportObj
+          : (exportObj.import as string | undefined) || (exportObj.default as string | undefined);
+      mainExportIsEsm = typeof mainPath === 'string' && mainPath.endsWith('.js');
+      if (!mainExportIsEsm) {
+        blockers.push(`Main export must point to .js file (ESM), got: ${mainPath}`);
+      }
+    }
+
+    // Check 7: controller export points to .js file
+    let controllerExportIsEsm = false;
+    if (controllerExport) {
+      const exportObj = controllerExport as Record<string, unknown> | string;
+      const controllerPath =
+        typeof exportObj === 'string'
+          ? exportObj
+          : (exportObj.import as string | undefined) || (exportObj.default as string | undefined);
+      controllerExportIsEsm = typeof controllerPath === 'string' && controllerPath.endsWith('.js');
+      if (!controllerExportIsEsm) {
+        warnings.push(`Controller export should point to .js file (ESM), got: ${controllerPath}`);
+      }
+    }
+
+    const validation: EsmPackageValidation = {
+      hasTypeModule,
+      hasExportsField,
+      hasMainExport,
+      hasControllerExport,
+      sideEffectsFree,
+      mainExportIsEsm,
+      controllerExportIsEsm,
+    };
+
+    const compatible = blockers.length === 0;
+
+    if (verbose) {
+      if (compatible) {
+        this.logger.info(`  ✅ ${elementName}: ESM player ready`);
+      } else {
+        this.logger.info(`  ❌ ${elementName}: Not ESM player ready`);
+        for (const blocker of blockers) {
+          this.logger.info(`     - ${blocker}`);
+        }
+      }
+    }
+
+    return {
+      compatible,
+      packageJson: validation,
+      blockers,
+      warnings,
+    };
+  }
+
+  private printReport(report: CompatibilityReport, outputPath: string): void {
+    const verbose = this.logger.isVerbose();
+
+    if (verbose) {
+      this.log(`\n${'='.repeat(70)}`);
+      this.log('📊 ESM COMPATIBILITY REPORT');
+      this.log('='.repeat(70));
+      this.log('\n📦 Elements:');
+      this.log(`   Total:              ${report.summary.totalElements}`);
+      this.log(
+        `   CommonJS-free:      ${report.summary.compatibleElements} ✅  (no CommonJS deps)`
+      );
+      if (report.esmPlayerValidationEnabled) {
+        this.log(
+          `   ESM player ready:   ${report.summary.esmPlayerReady} ✅  (package.json exports)`
+        );
+      } else {
+        this.log('   ESM player ready:   n/a (validation disabled)');
+      }
+
+      if (report.esmRuntimeValidationEnabled) {
+        const runtimeReady = report.summary.esmRuntimeReady ?? 0;
+        this.log(`   Runtime ready:      ${runtimeReady} ✅  (CDN probe: fetch + parse)`);
+      } else {
+        this.log('   Runtime ready:      n/a (runtime probes disabled)');
+      }
+      this.log(`   Blocked:            ${report.summary.blockedElements} ❌`);
+
+      this.log('\n📚 PIE Lib Packages:');
+      this.log(`   Total:      ${report.summary.totalPieLibPackages}`);
+      this.log(`   Compatible: ${report.summary.compatiblePieLibPackages} ✅`);
+      this.log(
+        `   Blocked:    ${report.summary.totalPieLibPackages - report.summary.compatiblePieLibPackages} ❌`
+      );
+
+      if (report.esmPlayerValidationEnabled) {
+        // ESM player ready elements (best category)
+        if (report.esmPlayerReady.length > 0) {
+          this.log(`\n✅ ESM Player Ready (${report.esmPlayerReady.length}):`);
+          for (const element of report.esmPlayerReady.sort()) {
+            const validation = report.esmValidation[element];
+            const deps = report.elementDetails[element]?.pieLibDeps || [];
+            this.log(`   • ${element}`);
+            this.log(`     - type: module ${validation.packageJson.hasTypeModule ? '✅' : '❌'}`);
+            this.log(`     - exports: . ${validation.packageJson.hasMainExport ? '✅' : '❌'}`);
+            this.log(
+              `     - exports: ./controller ${validation.packageJson.hasControllerExport ? '✅' : '❌'}`
+            );
+            this.log(`     - deps: ${deps.length > 0 ? deps.join(', ') : 'none'}`);
+
+            if (report.esmRuntimeValidationEnabled && report.esmRuntimeValidation?.[element]) {
+              const r = report.esmRuntimeValidation[element];
+              this.log(
+                `     - runtime probe: ${r.compatible ? '✅' : '❌'} (${r.cdnBaseUrl}, entry:${r.entryOk ? 'ok' : 'bad'}, controller:${r.controllerOk ? 'ok' : 'bad'})`
+              );
+              if (!r.compatible && r.errors?.length) {
+                this.log(`       - ${r.errors[0]}`);
+              }
+            }
+          }
+        }
+
+        // CommonJS-free but not ESM player ready
+        const commonJsFreeNotEsmReady = report.elements.filter(
+          (element) => !report.esmPlayerReady.includes(element)
+        );
+
+        if (commonJsFreeNotEsmReady.length > 0) {
+          this.log(
+            `\n⚠️  CommonJS-free but not ESM Player Ready (${commonJsFreeNotEsmReady.length}):`
+          );
+          for (const element of commonJsFreeNotEsmReady.sort()) {
+            const validation = report.esmValidation[element];
+            this.log(`   • ${element}`);
+
+            if (!validation.packageJson.hasTypeModule) {
+              this.log(`     ❌ Missing "type": "module"`);
+            }
+            if (!validation.packageJson.hasExportsField) {
+              this.log(`     ❌ Missing "exports" field`);
+            }
+            if (!validation.packageJson.hasMainExport) {
+              this.log(`     ❌ Missing "." export`);
+            }
+            if (!validation.packageJson.hasControllerExport) {
+              this.log(`     ❌ Missing "./controller" export`);
+            }
+            if (!validation.packageJson.mainExportIsEsm) {
+              this.log(`     ❌ Main export not ESM (.js)`);
+            }
+
+            // Show warnings
+            for (const warning of validation.warnings) {
+              this.log(`     ⚠️  ${warning}`);
+            }
+          }
+        }
+      }
+
+      if (Object.keys(report.blockedElements).length > 0) {
+        this.log(`\n❌ Blocked Elements (${Object.keys(report.blockedElements).length}):`);
+        for (const [element, blockers] of Object.entries(report.blockedElements).sort()) {
+          this.log(`   • ${element}:`);
+          for (const blocker of blockers) {
+            this.log(`     - ${blocker}`);
+          }
+        }
+      }
+
+      if (report.pieLibPackages.length > 0) {
+        this.log(`\n📚 Compatible PIE Lib Packages (${report.pieLibPackages.length}):`);
+        for (const pkg of report.pieLibPackages.sort()) {
+          const usedBy = report.pieLibDetails[pkg]?.usedBy || [];
+          this.log(`   • ${pkg} (used by: ${usedBy.join(', ')})`);
+        }
+      }
+
+      const blockedPieLib = Object.entries(report.pieLibDetails)
+        .filter(([_, details]) => !details.compatible)
+        .sort();
+
+      if (blockedPieLib.length > 0) {
+        this.log(`\n❌ Blocked PIE Lib Packages (${blockedPieLib.length}):`);
+        for (const [pkg, details] of blockedPieLib) {
+          this.log(`   • ${pkg} (needed by: ${details.usedBy.join(', ')}):`);
+          for (const blocker of details.blockers) {
+            this.log(`     - ${blocker}`);
+          }
+        }
+      }
+
+      this.printNotReadyActionReport(report);
+
+      this.log(`\n${'='.repeat(70)}`);
+      this.log(`\n💾 Report saved to: ${outputPath}`);
+      this.log('\n💡 Next steps:');
+      this.log('   1. Review the compatibility report above');
+      this.log('   2. Run sync: bun run upstream:sync');
+      this.log('   3. The sync will automatically use the ESM-compatible list\n');
+    } else {
+      // Non-verbose: just show where report was saved
+      this.log(`\n💾 Report saved to: ${outputPath}`);
+    }
+  }
+
+  private printNotReadyActionReport(report: CompatibilityReport): void {
+    const allElements = Object.keys(report.elementDetails).sort();
+    const blockedElements = allElements.filter((e) => !report.elementDetails[e]?.compatible);
+    const commonJsFreeNotEsmReady = report.esmPlayerValidationEnabled
+      ? report.elements.filter((e) => !report.esmPlayerReady.includes(e))
+      : [];
+    const runtimeNotReady =
+      report.esmRuntimeValidationEnabled && report.esmRuntimeValidation
+        ? Object.entries(report.esmRuntimeValidation)
+            .filter(([_, r]) => !r.compatible)
+            .map(([e]) => e)
+        : [];
+
+    const blockedPieLib = Object.entries(report.pieLibDetails)
+      .filter(([_, details]) => !details.compatible)
+      .sort();
+
+    const hasAnyNotReady =
+      blockedElements.length > 0 ||
+      commonJsFreeNotEsmReady.length > 0 ||
+      runtimeNotReady.length > 0 ||
+      blockedPieLib.length > 0;
+
+    if (!hasAnyNotReady) return;
+
+    this.log('\n🚧 Not ESM-ready yet (action items for upstream maintainers)');
+    this.log(
+      '   Goal: “deploy package + ESM player can load entry + controller (and transitives)”\n'
+    );
+
+    if (blockedElements.length > 0) {
+      this.log(`   ❌ CommonJS blockers (${blockedElements.length}):`);
+      this.log(
+        '   Fix: remove/upgrade/replace the listed CommonJS-only deps (direct or via @pie-lib/*).'
+      );
+      for (const element of blockedElements) {
+        const blockers =
+          report.elementDetails[element]?.blockers ?? report.blockedElements[element] ?? [];
+        this.log(`\n   • ${element}`);
+        for (const blocker of blockers.slice(0, 5)) {
+          this.log(`     - ${blocker}`);
+        }
+        if (blockers.length > 5) {
+          this.log(`     - …and ${blockers.length - 5} more`);
+        }
+        this.log('     What to do:');
+        this.log(
+          '       - Upgrade the dependency to a version that provides ESM + proper "exports"'
+        );
+        this.log(
+          '       - If no ESM exists, replace the dependency or move it behind build-time code (not runtime)'
+        );
+      }
+      this.log('');
+    }
+
+    if (report.esmPlayerValidationEnabled && commonJsFreeNotEsmReady.length > 0) {
+      this.log(`   ⚠️  Package metadata / exports issues (${commonJsFreeNotEsmReady.length}):`);
+      this.log(
+        '   Fix: make package.json ESM-friendly so an ESM loader can resolve `@pie-element/<name>` + `/controller`.\n'
+      );
+
+      for (const element of commonJsFreeNotEsmReady.sort()) {
+        const validation = report.esmValidation[element];
+        if (!validation) continue;
+
+        const pj = validation.packageJson;
+        this.log(`   • ${element}`);
+
+        const issues: string[] = [];
+        const fixes: string[] = [];
+
+        if (!pj.hasTypeModule) {
+          issues.push('Missing `"type": "module"`');
+          fixes.push(
+            'Add `"type": "module"` (or use `.mjs` consistently) so Node/bundlers treat output as ESM.'
+          );
+        }
+        if (!pj.hasExportsField) {
+          issues.push('Missing `"exports"`');
+          fixes.push(
+            'Add `"exports"` with `"."` (entry) and `"./controller"` (controller) subpaths pointing at `dist/*`.'
+          );
+        }
+        if (pj.hasExportsField && !pj.hasMainExport) {
+          issues.push('Missing `"exports"."."`');
+          fixes.push('Add `"exports": { ".": { "default": "./dist/index.js" } }` (path may vary).');
+        }
+        if (!pj.hasControllerExport) {
+          issues.push('Missing `"exports"."./controller"`');
+          fixes.push(
+            'Add `"./controller": { "default": "./dist/controller/index.js" }` when a controller exists.'
+          );
+        }
+        if (!pj.mainExportIsEsm) {
+          issues.push('Main export does not point at a `.js` ESM build');
+          fixes.push(
+            'Ensure the published entry is transpiled ESM JS (no TS, no JSX) and the export points to it.'
+          );
+        }
+        if (pj.hasControllerExport && !pj.controllerExportIsEsm) {
+          issues.push('Controller export does not point at a `.js` ESM build');
+          fixes.push(
+            'Ensure the published controller is transpiled ESM JS (no TS, no JSX) and the export points to it.'
+          );
+        }
+
+        for (const issue of issues.slice(0, 6)) {
+          this.log(`     - ${issue}`);
+        }
+        if (validation.blockers.length > 0) {
+          this.log(`     - Details: ${validation.blockers[0]}`);
+        }
+        if (validation.warnings.length > 0) {
+          this.log(`     - Warning: ${validation.warnings[0]}`);
+        }
+        this.log('     What to do:');
+        for (const fix of fixes.slice(0, 4)) {
+          this.log(`       - ${fix}`);
+        }
+        this.log('');
+      }
+    }
+
+    if (
+      report.esmRuntimeValidationEnabled &&
+      report.esmRuntimeValidation &&
+      runtimeNotReady.length > 0
+    ) {
+      this.log(`   ❌ Runtime probe failures (${runtimeNotReady.length}):`);
+      this.log(
+        '   Fix: make sure the published JS parses as ESM and all transitives resolve in production-like loading.\n'
+      );
+
+      for (const element of runtimeNotReady.sort()) {
+        const r = report.esmRuntimeValidation[element];
+        if (!r) continue;
+
+        this.log(`   • ${element} (CDN: ${r.cdnBaseUrl}, mode: ${r.probeMode ?? 'shallow'})`);
+        if (r.firstFailingUrl) this.log(`     - First failing URL: ${r.firstFailingUrl}`);
+        const firstErr = r.errors?.[0];
+        if (firstErr) this.log(`     - Error: ${firstErr}`);
+
+        const suggestions = this.suggestionsFromRuntimeError(firstErr);
+        if (suggestions.length > 0) {
+          this.log('     What to do:');
+          for (const s of suggestions) this.log(`       - ${s}`);
+        }
+        this.log('');
+      }
+    }
+
+    if (blockedPieLib.length > 0) {
+      this.log(`   ❌ PIE lib packages blocking ESM (${blockedPieLib.length}):`);
+      this.log('   Fix: these must become ESM-compatible because elements import them.\n');
+      for (const [pkg, details] of blockedPieLib) {
+        this.log(`   • @pie-lib/${pkg} (used by: ${details.usedBy.join(', ')})`);
+        for (const blocker of details.blockers.slice(0, 5)) {
+          this.log(`     - ${blocker}`);
+        }
+        if (details.blockers.length > 5) {
+          this.log(`     - …and ${details.blockers.length - 5} more`);
+        }
+      }
+      this.log('');
+    }
+  }
+
+  private suggestionsFromRuntimeError(err: string | undefined): string[] {
+    if (!err) {
+      return [
+        'Confirm the published entry and controller URLs return JavaScript (not HTML/404) and parse as ESM.',
+        'Re-run with --verbose to see the exact failing URL + first error.',
+      ];
+    }
+
+    const e = err.toLowerCase();
+
+    if (
+      e.includes('jsx syntax extension is not currently enabled') ||
+      e.includes('unexpected token <')
+    ) {
+      return [
+        'Your published output likely contains raw JSX; transpile JSX away during build (do not ship JSX in `.js/.mjs`).',
+        'Verify `dist/` contains plain JS and that `package.json` exports point at those `dist/` files.',
+      ];
+    }
+
+    if (e.includes('missing') && e.includes('specifier') && e.includes('exports')) {
+      return [
+        'A dependency is deep-importing a path that is not exposed via `"exports"`; upgrade/replace that dependency or avoid that deep import.',
+        'If this is a PIE package, ensure its `"exports"` explicitly lists the needed subpaths.',
+      ];
+    }
+
+    if (e.includes('could not resolve') || e.includes('not found') || e.includes('404')) {
+      return [
+        'Ensure the entry/controller paths you publish actually exist on the CDN (and match `package.json` exports).',
+        'If the controller exists, publish it as a subpath export (e.g. `./controller`) and ship the referenced `dist/` files.',
+      ];
+    }
+
+    if (
+      e.includes('commonjs') ||
+      e.includes('require is not defined') ||
+      e.includes('module is not defined')
+    ) {
+      return [
+        'A transitive dependency is CommonJS-only; upgrade/replace it with an ESM-capable version, or ship a pre-bundled ESM build.',
+      ];
+    }
+
+    return [
+      'Inspect the first failing URL and error; fix whichever dependency/output is not valid ESM.',
+      'Re-run with --verbose and (if needed) increase --runtime-max-depth / --runtime-max-modules to reproduce reliably.',
+    ];
+  }
+}