@ecopages/core 0.2.0-beta.23 → 0.2.0-beta.25

package/src/env.d.ts

@@ -3,6 +3,8 @@ interface EcopagesEnv {
 	ECOPAGES_HOSTNAME: string;
 	ECOPAGES_PORT: string;
 	ECOPAGES_LOGGER_DEBUG: 'true' | 'false';
+	/** When `true`, emits startup phase timings to stderr. Also enabled when `ECOPAGES_LOGGER_DEBUG=true`. */
+	ECOPAGES_STARTUP_TRACE?: 'true' | 'false';
 }
 
 declare global {

package/src/plugins/alias-resolver-cache.d.ts

@@ -1,17 +1,14 @@
 /**
- * Per-plugin cache for `@/...` alias resolution.
+ * Per-plugin cache for tsconfig path alias resolution.
  *
  * @remarks
- * The `ecopages-alias-resolver` plugin resolves project aliases like
- * `@/components/Button` to concrete file paths under the app's `srcDir`.
- * Each resolution can trigger up to 22 `existsSync` calls and (when
- * the resolved path is a barrel) a `readFileSync` to detect
- * `export * from './...'` forwarding.
+ * The `ecopages-alias-resolver` plugin resolves project path aliases to
+ * concrete file paths using the app's tsconfig `paths`. Each resolution goes
+ * through oxc-resolver and may read barrel re-export targets.
  *
- * This cache memoizes the result keyed by `(srcDir, specifier)`. It is
+ * This cache memoizes the result keyed by `(projectRoot, specifier)`. It is
  * process-local and not currently invalidated by the file watcher —
- * `srcDir` contents are assumed to be stable for the lifetime of the
- * process.
+ * project contents are assumed to be stable for the lifetime of the process.
  */
 export declare class AliasResolverCache {
     private readonly entries;

package/src/plugins/alias-resolver-plugin.d.ts

@@ -1,6 +1,6 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import { AliasResolverCache } from './alias-resolver-cache.js';
-export declare function resolveAppSourceAliasPath(srcDir: string, specifier: string): string | undefined;
-export declare function createAliasResolverPlugin(srcDir: string, options?: {
+export declare function createAliasResolverPlugin(projectRoot: string, options?: {
     cache?: AliasResolverCache;
 }): EcoBuildPlugin;
+export { isBarePackageImportSpecifier, matchesTsconfigPathPrefix, loadTsconfigPathPrefixes, resolveProjectImportPath, resolveProjectModulePath, } from './tsconfig-import-resolver.js';

package/src/plugins/alias-resolver-plugin.js

@@ -1,65 +1,52 @@
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
 import { AliasResolverCache } from "./alias-resolver-cache.js";
-const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
-function findResolvablePath(candidate) {
-  if (path.extname(candidate)) {
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  for (const extension of RESOLVABLE_EXTENSIONS) {
-    const fileCandidate = `${candidate}${extension}`;
-    if (existsSync(fileCandidate)) {
-      return fileCandidate;
-    }
-  }
-  for (const extension of RESOLVABLE_EXTENSIONS) {
-    const indexCandidate = path.join(candidate, `index${extension}`);
-    if (existsSync(indexCandidate)) {
-      return indexCandidate;
-    }
-  }
-  return void 0;
-}
-function resolveAliasedBarrelTarget(resolvedPath) {
-  if (!path.basename(resolvedPath).startsWith("index.")) {
-    return resolvedPath;
-  }
-  const source = readFileSync(resolvedPath, "utf8").trim();
-  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
-  if (!match?.[1]?.startsWith(".")) {
-    return resolvedPath;
-  }
-  const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
-  return target ?? resolvedPath;
+import { loadTsconfigPathPrefixes, resolveProjectImportPath } from "./tsconfig-import-resolver.js";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function resolveAppSourceAliasPath(srcDir, specifier) {
-  if (!specifier.startsWith("@/")) {
-    return void 0;
+function buildPathPrefixFilter(prefix) {
+  if (prefix.endsWith("/")) {
+    return new RegExp(`^${escapeRegExp(prefix)}`);
   }
-  const candidate = path.join(srcDir, specifier.slice(2));
-  const resolved = findResolvablePath(candidate);
-  return resolved ? resolveAliasedBarrelTarget(resolved) : void 0;
+  return new RegExp(`^${escapeRegExp(prefix)}(?:/|$)`);
 }
-function createAliasResolverPlugin(srcDir, options) {
+function createAliasResolverPlugin(projectRoot, options) {
   const cache = options?.cache ?? new AliasResolverCache();
+  const pathPrefixes = loadTsconfigPathPrefixes(projectRoot);
   return {
     name: "ecopages-alias-resolver",
     setup(build) {
-      build.onResolve({ filter: /^@\// }, (args) => {
-        const cached = cache.get(srcDir, args.path);
-        if (cached.hit) {
-          return cached.resolved ? { path: cached.resolved } : {};
-        }
-        const resolved = resolveAppSourceAliasPath(srcDir, args.path);
-        cache.set(srcDir, args.path, resolved);
-        return resolved ? { path: resolved } : {};
-      });
+      if (pathPrefixes.length === 0) {
+        return;
+      }
+      for (const prefix of pathPrefixes) {
+        build.onResolve({ filter: buildPathPrefixFilter(prefix) }, (args) => {
+          if (!args.importer) {
+            return void 0;
+          }
+          const cached = cache.get(projectRoot, args.path);
+          if (cached.hit) {
+            return cached.resolved ? { path: cached.resolved } : void 0;
+          }
+          const resolved = resolveProjectImportPath(projectRoot, args.importer, args.path);
+          cache.set(projectRoot, args.path, resolved);
+          return resolved ? { path: resolved } : void 0;
+        });
+      }
     }
   };
 }
+import {
+  isBarePackageImportSpecifier,
+  matchesTsconfigPathPrefix,
+  loadTsconfigPathPrefixes as loadTsconfigPathPrefixes2,
+  resolveProjectImportPath as resolveProjectImportPath2,
+  resolveProjectModulePath
+} from "./tsconfig-import-resolver.js";
 export {
   createAliasResolverPlugin,
-  resolveAppSourceAliasPath
+  isBarePackageImportSpecifier,
+  loadTsconfigPathPrefixes2 as loadTsconfigPathPrefixes,
+  matchesTsconfigPathPrefix,
+  resolveProjectImportPath2 as resolveProjectImportPath,
+  resolveProjectModulePath
 };

package/src/plugins/integration-plugin.d.ts

@@ -197,6 +197,14 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     initializeRenderer(options?: {
         rendererModules?: unknown;
     }): IntegrationRenderer<C>;
+    /**
+     * Shapes one dependency batch before core asset processing runs.
+     *
+     * @remarks
+     * Integrations use this to assign grouped-build metadata or other batch-level
+     * policy without teaching core about integration-specific asset graphs.
+     */
+    prepareAssetDependencies?(dependencies: AssetDefinition[]): AssetDefinition[];
     /**
      * Prepares build-facing contributions before the app build manifest is sealed.
      *

package/src/plugins/tsconfig-import-resolver.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Loads `compilerOptions.paths` keys from tsconfig, following `extends` recursively.
+ */
+export declare function loadTsconfigPathPrefixes(projectRoot: string): string[];
+export declare function matchesTsconfigPathPrefix(specifier: string, prefixes: readonly string[]): boolean;
+/**
+ * Returns true when `specifier` looks like a bare npm package import rather than
+ * a relative path, absolute path, node built-in, tsconfig alias, or `#` import map.
+ */
+export declare function isBarePackageImportSpecifier(specifier: string, projectRoot?: string): boolean;
+/**
+ * Resolves a relative or tsconfig path alias import (via oxc-resolver).
+ */
+export declare function resolveProjectModulePath(projectRoot: string, fromFile: string, specifier: string): string | undefined;
+/**
+ * Resolves a TS path alias import using the app's tsconfig `paths` (via oxc-resolver).
+ */
+export declare function resolveProjectImportPath(projectRoot: string, fromFile: string, specifier: string): string | undefined;

package/src/plugins/tsconfig-import-resolver.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { ResolverFactory } from "oxc-resolver";
+const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx"];
+const resolverCache = /* @__PURE__ */ new Map();
+const pathPrefixCache = /* @__PURE__ */ new Map();
+function stripJsonComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
+function findTsconfigPath(projectRoot) {
+  const candidate = path.join(projectRoot, "tsconfig.json");
+  return existsSync(candidate) ? candidate : void 0;
+}
+function readJsonFile(filePath) {
+  const source = readFileSync(filePath, "utf8");
+  try {
+    return JSON.parse(source);
+  } catch {
+    return JSON.parse(stripJsonComments(source));
+  }
+}
+function loadTsconfigPathPrefixes(projectRoot) {
+  const cached = pathPrefixCache.get(projectRoot);
+  if (cached) {
+    return cached;
+  }
+  const tsconfigPath = findTsconfigPath(projectRoot);
+  if (!tsconfigPath) {
+    pathPrefixCache.set(projectRoot, []);
+    return [];
+  }
+  const prefixes = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const collectFromConfig = (configPath) => {
+    const normalized = path.resolve(configPath);
+    if (visited.has(normalized)) {
+      return;
+    }
+    visited.add(normalized);
+    let config;
+    try {
+      config = readJsonFile(normalized);
+    } catch {
+      return;
+    }
+    if (typeof config.extends === "string") {
+      const parentPath = path.resolve(path.dirname(normalized), config.extends);
+      collectFromConfig(parentPath);
+    }
+    for (const key of Object.keys(config.compilerOptions?.paths ?? {})) {
+      if (key.endsWith("/*")) {
+        prefixes.add(key.slice(0, -1));
+        continue;
+      }
+      if (key.endsWith("*")) {
+        prefixes.add(key.slice(0, -1));
+        continue;
+      }
+      prefixes.add(key);
+    }
+  };
+  collectFromConfig(tsconfigPath);
+  const resolvedPrefixes = [...prefixes];
+  pathPrefixCache.set(projectRoot, resolvedPrefixes);
+  return resolvedPrefixes;
+}
+function matchesTsconfigPathPrefix(specifier, prefixes) {
+  return prefixes.some((prefix) => {
+    if (prefix.endsWith("/")) {
+      return specifier.startsWith(prefix);
+    }
+    return specifier === prefix || specifier.startsWith(`${prefix}/`);
+  });
+}
+function isBarePackageImportSpecifier(specifier, projectRoot) {
+  if (specifier.startsWith(".") || path.isAbsolute(specifier) || specifier.startsWith("/")) {
+    return false;
+  }
+  if (specifier.startsWith("node:") || specifier.startsWith("#") || specifier.includes(":")) {
+    return false;
+  }
+  if (projectRoot && matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
+    return false;
+  }
+  return true;
+}
+function getResolverFactory(projectRoot) {
+  const cached = resolverCache.get(projectRoot);
+  if (cached) {
+    return cached;
+  }
+  const tsconfigPath = findTsconfigPath(projectRoot);
+  if (!tsconfigPath) {
+    return void 0;
+  }
+  const resolver = new ResolverFactory({
+    tsconfig: {
+      configFile: tsconfigPath
+    },
+    extensions: [...RESOLVABLE_EXTENSIONS]
+  });
+  resolverCache.set(projectRoot, resolver);
+  return resolver;
+}
+function resolveAliasedBarrelTarget(resolvedPath) {
+  if (!path.basename(resolvedPath).startsWith("index.")) {
+    return resolvedPath;
+  }
+  const source = readFileSync(resolvedPath, "utf8").trim();
+  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+  if (!match?.[1]?.startsWith(".")) {
+    return resolvedPath;
+  }
+  const targetDir = path.dirname(resolvedPath);
+  const targetBase = path.resolve(targetDir, match[1]);
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const candidate = `${targetBase}${extension}`;
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const candidate = path.join(targetBase, `index${extension}`);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return resolvedPath;
+}
+function resolveProjectModulePath(projectRoot, fromFile, specifier) {
+  const prefixes = loadTsconfigPathPrefixes(projectRoot);
+  const isRelative = specifier.startsWith(".");
+  const isPathAlias = matchesTsconfigPathPrefix(specifier, prefixes);
+  if (!isRelative && !isPathAlias) {
+    return void 0;
+  }
+  const resolver = getResolverFactory(projectRoot);
+  if (!resolver) {
+    return void 0;
+  }
+  const result = resolver.sync(path.dirname(fromFile), specifier);
+  if (!result.path) {
+    return void 0;
+  }
+  return resolveAliasedBarrelTarget(realpathSync(result.path));
+}
+function resolveProjectImportPath(projectRoot, fromFile, specifier) {
+  if (!matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
+    return void 0;
+  }
+  return resolveProjectModulePath(projectRoot, fromFile, specifier);
+}
+export {
+  isBarePackageImportSpecifier,
+  loadTsconfigPathPrefixes,
+  matchesTsconfigPathPrefix,
+  resolveProjectImportPath,
+  resolveProjectModulePath
+};

package/src/route-renderer/orchestration/page-browser-graph.service.js

@@ -103,6 +103,9 @@ class PageBrowserGraphService {
         );
         continue;
       }
+      if (this.isHmrEnabled()) {
+        continue;
+      }
       if (!contribution?.dependencies?.length) {
         continue;
       }
@@ -130,15 +133,18 @@ class PageBrowserGraphService {
     );
     const groupedAssetsByRoute = /* @__PURE__ */ new Map();
     for (const [routeFile, groupedAssetKeys] of groupedAssetKeysByRoute) {
-      groupedAssetsByRoute.set(
-        routeFile,
-        processedGroupedDependencies.filter((asset) => {
-          if (!asset.groupedBundle) {
-            return false;
-          }
-          return groupedAssetKeys.has(getGroupedBundleAssetKey(asset.groupedBundle));
-        })
-      );
+      const matchedAssets = processedGroupedDependencies.filter((asset) => {
+        if (!asset.groupedBundle) {
+          return false;
+        }
+        return groupedAssetKeys.has(getGroupedBundleAssetKey(asset.groupedBundle));
+      });
+      if (groupedAssetKeys.size > 0 && matchedAssets.length === 0) {
+        appLogger.warn(
+          `Grouped page-browser assets for ${routeFile} are missing groupedBundle metadata after processing. Hydration scripts may be omitted from HTML.`
+        );
+      }
+      groupedAssetsByRoute.set(routeFile, matchedAssets);
     }
     return {
       assetsByRoute: groupedAssetsByRoute,

package/src/route-renderer/page-loading/ecopages-virtual-imports.d.ts

@@ -2,6 +2,12 @@ export type EcopagesVirtualImport = {
     from: string;
     imports: string[] | undefined;
 };
+/**
+ * @remarks
+ * Content server modules static-import every MDX entry. They must never become
+ * browser module-script dependencies discovered from page or component sources.
+ */
+export declare function isBrowserEcopagesVirtualImport(specifier: string): boolean;
 /**
  * Extracts runtime `ecopages:` virtual-module imports from a component source file.
  *

package/src/route-renderer/page-loading/ecopages-virtual-imports.js

@@ -1,5 +1,9 @@
 import { readFileSync } from "node:fs";
 import { parseSync } from "oxc-parser";
+const CONTENT_SERVER_VIRTUAL_MODULE_PATTERN = /^ecopages:content\/[a-z][a-z0-9-]+\/server$/;
+function isBrowserEcopagesVirtualImport(specifier) {
+  return specifier.startsWith("ecopages:") && !CONTENT_SERVER_VIRTUAL_MODULE_PATTERN.test(specifier);
+}
 function extractEcopagesVirtualImports(file) {
   let source;
   try {
@@ -18,7 +22,7 @@ function extractEcopagesVirtualImports(file) {
     if (node.type !== "ImportDeclaration") continue;
     if (node.importKind === "type") continue;
     const specifier = node.source?.value ?? "";
-    if (!specifier.startsWith("ecopages:")) continue;
+    if (!isBrowserEcopagesVirtualImport(specifier)) continue;
     if (found.get(specifier) === null) {
       continue;
     }
@@ -53,5 +57,6 @@ function extractEcopagesVirtualImports(file) {
   }));
 }
 export {
-  extractEcopagesVirtualImports
+  extractEcopagesVirtualImports,
+  isBrowserEcopagesVirtualImport
 };

package/src/route-renderer/page-loading/module-declaration-aggregation.js

@@ -1,4 +1,5 @@
 import { normalizeModuleDeclarations } from "../../eco/module-dependencies.js";
+import { isBrowserEcopagesVirtualImport } from "./ecopages-virtual-imports.js";
 function getDeclaredModules(value) {
   if (!Array.isArray(value)) {
     return void 0;
@@ -22,6 +23,9 @@ function mergeModuleDeclaration(modulesMap, declaration) {
 }
 function collectModuleDeclarations(modulesMap, declaredModules, autoVirtualImports) {
   for (const declaration of normalizeModuleDeclarations(getDeclaredModules(declaredModules))) {
+    if (declaration.from.startsWith("ecopages:") && !isBrowserEcopagesVirtualImport(declaration.from)) {
+      continue;
+    }
     mergeModuleDeclaration(modulesMap, declaration);
   }
   for (const declaration of autoVirtualImports) {

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

@@ -42,6 +42,7 @@ export declare class AssetProcessingService {
      * entries.
      */
     processDependencies(deps: AssetDefinition[], key: string): Promise<ProcessedAsset[]>;
+    private prepareDependenciesForProcessing;
     /**
      * Processes deduplicated dependencies grouped by processor type.
      *
@@ -80,6 +81,8 @@ export declare class AssetProcessingService {
      * Returns the cached processed asset for a dependency key when available.
      */
     private getCachedAsset;
+    private getCachedContentScriptAsset;
+    private resolveCachedContentScriptFilepath;
     /**
      * Stores one processed asset in the dependency cache.
      */

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

@@ -4,12 +4,19 @@ import { appLogger } from "../../../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
 import { deduplicateAssetDependencies, getAssetDependencyKey } from "./asset-dependency-keys.js";
 import {
+  ensureGroupedContentScriptsBundle,
   partitionGroupedContentScriptDependencies,
   processGroupedDependencyBundles
 } from "./grouped-content-bundles.js";
+import { resolveIntegrationPluginForProcessingKey } from "./resolve-integration-plugin.js";
 import { isHmrAware } from "./processor.interface.js";
 import { ProcessorRegistry } from "./processor.registry.js";
 import { processUngroupedDependency } from "./ungrouped-dependency-processing.js";
+import { materializeContentScriptAsset } from "./materialize-content-script-asset.js";
+import {
+  getDevBrowserScriptCacheEntry,
+  setDevBrowserScriptCacheEntry
+} from "../../../build/dev-browser-script-cache.js";
 import {
   ContentScriptProcessor,
   ContentStylesheetProcessor,
@@ -68,10 +75,16 @@ class AssetProcessingService {
     const depsDir = path.join(this.config.absolutePaths.distDir, RESOLVED_ASSETS_DIR);
     fileSystem.ensureDir(depsDir);
     const dedupedDeps = deduplicateAssetDependencies(deps);
-    const results = await this.processDependenciesParallel(dedupedDeps, key);
+    const preparedDeps = this.prepareDependenciesForProcessing(dedupedDeps, key);
+    ensureGroupedContentScriptsBundle(preparedDeps);
+    const results = await this.processDependenciesParallel(preparedDeps);
     await this.optimizeDependencies(results);
     return results;
   }
+  prepareDependenciesForProcessing(deps, processingKey) {
+    const plugin = resolveIntegrationPluginForProcessingKey(this.config, processingKey);
+    return plugin?.prepareAssetDependencies?.(deps) ?? deps;
+  }
   /**
    * Processes deduplicated dependencies grouped by processor type.
    *
@@ -80,14 +93,13 @@ class AssetProcessingService {
    * pair, while still allowing the overall dependency set to resolve in
    * parallel.
    */
-  async processDependenciesParallel(deps, key) {
+  async processDependenciesParallel(deps) {
     const grouped = this.groupDependenciesByType(deps);
     const groupPromises = Object.entries(grouped).map(async ([, typeDeps]) => {
       const { groupedBundleDeps, ungroupedDeps } = partitionGroupedContentScriptDependencies(typeDeps);
       const typePromises = ungroupedDeps.map(
         (dep) => processUngroupedDependency({
           dep,
-          key,
           depKey: getAssetDependencyKey(dep),
           getCachedAsset: (assetDep, depKey) => this.getCachedAsset(assetDep, depKey),
           getProcessor: (assetDep) => this.registry.getProcessor(assetDep.kind, assetDep.source),
@@ -109,7 +121,6 @@ class AssetProcessingService {
       );
       const groupedResults = await processGroupedDependencyBundles({
         bundles: Array.from(groupedBundleDeps.values()),
-        key,
         getCachedAsset: (dep, depKey) => this.getCachedAsset(dep, depKey),
         getDependencyKey: getAssetDependencyKey,
         getGroupedProcessor: () => this.registry.getProcessor("script", "content"),
@@ -229,6 +240,9 @@ class AssetProcessingService {
     if (process.env.NODE_ENV !== "production" && dep.source === "file" && dep.kind === "stylesheet") {
       return null;
     }
+    if (dep.kind === "script" && dep.source === "content") {
+      return this.getCachedContentScriptAsset(dep, depKey);
+    }
     const cached = this.cache.get(depKey);
     if (!cached) {
       return null;
@@ -239,11 +253,34 @@ class AssetProcessingService {
     }
     return cached.asset;
   }
+  getCachedContentScriptAsset(dep, depKey) {
+    const filepath = this.resolveCachedContentScriptFilepath(depKey) ?? getDevBrowserScriptCacheEntry(this.config, depKey)?.filepath;
+    if (!filepath) {
+      return null;
+    }
+    const materialized = materializeContentScriptAsset(dep, filepath);
+    this.cache.set(depKey, { asset: materialized });
+    return materialized;
+  }
+  resolveCachedContentScriptFilepath(depKey) {
+    const cached = this.cache.get(depKey);
+    if (!cached?.asset.filepath) {
+      return void 0;
+    }
+    if (!fileSystem.exists(cached.asset.filepath)) {
+      this.cache.delete(depKey);
+      return void 0;
+    }
+    return cached.asset.filepath;
+  }
   /**
    * Stores one processed asset in the dependency cache.
    */
   setCachedAsset(dep, depKey, asset) {
     this.cache.set(depKey, { asset });
+    if (dep.kind === "script" && dep.source === "content") {
+      setDevBrowserScriptCacheEntry(this.config, depKey, asset);
+    }
   }
   /**
    * Clears all cached processed assets.

package/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.d.ts

@@ -0,0 +1,52 @@
+import type { createRequire } from 'node:module';
+export type BrowserRuntimeDefaultExportPolicy = 'emit-default' | 'skip-default';
+type RequireFromRoot = ReturnType<typeof createRequire>;
+/**
+ * Resolves a package specifier to its ESM entry file path from the app root.
+ */
+export declare function resolvePackageEsmEntryPath(specifier: string, rootDir: string): string | undefined;
+/**
+ * Builds a relative import path from a generated runtime entry file to a resolved module path.
+ */
+export declare function toRelativeEntryImport(entryDir: string, resolvedPath: string): string;
+/**
+ * Resolves a browser runtime entry import to an ESM file path when possible.
+ *
+ * @remarks
+ * `createRequire().resolve()` follows the `require` export condition and can
+ * land on `.cjs` entrypoints. Browser vendor bundles then emit runtime
+ * `require()` calls for React externals. Prefer Node's ESM resolver first, then
+ * a `.cjs` → `.js` sibling fallback.
+ */
+export declare function resolveBrowserRuntimeEntryImport(options: {
+    specifier: string;
+    requireFromRoot: RequireFromRoot;
+    entryDir: string;
+    rootDir: string;
+}): string;
+/**
+ * Decides whether a generated runtime entry should re-export a default binding.
+ *
+ * @remarks
+ * ESM-only packages such as `@tanstack/react-query` expose named exports only.
+ * Legacy CJS packages such as `react` assign `module.exports` directly and have
+ * no `.default` under `require()`, but still need a default re-export for
+ * `import React from 'react'` in browser bundles.
+ *
+ * ESM source inspection is a best-effort fast path; when it is inconclusive the
+ * policy falls back to the shape returned by `require()`.
+ */
+export declare function inferBrowserRuntimeDefaultExportPolicy(options: {
+    specifier: string;
+    requireFromRoot: RequireFromRoot;
+    rootDir: string;
+}): BrowserRuntimeDefaultExportPolicy;
+/**
+ * Reads the named runtime exports that should be re-exported from a generated runtime entry module.
+ *
+ * @remarks
+ * Default exports are handled separately because generated runtime entry files need to emit a
+ * synthetic default binding only when the caller explicitly asks for it.
+ */
+export declare function listBrowserRuntimeModuleExportNames(specifier: string, requireFromRoot: RequireFromRoot): string[];
+export {};