@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

package/src/build/pages-unified-graph-build.js

@@ -0,0 +1,206 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../global/app-logger.js";
+import { build, getAppServerBuildPlugins } from "./build-adapter.js";
+import { requireBuildRuntime } from "./build-runtime.js";
+import { resolveBuildProfileOptions } from "./build-profile-options.js";
+import { createBuildInputsFingerprint, hashAppConfigFile } from "./build-input-fingerprint.js";
+import {
+  isProductionCacheManifestCurrent,
+  matchesProductionCacheBuildKey,
+  matchesProductionCacheFingerprint,
+  readProductionCacheManifest,
+  writeProductionCacheManifest
+} from "./production-build-cache.js";
+import { getCorePackageVersion } from "../services/module-loading/route-module-build-manifest.js";
+import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
+import { getSharedRouteModuleBuildCache } from "../services/module-loading/route-module-build-cache-registry.js";
+import { normalizeNodeRuntimeBuildOutputFile } from "./runtime-build-output-normalizer.js";
+import { resolveRouteModuleDependencyPaths } from "../services/module-loading/route-module-dependency-hasher.js";
+import { getJsxOwnershipPlugins } from "./jsx-ownership-plugins.js";
+const PAGES_UNIFIED_GRAPH_CACHE_DIR = ".server-pages-graph";
+const PAGES_UNIFIED_GRAPH_CACHE_FILENAME = ".build-cache.json";
+function isPagesUnifiedGraphEnabled() {
+  if (process.env.ECOPAGES_UNIFIED_PAGES_GRAPH === "0") {
+    return false;
+  }
+  if (process.env.ECOPAGES_UNIFIED_PAGES_GRAPH === "1") {
+    return true;
+  }
+  return process.env.NODE_ENV === "production";
+}
+function shouldBuildPagesUnifiedGraph() {
+  return isPagesUnifiedGraphEnabled() && process.env.NODE_ENV === "production";
+}
+function isPagesUnifiedGraphPage(filePath, appConfig) {
+  const normalizedPath = path.normalize(filePath);
+  return appConfig.templatesExt.some((extension) => normalizedPath.endsWith(extension));
+}
+function getPagesUnifiedGraphCachePath(appConfig) {
+  return path.join(
+    resolveInternalExecutionDir(appConfig),
+    PAGES_UNIFIED_GRAPH_CACHE_DIR,
+    PAGES_UNIFIED_GRAPH_CACHE_FILENAME
+  );
+}
+function createPagesUnifiedGraphBuildKey(appConfig, outdir) {
+  const plugins = appConfig.runtime?.buildManifest ? getAppServerBuildPlugins(appConfig) : [];
+  const pluginNames = [...plugins, ...getJsxOwnershipPlugins(appConfig)].map((plugin) => plugin.name).sort().join("|");
+  const templateExtensions = [...appConfig.templatesExt].sort().join("|");
+  return [
+    path.resolve(outdir),
+    hashAppConfigFile(appConfig),
+    templateExtensions,
+    pluginNames,
+    "es2022",
+    "esm",
+    "external-packages"
+  ].join("::");
+}
+function readPagesUnifiedGraphManifest(appConfig) {
+  const manifest = readProductionCacheManifest(
+    getPagesUnifiedGraphCachePath(appConfig)
+  );
+  if (!manifest?.outputs) {
+    return void 0;
+  }
+  return manifest;
+}
+function writePagesUnifiedGraphManifest(appConfig, manifest) {
+  writeProductionCacheManifest(getPagesUnifiedGraphCachePath(appConfig), manifest);
+}
+function createSafeGraphEntryKey(entryPath, rootDir) {
+  const relativePath = path.relative(rootDir, entryPath).replace(/\.[^.]+$/u, "");
+  const safeKey = relativePath.replace(/[^a-zA-Z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");
+  return safeKey.length > 0 ? safeKey : "page";
+}
+function resolveOutputForEntrypoint(entryPath, entryKey, buildResult) {
+  const exactOutput = buildResult.entryOutputs?.[path.resolve(entryPath)];
+  if (exactOutput) {
+    return exactOutput;
+  }
+  for (const { path: outputPath } of buildResult.outputs) {
+    const outputBaseName = path.basename(outputPath);
+    if (outputBaseName.startsWith(`${entryKey}-`) && /\.(?:m?js)$/u.test(outputBaseName)) {
+      return outputPath;
+    }
+    if (outputBaseName === `${entryKey}.js` || outputBaseName === `${entryKey}.mjs`) {
+      return outputPath;
+    }
+  }
+  return void 0;
+}
+function isManifestValidForEntries(manifest, appConfig, outdir, entryPaths) {
+  if (!isProductionCacheManifestCurrent(manifest, getCorePackageVersion())) {
+    return false;
+  }
+  if (!matchesProductionCacheFingerprint(manifest, createBuildInputsFingerprint(appConfig))) {
+    return false;
+  }
+  if (!matchesProductionCacheBuildKey(manifest, createPagesUnifiedGraphBuildKey(appConfig, outdir))) {
+    return false;
+  }
+  return entryPaths.every((entryPath) => {
+    const resolvedEntryPath = path.resolve(entryPath);
+    const outputPath = manifest.outputs[resolvedEntryPath];
+    return outputPath ? fileSystem.exists(outputPath) : false;
+  });
+}
+async function ensurePagesUnifiedGraphBuilt(options) {
+  if (!shouldBuildPagesUnifiedGraph()) {
+    return void 0;
+  }
+  const eligibleEntryPaths = options.entryPaths.map((entryPath) => path.resolve(entryPath)).filter((entryPath) => isPagesUnifiedGraphPage(entryPath, options.appConfig));
+  if (eligibleEntryPaths.length === 0) {
+    return void 0;
+  }
+  const outdir = path.resolve(options.outdir);
+  const existingManifest = options.force ? void 0 : readPagesUnifiedGraphManifest(options.appConfig);
+  if (existingManifest && isManifestValidForEntries(existingManifest, options.appConfig, outdir, eligibleEntryPaths)) {
+    appLogger.debug("Reusing pages unified graph cache");
+    return existingManifest;
+  }
+  const plugins = options.appConfig.runtime?.buildManifest ? getAppServerBuildPlugins(options.appConfig) : [];
+  const mergedPlugins = [...plugins, ...getJsxOwnershipPlugins(options.appConfig)];
+  const routeModuleBuildCache = getSharedRouteModuleBuildCache(outdir, options.appConfig);
+  const entryRecord = {};
+  const entryKeysByPath = /* @__PURE__ */ new Map();
+  for (const entryPath of eligibleEntryPaths) {
+    const entryKey = createSafeGraphEntryKey(entryPath, options.appConfig.rootDir);
+    entryRecord[entryKey] = entryPath;
+    entryKeysByPath.set(entryPath, entryKey);
+  }
+  appLogger.debugTime("pagesUnifiedGraphBuild");
+  const buildOptions = {
+    ...resolveBuildProfileOptions("route-module", options.appConfig, {
+      entrypoints: entryRecord,
+      outdir,
+      splitting: true,
+      naming: "[name]-[hash].[ext]",
+      plugins: mergedPlugins.length > 0 ? mergedPlugins : void 0
+    }),
+    entrypoints: entryRecord
+  };
+  const buildResult = await build(buildOptions, requireBuildRuntime(options.appConfig).getProfile("route-module"));
+  appLogger.debugTimeEnd("pagesUnifiedGraphBuild");
+  if (!buildResult.success) {
+    const details = buildResult.logs.map((log) => log.message).join(" | ");
+    throw new Error(`Pages unified graph build failed: ${details}`);
+  }
+  const outputs = {};
+  for (const entryPath of eligibleEntryPaths) {
+    const fileHash = fileSystem.hash(entryPath);
+    const entryKey = entryKeysByPath.get(entryPath);
+    const compiledOutput = entryKey ? resolveOutputForEntrypoint(entryPath, entryKey, buildResult) : void 0;
+    if (!compiledOutput) {
+      throw new Error(`Pages unified graph build produced no output for ${entryPath}`);
+    }
+    normalizeNodeRuntimeBuildOutputFile(compiledOutput, options.appConfig.rootDir);
+    outputs[entryPath] = compiledOutput;
+    routeModuleBuildCache.recordBuild({
+      filePath: entryPath,
+      rootDir: options.appConfig.rootDir,
+      outdir,
+      fileHash,
+      outputPath: compiledOutput,
+      dependencyModulePaths: resolveRouteModuleDependencyPaths(buildResult, entryPath, options.appConfig.rootDir),
+      externalPackages: true,
+      plugins: mergedPlugins
+    });
+  }
+  const manifest = {
+    invalidationVersion: getCorePackageVersion(),
+    buildInputsFingerprint: createBuildInputsFingerprint(options.appConfig),
+    buildKey: createPagesUnifiedGraphBuildKey(options.appConfig, outdir),
+    builtAt: Date.now(),
+    outputs
+  };
+  writePagesUnifiedGraphManifest(options.appConfig, manifest);
+  appLogger.debug(`Built pages unified graph for ${eligibleEntryPaths.length} entries`);
+  return manifest;
+}
+async function importPagesUnifiedGraphModule(appConfig, filePath) {
+  const manifest = readPagesUnifiedGraphManifest(appConfig);
+  if (!manifest) {
+    return void 0;
+  }
+  const resolvedFilePath = path.resolve(filePath);
+  const outputPath = manifest.outputs[resolvedFilePath];
+  if (!outputPath || !fileSystem.exists(outputPath)) {
+    return void 0;
+  }
+  return await import(
+    /* @vite-ignore */
+    pathToFileURL(outputPath).href
+  );
+}
+export {
+  PAGES_UNIFIED_GRAPH_CACHE_DIR,
+  PAGES_UNIFIED_GRAPH_CACHE_FILENAME,
+  ensurePagesUnifiedGraphBuilt,
+  importPagesUnifiedGraphModule,
+  isPagesUnifiedGraphEnabled,
+  isPagesUnifiedGraphPage,
+  shouldBuildPagesUnifiedGraph
+};

package/src/build/parallel-build-executor.d.ts

@@ -0,0 +1,21 @@
+import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
+/**
+ * Concurrency-limited build executor wrapper.
+ *
+ * @remarks
+ * Runs up to `limit` builds concurrently. Use for independent route-module
+ * and HMR browser builds where FIFO serialization is unnecessary.
+ */
+export declare class ParallelBuildExecutor implements BuildExecutor {
+    private readonly inner;
+    private readonly limit;
+    private activeCount;
+    private queue;
+    constructor(inner: BuildExecutor, limit: number);
+    build(options: BuildOptions): Promise<BuildResult>;
+    private drainQueue;
+    unwrap(): BuildExecutor;
+    getConcurrencyLimitForTests(): number;
+    getActiveCountForTests(): number;
+    getQueuedCountForTests(): number;
+}

package/src/build/parallel-build-executor.js

@@ -0,0 +1,52 @@
+class ParallelBuildExecutor {
+  inner;
+  limit;
+  activeCount = 0;
+  queue = [];
+  constructor(inner, limit) {
+    this.inner = inner;
+    this.limit = Math.max(1, limit);
+  }
+  build(options) {
+    return new Promise((resolve, reject) => {
+      this.queue.push({
+        operation: () => this.inner.build(options),
+        resolve,
+        reject
+      });
+      this.drainQueue();
+    });
+  }
+  drainQueue() {
+    while (this.activeCount < this.limit && this.queue.length > 0) {
+      const next = this.queue.shift();
+      if (!next) {
+        return;
+      }
+      this.activeCount += 1;
+      void next.operation().then((result) => {
+        next.resolve(result);
+      }).catch((error) => {
+        next.reject(error);
+      }).finally(() => {
+        this.activeCount -= 1;
+        this.drainQueue();
+      });
+    }
+  }
+  unwrap() {
+    return this.inner;
+  }
+  getConcurrencyLimitForTests() {
+    return this.limit;
+  }
+  getActiveCountForTests() {
+    return this.activeCount;
+  }
+  getQueuedCountForTests() {
+    return this.queue.length;
+  }
+}
+export {
+  ParallelBuildExecutor
+};

package/src/build/production-build-cache.d.ts

@@ -0,0 +1,20 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+/**
+ * Shared manifest fields for persisted production build caches.
+ */
+export interface ProductionCacheManifestBase {
+    invalidationVersion: string;
+    buildInputsFingerprint?: string;
+    buildKey?: string;
+    builtAt?: number;
+}
+export type ProductionBuildCacheKind = 'server-entry' | 'route-module' | 'pages-graph';
+/** Returns every persisted production cache manifest path for one app. */
+export declare function getProductionBuildCacheManifestPaths(appConfig: EcoPagesAppConfig): string[];
+/** Removes all persisted production cache manifests for one app. */
+export declare function clearPersistedProductionBuildCacheManifests(appConfig: EcoPagesAppConfig): void;
+export declare function readProductionCacheManifest<T extends ProductionCacheManifestBase>(manifestPath: string): T | undefined;
+export declare function writeProductionCacheManifest(manifestPath: string, manifest: unknown): void;
+export declare function isProductionCacheManifestCurrent(manifest: ProductionCacheManifestBase | undefined, invalidationVersion: string): boolean;
+export declare function matchesProductionCacheFingerprint(manifest: ProductionCacheManifestBase | undefined, buildInputsFingerprint: string): boolean;
+export declare function matchesProductionCacheBuildKey(manifest: ProductionCacheManifestBase | undefined, buildKey: string): boolean;

package/src/build/production-build-cache.js

@@ -0,0 +1,63 @@
+import { fileSystem } from "@ecopages/file-system";
+import path from "node:path";
+import { ROUTE_MODULE_BUILD_CACHE_FILENAME } from "../services/module-loading/route-module-build-manifest.js";
+import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
+const ROUTE_MODULE_CACHE_OUTDIRS = [".server-modules", ".server-route-modules"];
+const PAGES_GRAPH_CACHE_DIR = ".server-pages-graph";
+function getProductionBuildCacheManifestPaths(appConfig) {
+  const executionDir = resolveInternalExecutionDir(appConfig);
+  const paths = [];
+  for (const subdir of ROUTE_MODULE_CACHE_OUTDIRS) {
+    paths.push(path.join(executionDir, subdir, ROUTE_MODULE_BUILD_CACHE_FILENAME));
+  }
+  paths.push(path.join(executionDir, ".server-entry", ROUTE_MODULE_BUILD_CACHE_FILENAME));
+  paths.push(path.join(executionDir, PAGES_GRAPH_CACHE_DIR, ROUTE_MODULE_BUILD_CACHE_FILENAME));
+  return paths;
+}
+function clearPersistedProductionBuildCacheManifests(appConfig) {
+  if (process.env.NODE_ENV !== "production") {
+    return;
+  }
+  for (const manifestPath of getProductionBuildCacheManifestPaths(appConfig)) {
+    if (fileSystem.exists(manifestPath)) {
+      fileSystem.remove(manifestPath);
+    }
+  }
+}
+function readProductionCacheManifest(manifestPath) {
+  if (!fileSystem.exists(manifestPath)) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(fileSystem.readFileSync(manifestPath));
+    if (!parsed || typeof parsed !== "object") {
+      return void 0;
+    }
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+function writeProductionCacheManifest(manifestPath, manifest) {
+  fileSystem.ensureDir(path.dirname(manifestPath));
+  fileSystem.write(manifestPath, `${JSON.stringify(manifest, null, "	")}
+`);
+}
+function isProductionCacheManifestCurrent(manifest, invalidationVersion) {
+  return manifest?.invalidationVersion === invalidationVersion;
+}
+function matchesProductionCacheFingerprint(manifest, buildInputsFingerprint) {
+  return manifest?.buildInputsFingerprint === buildInputsFingerprint;
+}
+function matchesProductionCacheBuildKey(manifest, buildKey) {
+  return manifest?.buildKey === buildKey;
+}
+export {
+  clearPersistedProductionBuildCacheManifests,
+  getProductionBuildCacheManifestPaths,
+  isProductionCacheManifestCurrent,
+  matchesProductionCacheBuildKey,
+  matchesProductionCacheFingerprint,
+  readProductionCacheManifest,
+  writeProductionCacheManifest
+};

package/src/build/rolldown-adapter-helpers.d.ts

@@ -2,12 +2,9 @@
  * Shared helpers for the Rolldown-backed build adapters.
  *
  * @remarks
- * The standard {@link RolldownBuildAdapter} (one-shot production builds)
- * and the dev {@link RolldownDevBuildAdapter} (DevEngine-backed
- * incremental rebuilds) both need the same BuildOptions → Rolldown
- * mapping, the same dependency-graph extraction, and the same
- * post-build rewriting pipeline. This module hosts the shared code so
- * the two adapters stay semantically identical.
+ * The standard {@link RolldownBuildAdapter} uses these helpers for
+ * BuildOptions → Rolldown mapping, dependency-graph extraction, and the
+ * post-build rewriting pipeline.
  *
  * @module
  */

package/src/build/rolldown-adapter-helpers.js

@@ -1,10 +1,41 @@
 import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { collectBrowserRuntimeImportRewriteMap, rewriteBrowserRuntimeImports } from "./browser-runtime-plugin.js";
 import { createServerSideCssShimPlugin } from "./server-side-css-shim-plugin.js";
 import { createRolldownPluginBridge } from "./rolldown-plugin-bridge.js";
-import { isDeclaredAppPackageImport, normalizeNodeRuntimeBuildOutputs } from "./runtime-build-output-normalizer.js";
+import {
+  isDeclaredAppPackageImport,
+  isWorkspacePackageImport,
+  normalizeNodeRuntimeBuildOutputs
+} from "./runtime-build-output-normalizer.js";
 const corePackageRequire = createRequire(new URL("../../package.json", import.meta.url));
+let corePackageNames;
+function getCorePackageNames() {
+  if (corePackageNames) {
+    return corePackageNames;
+  }
+  const packageJsonPath = new URL("../../package.json", import.meta.url);
+  corePackageNames = /* @__PURE__ */ new Set();
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+      const entries = packageJson[field];
+      if (!entries || typeof entries !== "object") {
+        continue;
+      }
+      for (const name of Object.keys(entries)) {
+        corePackageNames.add(name);
+      }
+    }
+  } catch {
+  }
+  return corePackageNames;
+}
+function isCoreDeclaredPackageImport(specifier) {
+  const name = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0] ?? specifier;
+  return getCorePackageNames().has(name);
+}
 function transpileProfileToOptions(profile) {
   switch (profile) {
     case "browser-script":
@@ -37,13 +68,21 @@ function getAppRootRequire(cache, contextRoot) {
   return req;
 }
 function shouldBundlePackageImport(id, contextRoot, appRootRequireCache) {
+  if (isWorkspacePackageImport(id, contextRoot)) {
+    return true;
+  }
   if (isDeclaredAppPackageImport(id, contextRoot)) {
     const appRootRequire = getAppRootRequire(appRootRequireCache, contextRoot);
     const appResolvedPath = tryResolveModule(id, appRootRequire);
     return Boolean(appResolvedPath && /\.(?:[cm]?ts|tsx|jsx)$/u.test(appResolvedPath));
   }
-  const coreResolvedPath = tryResolveModule(id, corePackageRequire);
-  return Boolean(coreResolvedPath && /\.(?:[cm]?ts|tsx|jsx)$/u.test(coreResolvedPath));
+  if (isCoreDeclaredPackageImport(id)) {
+    const coreResolvedPath = tryResolveModule(id, corePackageRequire);
+    if (coreResolvedPath && !/\.(?:[cm]?ts|tsx|jsx)$/u.test(coreResolvedPath)) {
+      return false;
+    }
+  }
+  return true;
 }
 function createExternalMatcher(options, appRootRequireCache) {
   const explicitExternals = new Set(options.external ?? []);
@@ -162,7 +201,8 @@ function resolveRolldownOptions(options, contextRoot, outdir, appRootRequireCach
     transformOptions.target = options.target;
   }
   const bundlePlugins = options.plugins ?? [];
-  const appPlugins = createRolldownPluginBridge(bundlePlugins, contextRoot);
+  const sourceTransforms = options.target === "browser" ? options.sourceTransforms ?? [] : [];
+  const appPlugins = createRolldownPluginBridge(bundlePlugins, contextRoot, sourceTransforms);
   const allPlugins = [...options.target !== "browser" ? [createServerSideCssShimPlugin()] : [], ...appPlugins];
   const inputOptions = {
     input: options.entrypoints,
@@ -172,6 +212,11 @@ function resolveRolldownOptions(options, contextRoot, outdir, appRootRequireCach
     transform: Object.keys(transformOptions).length > 0 ? transformOptions : void 0,
     resolve: options.conditions ? { conditionNames: options.conditions } : void 0,
     treeshake: typeof options.treeshaking === "boolean" ? options.treeshaking : true,
+    ...process.env.ECOPAGES_PROFILE_BUILD === "1" ? {} : {
+      checks: {
+        pluginTimings: false
+      }
+    },
     experimental: {
       nativeMagicString: true
     },
@@ -215,11 +260,21 @@ function rewriteBrowserRuntimeImportsInOutputs(result, contextRoot, plugins) {
     if (rewritten !== code) {
       fs.writeFileSync(output.path, rewritten);
     }
-    rewriteCache.add(contentKey);
+    rememberRewrite(contentKey);
   }
   return result;
 }
+const REWRITE_CACHE_MAX_ENTRIES = 2048;
 const rewriteCache = /* @__PURE__ */ new Set();
+function rememberRewrite(contentKey) {
+  rewriteCache.add(contentKey);
+  if (rewriteCache.size > REWRITE_CACHE_MAX_ENTRIES) {
+    const oldest = rewriteCache.values().next().value;
+    if (oldest !== void 0) {
+      rewriteCache.delete(oldest);
+    }
+  }
+}
 function djb2(input) {
   let hash = 5381;
   for (let i = 0; i < input.length; i++) {
@@ -246,11 +301,21 @@ function buildResultFromRolldownOutput(output, outdir, contextRoot) {
   }));
   const entryChunks = output.output.filter((entry) => entry.type === "chunk" && entry.isEntry);
   const dependencyGraph = entryChunks.length > 0 ? extractDependencyGraph(entryChunks, contextRoot) : void 0;
+  const entryOutputs = {};
+  for (const chunk of entryChunks) {
+    if (chunk.facadeModuleId) {
+      entryOutputs[normalizeModulePath(chunk.facadeModuleId, contextRoot)] = normalizeOutputPath(
+        chunk.fileName,
+        outdir
+      );
+    }
+  }
   return {
     success: true,
     logs: [],
     outputs,
-    dependencyGraph
+    dependencyGraph,
+    entryOutputs: entryChunks.length > 0 ? entryOutputs : void 0
   };
 }
 export {

package/src/build/rolldown-build-adapter.d.ts

@@ -6,9 +6,7 @@
  * default adapter installed by `ConfigBuilder` and the adapter that
  * issues real builds in production.
  *
- * Each `build()` creates a fresh `rolldown()` bundler, so there is no
- * module-graph reuse across calls. For HMR/watch mode where the same
- * entrypoints are rebuilt repeatedly, see {@link RolldownDevBuildAdapter}.
+ * Each `build()` creates a fresh `rolldown()` bundler.
  */
 import type { BuildAdapter, BuildOptions, BuildResult, BuildTranspileOptions, BuildTranspileProfile } from './build-adapter.js';
 export declare class RolldownBuildAdapter implements BuildAdapter {
@@ -16,9 +14,7 @@ export declare class RolldownBuildAdapter implements BuildAdapter {
     /** Per-adapter require cache, keyed on resolved context root. */
     private readonly appRootRequireCache;
     /**
-     * Issues one build. Creates a fresh `rolldown()` bundler per call,
-     * so no module-graph reuse. For repeated rebuilds on the same
-     * entrypoints, use {@link RolldownDevBuildAdapter}.
+     * Issues one build. Creates a fresh `rolldown()` bundler per call.
      */
     buildOrThrow(options: BuildOptions): Promise<BuildResult>;
     build(options: BuildOptions): Promise<BuildResult>;

package/src/build/rolldown-build-adapter.js

@@ -9,17 +9,17 @@ import {
   toBuildLogs,
   transpileProfileToOptions
 } from "./rolldown-adapter-helpers.js";
+import { recordRolldownBuildInvocation } from "./rolldown-build-invocation-metrics.js";
 const moduleRequire = createRequire(import.meta.url);
 class RolldownBuildAdapter {
   ownership = "rolldown";
   /** Per-adapter require cache, keyed on resolved context root. */
   appRootRequireCache = /* @__PURE__ */ new Map();
   /**
-   * Issues one build. Creates a fresh `rolldown()` bundler per call,
-   * so no module-graph reuse. For repeated rebuilds on the same
-   * entrypoints, use {@link RolldownDevBuildAdapter}.
+   * Issues one build. Creates a fresh `rolldown()` bundler per call.
    */
   async buildOrThrow(options) {
+    recordRolldownBuildInvocation("rolldown");
     const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
     const outdir = path.resolve(options.outdir ?? "dist/assets");
     const plugins = options.plugins ?? [];

package/src/build/rolldown-build-invocation-metrics.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Process-wide Rolldown build invocation counters for benchmarks and spikes.
+ *
+ * Gated behind {@link isRolldownBuildMetricsEnabled} so production paths stay quiet.
+ */
+export declare function isRolldownBuildMetricsEnabled(): boolean;
+export declare function recordRolldownBuildInvocation(adapter?: 'rolldown'): void;
+export declare function getRolldownBuildInvocationCounts(): Readonly<Record<string, number>>;
+export declare function resetRolldownBuildInvocationCounts(): void;
+export declare function recordPageModuleBuildInvocation(): void;
+export declare function getPageModuleRolldownBuildInvocations(): number;
+export declare function getTotalRolldownBuildInvocations(): number;

package/src/build/rolldown-build-invocation-metrics.js

@@ -0,0 +1,43 @@
+const invocationCounts = /* @__PURE__ */ new Map();
+let pageModuleBuildInvocations = 0;
+function isRolldownBuildMetricsEnabled() {
+  return process.env.ECOPAGES_ROLLDOWN_BUILD_METRICS === "1" || process.env.ECOPAGES_LOGGER_DEBUG === "true";
+}
+function recordRolldownBuildInvocation(adapter = "rolldown") {
+  if (!isRolldownBuildMetricsEnabled()) {
+    return;
+  }
+  invocationCounts.set(adapter, (invocationCounts.get(adapter) ?? 0) + 1);
+}
+function getRolldownBuildInvocationCounts() {
+  return Object.fromEntries(invocationCounts);
+}
+function resetRolldownBuildInvocationCounts() {
+  invocationCounts.clear();
+  pageModuleBuildInvocations = 0;
+}
+function recordPageModuleBuildInvocation() {
+  if (!isRolldownBuildMetricsEnabled()) {
+    return;
+  }
+  pageModuleBuildInvocations += 1;
+}
+function getPageModuleRolldownBuildInvocations() {
+  return pageModuleBuildInvocations;
+}
+function getTotalRolldownBuildInvocations() {
+  let total = 0;
+  for (const count of invocationCounts.values()) {
+    total += count;
+  }
+  return total;
+}
+export {
+  getPageModuleRolldownBuildInvocations,
+  getRolldownBuildInvocationCounts,
+  getTotalRolldownBuildInvocations,
+  isRolldownBuildMetricsEnabled,
+  recordPageModuleBuildInvocation,
+  recordRolldownBuildInvocation,
+  resetRolldownBuildInvocationCounts
+};

package/src/build/rolldown-plugin-bridge.d.ts

@@ -40,6 +40,7 @@
  * on every source file.
  */
 import type { Plugin } from 'rolldown';
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
 import type { EcoBuildPlugin } from './build-types.js';
 /**
  * Creates a Rolldown `Plugin` array that drives the supplied
@@ -55,5 +56,18 @@ import type { EcoBuildPlugin } from './build-types.js';
  * Plugin ordering is preserved: registrations from earlier eco plugins
  * are checked before registrations from later ones, matching the
  * original per-plugin priority semantics.
+ *
+ * @remarks
+ * Rolldown re-fires `buildStart` on each build, so registrations and the
+ * virtual-module counter are cleared before every `setup` pass — otherwise
+ * handlers accumulate when bridge plugins are reused.
+ *
+ * @param plugins - `EcoBuildPlugin` instances registered for this build.
+ * @param contextRoot - Project root used to resolve relative load paths.
+ * @param sourceTransforms - Optional app-owned transforms applied after a matching
+ * `onLoad` handler returns module contents. Browser builds pass
+ * {@link getAppSourceTransforms | app source transforms} here so metadata injection
+ * still runs on output rewritten by boundary/runtime plugins. Virtual modules,
+ * CSS, and asset loads are skipped.
  */
-export declare function createRolldownPluginBridge(plugins: EcoBuildPlugin[], contextRoot: string): Plugin[];
+export declare function createRolldownPluginBridge(plugins: EcoBuildPlugin[], contextRoot: string, sourceTransforms?: readonly EcoSourceTransform[]): Plugin[];