@multiplatform.one/config 6.0.0

package/src/vite.ts

@@ -0,0 +1,623 @@
+import fs from "node:fs";
+import path from "node:path";
+import { lookupTamaguiModules, resolveConfig } from "@multiplatform.one/utils/dev";
+import { discoverPublicPackageRoots } from "./workspacePublicPackages.js";
+import { tamaguiPlugin } from "@tamagui/vite-plugin";
+import dotenv from "dotenv";
+import type { Plugin, UserConfig } from "vite";
+import createExternal from "vite-plugin-external";
+import i18nextLoader from "vite-plugin-i18next-loader";
+
+export interface CreateViteConfigOptions {
+  /**
+   * Absolute path to the project root (directory containing .env files).
+   * Defaults to looking up the git root.
+   */
+  projectRoot?: string;
+
+  /**
+   * Public config keys to expose via VITE_MP_CONFIG.
+   * These are typically the `public` keys from features/config.json.
+   */
+  publicConfigKeys?: string[];
+
+  /**
+   * Enable Tamagui plugin. Defaults to true.
+   */
+  tamagui?:
+    | boolean
+    | {
+        /**
+         * Tamagui components to include.
+         * Defaults to looking up tamaguiModules from package.json files.
+         */
+        components?: string[];
+
+        /**
+         * Path to the Tamagui config file.
+         * Defaults to "./config/tamagui.config.ts".
+         */
+        config?: string;
+
+        /**
+         * Path to output CSS. Defaults to "./tamagui.css".
+         */
+        outputCSS?: string;
+      };
+
+  /**
+   * Enable i18next loader plugin. Defaults to false.
+   */
+  i18n?:
+    | boolean
+    | {
+        /**
+         * Paths to scan for translation files.
+         * Defaults to ["../../features/i18n"].
+         */
+        paths?: string[];
+
+        /**
+         * How to resolve namespaces. Defaults to "basename".
+         */
+        namespaceResolution?: string;
+      };
+
+  /**
+   * Enable One framework plugin. Defaults to false.
+   * When true, uses sensible defaults for router, web, react, and native.
+   */
+  one?:
+    | boolean
+    | {
+        router?: { root?: string };
+        web?: { deploy?: string; defaultRenderMode?: string };
+        react?: { compiler?: boolean };
+        native?: { key?: string };
+        deps?: Record<string, boolean>;
+      };
+
+  /**
+   * SSR configuration. Defaults to reasonable values when One is enabled.
+   */
+  ssr?: UserConfig["ssr"];
+
+  /**
+   * Server configuration. Merged with defaults.
+   */
+  server?: UserConfig["server"];
+
+  /**
+   * Additional Vite plugins to include.
+   */
+  plugins?: UserConfig["plugins"];
+
+  /**
+   * Externalize react-router-dom. Defaults to true when One is enabled.
+   */
+  externalReactRouter?: boolean;
+
+  /**
+   * Additional dependency optimizations for SSR.
+   */
+  ssrDeps?: {
+    include?: string[];
+    exclude?: string[];
+    external?: string[];
+  };
+
+  /**
+   * Entry files for Vite's native SSR dep scanner.
+   * Vite follows actual import statements from these files to determine what
+   * needs pre-bundling — much more accurate than walking package.json dep trees.
+   * Defaults to ["routes/**\/*.{ts,tsx}"] for One framework apps.
+   * Only used when `one` is enabled.
+   */
+  ssrEntries?: string[];
+}
+
+/**
+ * Creates a shared Vite configuration for multiplatform.one apps.
+ *
+ * This abstracts away the boilerplate that's typically duplicated across
+ * app vite.config.ts files, including Tamagui plugin setup, i18n,
+ * env variable loading, SSR configuration, and One framework integration.
+ *
+ * @example
+ * ```ts
+ * // apps/one/vite.config.ts
+ * import { createViteConfig } from "@multiplatform.one/config/vite";
+ * import { public as publicConfigKeys } from "../../features/config.json";
+ *
+ * export default createViteConfig({
+ *   publicConfigKeys,
+ *   one: { web: { deploy: "node", defaultRenderMode: "ssr" } },
+ *   tamagui: { config: "./config/tamagui.config.ts" },
+ *   i18n: { paths: ["../../features/i18n"] },
+ * });
+ * ```
+ */
+export function createViteConfig(options: CreateViteConfigOptions = {}): UserConfig {
+  const {
+    projectRoot: _projectRoot,
+    publicConfigKeys = [],
+    tamagui = true,
+    i18n = false,
+    one = false,
+    ssr,
+    server,
+    plugins: extraPlugins = [],
+    externalReactRouter,
+    ssrDeps,
+    ssrEntries,
+  } = options;
+
+  const projectRoot = _projectRoot || findProjectRoot();
+
+  // Load env from project root
+  dotenv.config({ path: path.resolve(projectRoot, ".env") });
+  if (publicConfigKeys.length > 0) {
+    process.env.VITE_MP_CONFIG = JSON.stringify(resolveConfig(publicConfigKeys));
+  }
+
+  const vitePlugins: UserConfig["plugins"] = [];
+  vitePlugins.push(preferBuiltWorkspaceEntryPlugin());
+
+  if (one) {
+    // One plugin must be added by the consumer in their extraPlugins.
+    // Alias react-native to react-native-web in SSR so Rolldown never parses
+    // react-native/index.js (which contains Flow-only syntax).
+    vitePlugins.push(ssrReactNativeAliasPlugin());
+    vitePlugins.push(clientBrokenEsmPlugin());
+    // Register a native-only resolveId plugin through vxrn's __vxrnAddNativePlugins
+    // hook (consumed in vxrn's getNativePlugins). vxrn's native rolldown resolver
+    // does NOT honor engine.io-client's `browser` field, so its Node `.node`
+    // transports (ws + xmlhttprequest-ssl) leak into Hermes and won't even compile.
+    // This re-asserts the package's own browser redirect (-> browser transports that
+    // use RN's global WebSocket/XMLHttpRequest) with NO node_modules patch.
+    registerNativeEngineIoBrowserTransports();
+    // preferBuiltWorkspaceEntryPlugin (web-only) hard-resolves every workspace
+    // package to its `dist/esm/index.mjs` (WEB build), and that resolution reaches
+    // the native graph too — pinning the whole @multiplatform.one/* chain to web
+    // (dragging @tiptap/prosemirror/html5-qrcode/etc into Hermes). This native-only
+    // resolveId redirects each workspace web entry to its `dist/esm/index.native.js`
+    // sibling so native gets the react-native build (the wrappers' native variants).
+    registerNativeWorkspaceEntries();
+  }
+
+  // Tamagui plugin
+  if (tamagui) {
+    const tamaguiOpts = typeof tamagui === "object" ? tamagui : {};
+    vitePlugins.push(
+      tamaguiPlugin({
+        components: tamaguiOpts.components || lookupTamaguiModules([process.cwd()]),
+        config: tamaguiOpts.config || "./config/tamagui.config.ts",
+        outputCSS: tamaguiOpts.outputCSS || "./public/tamagui.css",
+        // Prevents the config file watcher from re-evaluating the Tamagui
+        // config in the main process when the Piscina worker writes changes
+        // to .tamagui/. Without this, the watcher triggers bundleConfig →
+        // import() → createTamagui() on a raw @tamagui/web instance that
+        // conflicts with the SSR module runner's pre-bundled instance.
+        // See also: patches/@tamagui__static (forces CJS config bundles in
+        // the worker to avoid ESM/CJS dual-instance globalThis conflicts).
+        disableWatchTamaguiConfig: true,
+      }),
+    );
+  }
+
+  // i18n plugin
+  if (i18n) {
+    const i18nOpts = typeof i18n === "object" ? i18n : {};
+    vitePlugins.push(
+      i18nextLoader({
+        paths: i18nOpts.paths || ["../../features/i18n"],
+        namespaceResolution: (i18nOpts.namespaceResolution as any) || "basename",
+      }),
+    );
+  }
+
+  // Externalize react-router-dom (needed for One framework)
+  if (externalReactRouter !== false && one) {
+    vitePlugins.push(
+      createExternal({
+        externals: {
+          "react-router-dom": {} as any,
+        },
+      }),
+    );
+  }
+
+  // Merge extra plugins
+  vitePlugins.push(...(extraPlugins as any[]));
+
+  // SSR defaults for One framework
+  const defaultSsr: UserConfig["ssr"] = one
+    ? ({
+        noExternal: true,
+        optimizeDeps: {
+          entries: ssrEntries ?? ["routes/**/*.{ts,tsx}"],
+          include: [
+            // @tamagui/core holds a global config singleton. It must be
+            // pre-bundled as a single chunk so all SSR code shares one instance.
+            // If loaded via two different paths (optimizer + module runner),
+            // TamaguiProvider sets config on one instance but components read
+            // from the other, triggering the "global config fallback" warning.
+            "@tamagui/core",
+            "@tamagui/web",
+            "tamagui",
+            "@tamagui/toast",
+            "@tamagui/linear-gradient",
+            // react-i18next and i18next must be pre-bundled for SSR so they
+            // share the same React instance as react-dom/server. Without
+            // explicit include, the SSR module runner loads react-i18next
+            // directly from node_modules, which imports a raw
+            // node_modules/react/cjs/react.development.js. That raw React
+            // has its dispatcher unset (null), causing "Cannot read properties
+            // of null (reading 'useSyncExternalStore')" during useTranslation.
+            "react-i18next",
+            "i18next",
+            // @tanstack/react-store must be pre-bundled for SSR so it uses the
+            // shared React chunk (react-D-en6o7j.js) instead of loading
+            // use-sync-external-store/shim/with-selector as a CJS external which
+            // internally does require('react') → raw node_modules React →
+            // different instance from react-dom/server → dispatcher null.
+            "@tanstack/react-store",
+            "@tanstack/store",
+            // CJS-only transitive dep of react-i18next (via html-parse-stringify).
+            // Rolldown doesn't pull it into the react-i18next pre-bundle chunk, so
+            // the SSR module runner gets the raw file and fails with
+            // "module is not defined".
+            "void-elements",
+            // use-sync-external-store must share the same React instance as the
+            // SSR renderer. Without bundling it in, the CJS shim does
+            // require('react') at runtime → different node_modules React →
+            // dispatcher null → "Cannot read properties of null (reading
+            // 'useSyncExternalStore')" crash during useTranslation in SSR.
+            "use-sync-external-store",
+            "use-sync-external-store/shim",
+            ...(ssrDeps?.include || []),
+          ],
+          exclude: [
+            "@react-native/assets-registry",
+            "@react-native-community/datetimepicker",
+            "socket.io-client",
+            "engine.io-client",
+            "xmlhttprequest-ssl",
+            // Devtools — never needed in SSR, and their nested deps have
+            // version mismatches (form-core@1.27.7 needs Derived from store).
+            "@tanstack/form-devtools",
+            "@tanstack/react-form-devtools",
+            ...(ssrDeps?.exclude || []),
+          ],
+          rolldownOptions: {
+            // Belt-and-suspenders: force Rolldown to treat these packages as
+            // external at the bundler level, not just via the exclude plugin.
+            // Without this, Rolldown can still inline them as transitive deps
+            // of other pre-bundled packages, causing MISSING_EXPORT errors.
+            external: [
+              "@tanstack/form-devtools",
+              "@tanstack/react-form-devtools",
+              ...(ssrDeps?.external || []),
+            ],
+            // Shim any remaining missing exports instead of hard-failing.
+            shimMissingExports: true,
+          },
+        },
+        external: [
+          "loglevel",
+          "@react-native/assets-registry",
+          "@react-native-community/datetimepicker",
+          "socket.io-client",
+          "engine.io-client",
+          "xmlhttprequest-ssl",
+          "@tanstack/form-devtools",
+          "@tanstack/react-form-devtools",
+          ...(ssrDeps?.external || []),
+          // better-auth pulls @opentelemetry/* (CJS) which fails in the ESM
+          // SSR module runner with "exports is not defined". Externalize so
+          // Node's native CJS loader handles them.
+          "@opentelemetry/semantic-conventions",
+          "@opentelemetry/api",
+          "@opentelemetry/sdk-trace-base",
+          "@opentelemetry/sdk-trace-node",
+        ],
+      } as any)
+    : undefined;
+
+  // Server defaults
+  //
+  // When the One app runs behind Frappe's dev proxy (port 8000 → 3000), the
+  // browser page origin is :8000 but the vxrn HMR WebSocket lives on :3000.
+  // Werkzeug (WSGI) can't proxy WebSocket upgrades, so we tell the HMR client
+  // to connect directly to the One dev server port.
+  //
+  // IMPORTANT: vxrn internally sets `hmr.path = '/__vxrnhmr'`.  We must
+  // include the path here because config merging replaces the entire `hmr`
+  // object (shallow merge at the `server` level).  If vxrn ever changes the
+  // path, update it here too.
+  const onePort = Number(process.env.ONE_PORT) || 3000;
+  const defaultServer: UserConfig["server"] = {
+    allowedHosts: ["localhost", "127.0.0.1", "app.localhost", "app.test"],
+    strictPort: true,
+    watch: {
+      ignored: ["**/src-tauri/**"],
+    },
+    ...(one
+      ? {
+          hmr: {
+            path: "/__vxrnhmr",
+            clientPort: onePort,
+          },
+        }
+      : {}),
+    ...server,
+  };
+
+  return {
+    css: {
+      modules: {
+        localsConvention: "camelCase",
+      },
+    },
+    build: {
+      chunkSizeWarningLimit: 600,
+    },
+    define: {
+      // Build-time flag for Frappe translation backend tree-shaking
+      "process.env.VITE_FRAPPE_ENABLED": JSON.stringify(
+        process.env.VITE_FRAPPE_ENABLED === "true" ? "true" : "false",
+      ),
+    },
+    ssr: ssr || defaultSsr,
+    resolve: {
+      alias: {
+        // Fix tamagui-build outputting `from "react.mjs"` instead of `from "react"`
+        "react.mjs": "react",
+
+        // React 19.1+ ships its own compiler runtime.  The standalone
+        // `react-compiler-runtime` beta package (pulled in by `one`) gets
+        // pre-bundled by Vite with its own React copy, causing a duplicate-
+        // React dispatcher-is-null crash (`useMemoCache`).  Aliasing to
+        // the built-in entry point ensures a single React instance.
+        "react-compiler-runtime": "react/compiler-runtime",
+
+        // use-sync-external-store is marked as SSR-external by the
+        // ssrExternalFix plugin in vite.config.ts, so Node's CJS loader
+        // handles it during SSR (avoiding the "module is not defined" error).
+        // Do NOT alias it here — Vite's prefix-match aliases catch subpaths
+        // like /shim/with-selector.js and /with-selector, rewriting them to
+        // react/with-selector which doesn't exist, crashing dep optimisation.
+      },
+      // @react-navigation/core ships a nested node_modules/react-is (CJS-only).
+      // Deduplication forces the root copy so clientBrokenEsmPlugin's pre-bundle
+      // covers it everywhere.
+      dedupe: ["react-is"],
+    },
+    server: defaultServer,
+    envPrefix: ["VITE_", "TAURI_ENV_"],
+    plugins: vitePlugins,
+  } satisfies UserConfig;
+}
+
+export {
+  discoverPublicPackageRoots,
+  publicPackageViteSourceAliases,
+} from "./workspacePublicPackages.js";
+
+/**
+ * Aliases react-native to react-native-web in the SSR environment.
+ *
+ * @react-navigation/native statically imports react-native, which causes
+ * Rolldown's dep optimizer to load react-native/index.js — a file that contains
+ * Flow-only syntax (`import typeof`, `as Type`) that Rolldown cannot parse.
+ * Aliasing to react-native-web redirects those imports to the web-safe shim,
+ * so the real react-native package is never touched during SSR bundling.
+ */
+function ssrReactNativeAliasPlugin(): Plugin {
+  return {
+    name: "multiplatform-ssr-react-native-alias",
+    enforce: "post",
+    configResolved(config) {
+      const ssrEnv = (config as any).environments?.ssr;
+      if (!ssrEnv?.resolve) return;
+      const alias: Array<{ find: string | RegExp; replacement: string }> =
+        ssrEnv.resolve.alias ?? [];
+      if (!alias.some((a: any) => a.find === "react-native")) {
+        alias.push({ find: "react-native", replacement: "react-native-web" });
+      }
+      ssrEnv.resolve.alias = alias;
+    },
+  };
+}
+
+/**
+ * Adds packages that have broken or missing ESM default exports to the client
+ * environments pre-bundle. Rolldown resolves them via their "import" condition
+ * and generates a proper ESM chunk with synthetic interop default export.
+ *
+ * use-latest-callback: type=commonjs, exports.import → esm.mjs, but vxrn's
+ * client conditions (["vxrn-web"]) skip "import" and land on "default" →
+ * lib/src/index.js (CJS, named-only). Pre-bundling forces the import condition.
+ */
+function clientBrokenEsmPlugin(): Plugin {
+  return {
+    name: "multiplatform-client-broken-esm",
+    configResolved(config) {
+      const clientEnv = (config as any).environments?.client;
+      if (!clientEnv?.optimizeDeps) return;
+      const extras = [
+        "use-latest-callback",
+        // CJS packages in vxrn's dedupe list that are not auto-added to the
+        // client environment optimizer, causing "doesn't provide an export
+        // named 'default'" errors when served raw by Vite.
+        "escape-string-regexp",
+        // Pure CJS with no "import" condition — subpath must be pre-bundled
+        // explicitly so named exports (useSyncExternalStoreWithSelector) exist.
+        // Root entry is SSR-external (Node handles it); client needs pre-bundle.
+        "use-sync-external-store/with-selector",
+        // @react-navigation/core ships a nested node_modules/react-is (CJS).
+        // resolve.dedupe forces the root copy to be used; pre-bundling it here
+        // adds ESM interop so named exports like isValidElementType are available.
+        "react-is",
+        // CJS-only packages imported by @react-navigation/* TypeScript source.
+        // When the client loads @react-navigation/* via the "source" condition
+        // (TypeScript), these transitive CJS deps get served raw and lack ESM
+        // named exports. Pre-bundling generates the ESM interop wrappers.
+        "fast-deep-equal",
+        "color",
+        // query-string v7 is CJS-only; imported by @react-navigation/core for URL parsing.
+        "query-string",
+      ];
+      const include: string[] = clientEnv.optimizeDeps.include ?? [];
+      for (const dep of extras) {
+        if (!include.includes(dep)) include.push(dep);
+      }
+      clientEnv.optimizeDeps.include = include;
+    },
+  };
+}
+
+/**
+ * Adds engine.io-client's `browser`-field transport redirect to vxrn's NATIVE
+ * rolldown pipeline via its `globalThis.__vxrnAddNativePlugins` hook.
+ *
+ * socket.io-client -> engine.io-client/index.js statically imports its Node
+ * transports (`./globals.node.js`, `./transports/{websocket,polling-xhr}.node.js`),
+ * which pull `ws` + `xmlhttprequest-ssl` + Node globals. Those `.node` files also
+ * contain raw ESM `import` syntax that Hermes can't even COMPILE, so the native
+ * bundle dies at boot. engine.io's own `package.json` `browser` field already
+ * redirects each `*.node.js` to a browser sibling that uses the global
+ * `WebSocket` / `XMLHttpRequest` React Native provides — but vxrn's native
+ * resolver omits the `browser` aliasField (and its rolldown binding doesn't even
+ * support `aliasFields`). vxrn's native dev engine ignores the Vite config's
+ * `resolve.alias`/`resolveId` too — BUT it DOES read `globalThis.__vxrnAddNativePlugins`
+ * inside `getNativePlugins`, so a `resolveId` registered there runs on native.
+ * This re-asserts the browser redirect with no node_modules patch. Web is
+ * unaffected (engine.io is SSR-externalized and the web client already maps `browser`).
+ */
+function registerNativeEngineIoBrowserTransports(): void {
+  const g = globalThis as unknown as { __vxrnAddNativePlugins?: unknown[] };
+  const name = "vxrn-engineio-browser-transports";
+  g.__vxrnAddNativePlugins = g.__vxrnAddNativePlugins ?? [];
+  if (g.__vxrnAddNativePlugins.some((p) => (p as { name?: string })?.name === name)) return;
+  g.__vxrnAddNativePlugins.push({
+    name,
+    async resolveId(
+      this: { resolve: (id: string, importer: string, opts: { skipSelf: boolean }) => unknown },
+      id: string,
+      importer?: string,
+    ) {
+      if (
+        importer &&
+        /engine\.io-client[\\/]build[\\/]/.test(importer) &&
+        id.endsWith(".node.js")
+      ) {
+        return this.resolve(`${id.slice(0, -".node.js".length)}.js`, importer, { skipSelf: true });
+      }
+      return null;
+    },
+  });
+}
+
+/**
+ * Routes workspace (`@multiplatform.one/*`) packages to their `dist/esm/index.native.js`
+ * build on NATIVE, via vxrn's `globalThis.__vxrnAddNativePlugins` hook.
+ *
+ * Why this is needed: `preferBuiltWorkspaceEntryPlugin` (a Vite plugin, web/SSR only)
+ * hard-resolves every workspace bare specifier to `<root>/dist/esm/index.mjs` — the WEB
+ * build — bypassing the package.json `exports` `react-native` condition. That web
+ * resolution propagates into vxrn's native graph (the native engine receives no Vite
+ * userPlugins, so it cannot be made native-aware there), pinning the entire workspace
+ * chain to web on native and dragging web-only deps (@tiptap, prosemirror, html5-qrcode,
+ * @mixmark-io/domino, …) into Hermes. Each affected package ships a `dist/esm/index.native.js`
+ * (built by tamagui-build, intra-package imports already rewritten to their `.native`
+ * siblings). This resolveId matches both forms — the bare specifier and the already-resolved
+ * `…/dist/esm/index.mjs` path — and redirects to the native sibling when it exists, so the
+ * react-native build wins on native. Web/SSR are unaffected (this plugin runs ONLY on native).
+ */
+function registerNativeWorkspaceEntries(): void {
+  const g = globalThis as unknown as { __vxrnAddNativePlugins?: unknown[] };
+  const name = "vxrn-workspace-native-entries";
+  g.__vxrnAddNativePlugins = g.__vxrnAddNativePlugins ?? [];
+  if (g.__vxrnAddNativePlugins.some((p) => (p as { name?: string })?.name === name)) return;
+  let roots: Map<string, string>;
+  try {
+    roots = discoverPublicPackageRoots(findProjectRoot());
+  } catch {
+    roots = new Map();
+  }
+  g.__vxrnAddNativePlugins.push({
+    name,
+    resolveId(id: string): string | null {
+      // (a) bare workspace specifier (e.g. "@multiplatform.one/rich-text")
+      const root = roots.get(id);
+      if (root) {
+        const nativeEntry = path.join(root, "dist/esm/index.native.js");
+        return fs.existsSync(nativeEntry) ? nativeEntry : null;
+      }
+      // (b) already-resolved web entry "<...>/dist/esm/index.mjs" -> ".native.js" sibling
+      if (id.endsWith("/dist/esm/index.mjs")) {
+        const nativeEntry = `${id.slice(0, -".mjs".length)}.native.js`;
+        if (fs.existsSync(nativeEntry)) return nativeEntry;
+      }
+      return null;
+    },
+  });
+}
+
+function findProjectRoot(): string {
+  try {
+    const { execSync } = require("node:child_process");
+    return execSync("git rev-parse --show-toplevel", { encoding: "utf8" }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+/**
+ * package.json `exports` cannot branch on whether `dist/` exists. For workspace
+ * packages, prefer `dist/esm/index.{mjs,js}` when built; otherwise fall back to
+ * `src/index.ts` so local dev works without a build while published tarballs
+ * still resolve through `exports` to `dist`.
+ */
+function preferBuiltWorkspaceEntryPlugin(): Plugin {
+  const roots = discoverPublicPackageRoots(findProjectRoot());
+
+  return {
+    name: "multiplatform-prefer-built-workspace-main",
+    enforce: "pre",
+    resolveId(id) {
+      const root = roots.get(id);
+      if (!root) return null;
+      const distCandidates = [
+        path.join(root, "dist/esm/index.mjs"),
+        path.join(root, "dist/esm/index.js"),
+      ];
+      for (const file of distCandidates) {
+        if (fs.existsSync(file)) return file;
+      }
+      const srcTs = path.join(root, "src/index.ts");
+      if (fs.existsSync(srcTs)) return srcTs;
+      const srcTsx = path.join(root, "src/index.tsx");
+      if (fs.existsSync(srcTsx)) return srcTsx;
+
+      // Vendored packages (e.g. keycloak-js) have no src/ — resolve via
+      // package.json exports/main so the dep scanner doesn't fail.
+      const pkgJsonPath = path.join(root, "package.json");
+      if (fs.existsSync(pkgJsonPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+          const entry =
+            pkg.exports?.["."]?.import || pkg.exports?.["."]?.default || pkg.main || pkg.module;
+          if (entry) {
+            const resolved = path.resolve(root, entry);
+            if (fs.existsSync(resolved)) return resolved;
+          }
+        } catch {
+          /* ignore */
+        }
+      }
+      return null;
+    },
+  };
+}