@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.41

package/src/services/assets/asset-processing-service/page-package.js

@@ -0,0 +1,80 @@
+function getSuppressedSourceFilepaths(assets) {
+  const suppressed = /* @__PURE__ */ new Set();
+  for (const asset of assets) {
+    if ((asset.packageRole === "page-style" || asset.packageRole === "page-script") && Array.isArray(asset.bundledSourceFilepaths)) {
+      for (const filepath of asset.bundledSourceFilepaths) {
+        suppressed.add(filepath);
+      }
+    }
+  }
+  return suppressed;
+}
+function createPagePackage(assets, options = {}) {
+  const allAssets = [
+    ...assets,
+    ...options.pageBrowserGraph?.entryAssets ?? [],
+    ...options.pageBrowserGraph?.chunkAssets ?? []
+  ];
+  const inlineAssets = [];
+  const separateAssets = [];
+  const dynamicChunks = [];
+  let pageScript;
+  let pageStylesheet;
+  const suppressedSourceFilepaths = getSuppressedSourceFilepaths(allAssets);
+  for (const asset of allAssets) {
+    if (asset.inline) {
+      inlineAssets.push(asset);
+      continue;
+    }
+    if (asset.packageRole === "dynamic-chunk") {
+      dynamicChunks.push(asset);
+      continue;
+    }
+    if (!pageScript && asset.packageRole === "page-script") {
+      pageScript = asset;
+      continue;
+    }
+    if (!pageStylesheet && asset.packageRole === "page-style") {
+      pageStylesheet = asset;
+      continue;
+    }
+    if (asset.packageRole === "keep-separate" || asset.packageRole === "runtime") {
+      separateAssets.push(asset);
+      continue;
+    }
+    if (!pageScript && asset.kind === "script" && !asset.excludeFromHtml) {
+      pageScript = asset;
+      continue;
+    }
+    if (!pageStylesheet && asset.kind === "stylesheet") {
+      pageStylesheet = asset;
+      continue;
+    }
+    separateAssets.push(asset);
+  }
+  return {
+    assets: allAssets,
+    pageBrowserGraph: options.pageBrowserGraph,
+    htmlAssets: allAssets.filter((asset) => shouldIncludeInHtml(asset, suppressedSourceFilepaths)),
+    pageScript,
+    pageStylesheet,
+    inlineAssets,
+    separateAssets,
+    dynamicChunks
+  };
+}
+function shouldIncludeInHtml(asset, suppressedSourceFilepaths) {
+  if (asset.excludeFromHtml) {
+    return false;
+  }
+  if (asset.packageRole === "runtime") {
+    return false;
+  }
+  if (asset.sourceFilepath && suppressedSourceFilepaths.has(asset.sourceFilepath)) {
+    return false;
+  }
+  return true;
+}
+export {
+  createPagePackage
+};

package/src/services/{asset-processing-service → assets/asset-processing-service}/processor.interface.d.ts

@@ -1,5 +1,5 @@
-import type { IHmrManager } from '../../internal-types';
-import type { AssetDefinition, ProcessedAsset } from './assets.types';
+import type { IHmrManager } from '../../../types/internal-types.js';
+import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
 /**
  * Base interface for asset processors.
  * Processors transform asset definitions into processed assets.

package/src/services/{asset-processing-service → assets/asset-processing-service}/processor.registry.d.ts

@@ -1,5 +1,5 @@
-import type { AssetKind, AssetSource } from './assets.types';
-import type { BaseProcessor } from './processors/base/base-processor';
+import type { AssetKind, AssetSource } from './assets.types.js';
+import type { BaseProcessor } from './processors/base/base-processor.js';
 export declare class ProcessorRegistry {
     private processors;
     register(kind: AssetKind, variant: AssetSource, processor: BaseProcessor<any>): void;

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/base/base-processor.d.ts

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../../../../types/internal-types.js';
 import type { BaseAsset, ProcessedAsset } from '../../assets.types.js';
 export declare abstract class BaseProcessor<T extends BaseAsset> {
     protected appConfig: EcoPagesAppConfig;

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/base/base-processor.js

@@ -1,7 +1,8 @@
 import path from "node:path";
-import { RESOLVED_ASSETS_DIR } from "../../../../constants.js";
-import { rapidhash } from "../../../../utils/hash.js";
-import { isDevelopmentRuntime, isProductionRuntime } from "../../../../utils/runtime.js";
+import { RESOLVED_ASSETS_DIR } from "../../../../../config/constants.js";
+import { rapidhash } from "../../../../../utils/hash.js";
+import { isDevelopmentRuntime, isProductionRuntime } from "../../../../../utils/runtime.js";
+import { fileSystem } from "@ecopages/file-system";
 class BaseProcessor {
   appConfig;
   /**
@@ -37,11 +38,16 @@ class BaseProcessor {
   buildCacheKey(identifier, contentHash, dep) {
     const attrsHash = dep.attributes ? this.generateHash(JSON.stringify(dep.attributes)) : "";
     const position = dep.position ?? "";
-    return `${identifier}:${contentHash}:${position}:${attrsHash}`;
+    const packageRole = dep.packageRole ?? "";
+    return `${identifier}:${contentHash}:${position}:${attrsHash}:${packageRole}`;
   }
   getOrProcess(cacheKey, processFn) {
     if (this.hasCacheFile(cacheKey)) {
-      return Promise.resolve(this.getCacheFile(cacheKey));
+      const cached = this.getCacheFile(cacheKey);
+      if (!cached.filepath || fileSystem.exists(cached.filepath)) {
+        return Promise.resolve(cached);
+      }
+      this.cache.delete(cacheKey);
     }
     const result = processFn();
     if (result instanceof Promise) {

package/src/services/assets/asset-processing-service/processors/base/base-script-processor.d.ts

@@ -0,0 +1,22 @@
+import type { EcoPagesAppConfig } from '../../../../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../../../../build/build-types.js';
+import type { ScriptAsset } from '../../assets.types.js';
+import { BaseProcessor } from './base-processor.js';
+import { type BrowserBundleGroupedEntry } from '../../../browser-bundle.service.js';
+export declare abstract class BaseScriptProcessor<T extends ScriptAsset> extends BaseProcessor<T> {
+    private readonly browserBundleService;
+    constructor({ appConfig }: {
+        appConfig: EcoPagesAppConfig;
+    });
+    protected shouldBundle(dep: T): boolean;
+    protected getBundlerOptions(dep: T): Record<string, any>;
+    protected collectBuildPlugins(excludePluginNames?: string[]): EcoBuildPlugin[];
+    protected bundleScript({ entrypoint, outdir, excludeAppBuildPlugins, plugins: additionalPlugins, ...rest }: {
+        entrypoint: string;
+        outdir: string;
+    } & ScriptAsset['bundleOptions']): Promise<string>;
+    protected bundleScripts({ entries, outdir, excludeAppBuildPlugins, plugins: additionalPlugins, ...rest }: {
+        entries: BrowserBundleGroupedEntry[];
+        outdir: string;
+    } & ScriptAsset['bundleOptions']): Promise<Map<string, string>>;
+}

package/src/services/assets/asset-processing-service/processors/base/base-script-processor.js

@@ -0,0 +1,136 @@
+import { appLogger } from "../../../../../global/app-logger.js";
+import { getAppBrowserBuildPlugins } from "../../../../../build/build-adapter.js";
+import { fileSystem } from "@ecopages/file-system";
+import path from "node:path";
+import { BaseProcessor } from "./base-processor.js";
+import { BrowserBundleService } from "../../../browser-bundle.service.js";
+class BaseScriptProcessor extends BaseProcessor {
+  browserBundleService;
+  constructor({ appConfig }) {
+    super({ appConfig });
+    this.browserBundleService = new BrowserBundleService(appConfig);
+  }
+  shouldBundle(dep) {
+    return dep.bundle !== false;
+  }
+  getBundlerOptions(dep) {
+    if (dep.packageRole === "page-script" && dep.bundleOptions?.splitting === void 0) {
+      return {
+        ...dep.bundleOptions,
+        splitting: false
+      };
+    }
+    return dep.bundleOptions || {};
+  }
+  collectBuildPlugins(excludePluginNames) {
+    const buildPlugins = getAppBrowserBuildPlugins(this.appConfig);
+    if (!excludePluginNames || excludePluginNames.length === 0) {
+      return buildPlugins;
+    }
+    const excluded = new Set(excludePluginNames);
+    return buildPlugins.filter((plugin) => !excluded.has(plugin.name));
+  }
+  async bundleScript({
+    entrypoint,
+    outdir,
+    excludeAppBuildPlugins,
+    plugins: additionalPlugins,
+    ...rest
+  }) {
+    const buildPlugins = this.collectBuildPlugins(excludeAppBuildPlugins);
+    const allPlugins = additionalPlugins ? [...additionalPlugins, ...buildPlugins] : buildPlugins;
+    const buildResult = await this.browserBundleService.bundle({
+      profile: "browser-script",
+      entrypoints: [entrypoint],
+      outdir,
+      root: this.appConfig.rootDir,
+      excludeAppBuildPlugins,
+      splitting: true,
+      naming: "[name]-[hash].[ext]",
+      plugins: allPlugins,
+      ...rest
+    });
+    if (!buildResult.success) {
+      for (const log of buildResult.logs) {
+        appLogger.debug(log.message, log);
+      }
+    }
+    const entryBaseName = path.parse(entrypoint).name;
+    const entryOutput = buildResult.outputs.map((output) => output.path).find((outputPath) => path.basename(outputPath) === `${entryBaseName}.js`);
+    if (entryOutput) {
+      return entryOutput;
+    }
+    const nonVendorOutput = buildResult.outputs.map((output) => output.path).find((outputPath) => !path.basename(outputPath).startsWith("vendors"));
+    if (nonVendorOutput) {
+      return nonVendorOutput;
+    }
+    const primaryOutput = buildResult.outputs[0]?.path;
+    if (primaryOutput) {
+      return primaryOutput;
+    }
+    const namedFallbackOutput = path.join(outdir, `${entryBaseName}.js`);
+    if (fileSystem.exists(namedFallbackOutput)) {
+      return namedFallbackOutput;
+    }
+    const fallbackOutput = path.join(outdir, "entry_0.js");
+    if (fileSystem.exists(fallbackOutput)) {
+      return fallbackOutput;
+    }
+    const logMessage = buildResult.logs.map((log) => log.message).join(" | ");
+    throw new Error(`No build output generated for ${entrypoint}${logMessage ? `: ${logMessage}` : ""}`);
+  }
+  async bundleScripts({
+    entries,
+    outdir,
+    excludeAppBuildPlugins,
+    plugins: additionalPlugins,
+    ...rest
+  }) {
+    const buildPlugins = this.collectBuildPlugins(excludeAppBuildPlugins);
+    const allPlugins = additionalPlugins ? [...additionalPlugins, ...buildPlugins] : buildPlugins;
+    const buildResult = await this.browserBundleService.bundleGroupedEntries(entries, {
+      profile: "browser-script",
+      outdir,
+      root: this.appConfig.rootDir,
+      excludeAppBuildPlugins,
+      ...rest,
+      splitting: true,
+      naming: "[name]-[hash].[ext]",
+      plugins: allPlugins
+    });
+    if (!buildResult.success) {
+      for (const log of buildResult.logs) {
+        appLogger.debug(log.message, log);
+      }
+    }
+    const outputs = buildResult.outputs.map((output) => output.path);
+    const entryOutputs = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      const exactOutput = outputs.find((outputPath) => path.basename(outputPath) === `${entry.entryName}.js`);
+      if (exactOutput) {
+        entryOutputs.set(entry.entryName, exactOutput);
+        continue;
+      }
+      const hashedOutput = outputs.find(
+        (outputPath) => path.basename(outputPath).startsWith(`${entry.entryName}-`)
+      );
+      if (hashedOutput) {
+        entryOutputs.set(entry.entryName, hashedOutput);
+        continue;
+      }
+      const fallbackOutput = path.join(outdir, `${entry.entryName}.js`);
+      if (fileSystem.exists(fallbackOutput)) {
+        entryOutputs.set(entry.entryName, fallbackOutput);
+        continue;
+      }
+      const logMessage = buildResult.logs.map((log) => log.message).join(" | ");
+      throw new Error(
+        `No build output generated for grouped entry ${entry.entryName}${logMessage ? `: ${logMessage}` : ""}`
+      );
+    }
+    return entryOutputs;
+  }
+}
+export {
+  BaseScriptProcessor
+};

package/src/services/assets/asset-processing-service/processors/index.d.ts

@@ -0,0 +1,5 @@
+export * from './script/content-script.processor.js';
+export * from './script/file-script.processor.js';
+export * from './script/node-module-script.processor.js';
+export * from './stylesheet/content-stylesheet.processor.js';
+export * from './stylesheet/file-stylesheet.processor.js';

package/src/services/assets/asset-processing-service/processors/index.js

@@ -0,0 +1,5 @@
+export * from "./script/content-script.processor.js";
+export * from "./script/file-script.processor.js";
+export * from "./script/node-module-script.processor.js";
+export * from "./stylesheet/content-stylesheet.processor.js";
+export * from "./stylesheet/file-stylesheet.processor.js";

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/script/content-script.processor.d.ts

@@ -1,5 +1,6 @@
-import type { ContentScriptAsset, ProcessedAsset } from '../../assets.types';
-import { BaseScriptProcessor } from '../base/base-script-processor';
+import type { ContentScriptAsset, ProcessedAsset } from '../../assets.types.js';
+import { BaseScriptProcessor } from '../base/base-script-processor.js';
 export declare class ContentScriptProcessor extends BaseScriptProcessor<ContentScriptAsset> {
+    processGrouped(deps: ContentScriptAsset[]): Promise<ProcessedAsset[]>;
     process(dep: ContentScriptAsset): Promise<ProcessedAsset>;
 }

package/src/services/assets/asset-processing-service/processors/script/content-script.processor.js

@@ -0,0 +1,119 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { BaseScriptProcessor } from "../base/base-script-processor.js";
+class ContentScriptProcessor extends BaseScriptProcessor {
+  async processGrouped(deps) {
+    if (deps.length === 0) {
+      return [];
+    }
+    const shouldBundle = deps.every((dep) => this.shouldBundle(dep));
+    if (!shouldBundle || deps.some((dep) => dep.inline)) {
+      return Promise.all(deps.map((dep) => this.process(dep)));
+    }
+    const tempDir = path.join(
+      this.appConfig.absolutePaths.distDir,
+      `grouped-script-entries-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+    fileSystem.ensureDir(tempDir);
+    try {
+      const tempEntries = deps.map((dep, index) => {
+        const entryName = dep.groupedBundle?.entryName ?? dep.name ?? `grouped-script-${index}`;
+        const tempFilepath = path.join(tempDir, `${entryName}.js`);
+        fileSystem.write(tempFilepath, dep.content);
+        return {
+          dep,
+          entryName,
+          tempFilepath
+        };
+      });
+      const primaryDep = deps[0];
+      const outputPaths = await this.bundleScripts({
+        ...this.getBundlerOptions(primaryDep),
+        entries: tempEntries.map(({ entryName, tempFilepath }) => ({
+          entryName,
+          entrypoint: tempFilepath
+        })),
+        outdir: this.getAssetsDir(),
+        minify: this.isProduction,
+        naming: "[name]-[hash].[ext]"
+      });
+      return tempEntries.map(({ dep, entryName }) => {
+        const bundledFilePath = outputPaths.get(entryName);
+        if (!bundledFilePath) {
+          throw new Error(`Missing grouped bundle output for ${entryName}`);
+        }
+        return {
+          filepath: bundledFilePath,
+          content: dep.inline ? fileSystem.readFileSync(bundledFilePath).toString() : void 0,
+          kind: "script",
+          position: dep.position,
+          attributes: dep.attributes,
+          inline: dep.inline,
+          excludeFromHtml: dep.excludeFromHtml,
+          packageRole: dep.packageRole,
+          groupedBundle: dep.groupedBundle,
+          bundledSourceFilepaths: dep.bundledSourceFilepaths
+        };
+      });
+    } finally {
+      fileSystem.remove(tempDir);
+    }
+  }
+  async process(dep) {
+    const hash = this.generateHash(dep.content);
+    const filename = dep.name ? `${dep.name}.js` : `script-${hash}.js`;
+    const shouldBundle = this.shouldBundle(dep);
+    const filepath = path.join(this.getAssetsDir(), "scripts", filename);
+    if (!shouldBundle) {
+      if (!dep.inline) fileSystem.write(filepath, dep.content);
+      const unbundledProcessedAsset = {
+        filepath,
+        content: dep.inline ? dep.content : void 0,
+        kind: "script",
+        position: dep.position,
+        attributes: dep.attributes,
+        inline: dep.inline,
+        excludeFromHtml: dep.excludeFromHtml,
+        packageRole: dep.packageRole,
+        bundledSourceFilepaths: dep.bundledSourceFilepaths
+      };
+      this.writeCacheFile(filename, unbundledProcessedAsset);
+      return unbundledProcessedAsset;
+    }
+    if (dep.content) {
+      const tempDir = this.appConfig.absolutePaths.distDir;
+      fileSystem.ensureDir(tempDir);
+      const tempFileName = path.join(
+        tempDir,
+        `${path.parse(filename).name}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp.js`
+      );
+      fileSystem.write(tempFileName, dep.content);
+      const bundledFilePath = await this.bundleScript({
+        entrypoint: tempFileName,
+        outdir: this.getAssetsDir(),
+        minify: this.isProduction,
+        naming: `${path.parse(filename).name}-[hash].[ext]`,
+        ...this.getBundlerOptions(dep)
+      });
+      const processedAsset = {
+        filepath: bundledFilePath,
+        content: dep.inline ? fileSystem.readFileSync(bundledFilePath).toString() : void 0,
+        kind: "script",
+        position: dep.position,
+        attributes: dep.attributes,
+        inline: dep.inline,
+        excludeFromHtml: dep.excludeFromHtml,
+        packageRole: dep.packageRole,
+        groupedBundle: dep.groupedBundle,
+        bundledSourceFilepaths: dep.bundledSourceFilepaths
+      };
+      fileSystem.remove(tempFileName);
+      this.writeCacheFile(filename, processedAsset);
+      return processedAsset;
+    }
+    throw new Error("No content found for script asset");
+  }
+}
+export {
+  ContentScriptProcessor
+};

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/script/file-script.processor.d.ts

@@ -1,8 +1,9 @@
-import type { IHmrManager } from '../../../../internal-types';
-import type { FileScriptAsset, ProcessedAsset } from '../../assets.types';
-import { BaseScriptProcessor } from '../base/base-script-processor';
+import type { IHmrManager } from '../../../../../types/internal-types.js';
+import type { FileScriptAsset, ProcessedAsset } from '../../assets.types.js';
+import { BaseScriptProcessor } from '../base/base-script-processor.js';
 export declare class FileScriptProcessor extends BaseScriptProcessor<FileScriptAsset> {
     private hmrManager?;
+    private resolveHmrOutputFilepath;
     setHmrManager(hmrManager: IHmrManager): void;
     process(dep: FileScriptAsset): Promise<ProcessedAsset>;
 }

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/script/file-script.processor.js

@@ -1,23 +1,38 @@
 import path from "node:path";
-import { RESOLVED_ASSETS_DIR } from "../../../../constants";
+import { RESOLVED_ASSETS_DIR } from "../../../../../config/constants.js";
 import { fileSystem } from "@ecopages/file-system";
-import { BaseScriptProcessor } from "../base/base-script-processor";
+import { BaseScriptProcessor } from "../base/base-script-processor.js";
 class FileScriptProcessor extends BaseScriptProcessor {
   hmrManager;
+  resolveHmrOutputFilepath(entrypointPath) {
+    if (!this.hmrManager || !("getDistDir" in this.hmrManager)) {
+      return void 0;
+    }
+    const getDistDir = this.hmrManager.getDistDir;
+    if (typeof getDistDir !== "function") {
+      return void 0;
+    }
+    const relativePathJs = path.relative(this.appConfig.absolutePaths.srcDir, entrypointPath).replace(/\.(tsx?|jsx?|mdx?)$/, ".js").replace(/\[([^\]]+)\]/g, "_$1_");
+    return path.join(getDistDir.call(this.hmrManager), relativePathJs);
+  }
   setHmrManager(hmrManager) {
     this.hmrManager = hmrManager;
   }
   async process(dep) {
     if (this.hmrManager?.isEnabled() && !dep.inline) {
-      const outputUrl = await this.hmrManager.registerEntrypoint(dep.filepath);
+      const outputUrl = await this.hmrManager.registerScriptEntrypoint(dep.filepath);
+      const outputFilepath = this.resolveHmrOutputFilepath(dep.filepath);
       return {
-        filepath: dep.filepath,
+        filepath: outputFilepath ?? dep.filepath,
+        sourceFilepath: dep.filepath,
         srcUrl: outputUrl,
         kind: "script",
         position: dep.position,
         attributes: dep.attributes,
         inline: false,
-        excludeFromHtml: dep.excludeFromHtml
+        excludeFromHtml: dep.excludeFromHtml,
+        packageRole: dep.packageRole,
+        bundledSourceFilepaths: dep.bundledSourceFilepaths
       };
     }
     const content = fileSystem.readFileSync(dep.filepath);
@@ -40,12 +55,15 @@ class FileScriptProcessor extends BaseScriptProcessor {
         }
         return {
           filepath,
+          sourceFilepath: dep.filepath,
           content,
           kind: "script",
           position: dep.position,
           attributes: dep.attributes,
           inline: dep.inline,
-          excludeFromHtml: dep.excludeFromHtml
+          excludeFromHtml: dep.excludeFromHtml,
+          packageRole: dep.packageRole,
+          bundledSourceFilepaths: dep.bundledSourceFilepaths
         };
       }
       const relativeFilepath = path.relative(this.appConfig.absolutePaths.srcDir, dep.filepath);
@@ -61,12 +79,15 @@ class FileScriptProcessor extends BaseScriptProcessor {
       });
       return {
         filepath: bundledFilePath,
+        sourceFilepath: dep.filepath,
         content: dep.inline ? fileSystem.readFileSync(bundledFilePath).toString() : void 0,
         kind: "script",
         position: dep.position,
         attributes: dep.attributes,
         inline: dep.inline,
-        excludeFromHtml: dep.excludeFromHtml
+        excludeFromHtml: dep.excludeFromHtml,
+        packageRole: dep.packageRole,
+        bundledSourceFilepaths: dep.bundledSourceFilepaths
       };
     });
   }

package/src/services/assets/asset-processing-service/processors/script/node-module-script.processor.d.ts

@@ -0,0 +1,42 @@
+import type { NodeModuleScriptAsset } from '../../assets.types.js';
+import { BaseScriptProcessor } from '../base/base-script-processor.js';
+/**
+ * Processes browser script assets whose entrypoint is referenced by package specifier.
+ *
+ * @remarks
+ * Resolution stays app-boundary-first: prefer the active build adapter, then fall back
+ * to ESM export-map resolution, and only then probe a small set of literal file paths.
+ */
+export declare class NodeModuleScriptProcessor extends BaseScriptProcessor<NodeModuleScriptAsset> {
+    process(dep: NodeModuleScriptAsset): Promise<import("../../assets.types.js").ProcessedAsset>;
+    /**
+     * Resolves a node-module script entry from the current app boundary.
+     *
+     * @remarks
+     * The build adapter remains the primary resolution surface because Bun/native
+     * host-owned builds may have a more accurate view of aliases and package
+     * ownership than core does. The local fallback only runs when that adapter
+     * resolution is unavailable.
+     */
+    private resolveModulePath;
+    /**
+     * Resolves browser-owned script specifiers without relying on CommonJS resolution.
+     *
+     * @remarks
+     * This path intentionally stays ESM-first because these assets are emitted as
+     * browser scripts. We first ask Node's ESM resolver to evaluate the package
+     * export map from the app boundary. If that still fails, we fall back to a
+     * bounded filesystem probe so direct file installs and package subpaths like
+     * `pkg/client/entry` still resolve when the export map does not cover them.
+     */
+    private resolveModulePathFallback;
+    /**
+     * Returns the file candidates we accept during the final literal filesystem probe.
+     *
+     * @remarks
+     * This is intentionally small and browser-entry-oriented: direct files, common
+     * JS extensions, and `index.*` entrypoints. If a package needs anything more
+     * exotic, it should resolve through the adapter or ESM export-map path above.
+     */
+    private getFallbackCandidatePaths;
+}