@ecopages/core 0.2.0-beta.26 → 0.2.0-beta.27

package/src/build/runtime/build-request-policy.js

@@ -0,0 +1,46 @@
+import { getAppBrowserBuildPlugins, getAppServerBuildPlugins, getAppTranspileOptions } from "../build-adapter.js";
+import { resolveBuildProfileOptions } from "./build-profile-options.js";
+import { getJsxOwnershipPlugins } from "../browser/jsx-ownership-plugins.js";
+import { getAppSourceTransforms } from "../../plugins/source-transform.js";
+function resolveServerAppBuildPlugins(appConfig) {
+  return [...getAppServerBuildPlugins(appConfig), ...getJsxOwnershipPlugins(appConfig)];
+}
+function mergeCallerBuildPlugins(appPlugins, callerPlugins) {
+  if (!callerPlugins || callerPlugins.length === 0) {
+    return appPlugins;
+  }
+  const appByName = new Map(appPlugins.map((plugin) => [plugin.name, plugin]));
+  const uniqueCallerPlugins = callerPlugins.filter((plugin) => !appByName.has(plugin.name));
+  return [...uniqueCallerPlugins, ...appPlugins];
+}
+function createServerBuildRequest(appConfig, input) {
+  const profile = input.profile ?? "route-module";
+  const plugins = mergeCallerBuildPlugins(resolveServerAppBuildPlugins(appConfig), input.plugins);
+  const { plugins: _callerPlugins, profile: _profile, ...overrides } = input;
+  return {
+    ...resolveBuildProfileOptions(profile, appConfig, overrides),
+    ...overrides,
+    entrypoints: input.entrypoints,
+    ...plugins.length > 0 ? { plugins } : {}
+  };
+}
+function createBrowserBuildRequest(appConfig, input) {
+  const { profile, excludeAppBuildPlugins, plugins: callerPlugins, ...overrides } = input;
+  const appBrowserPlugins = getAppBrowserBuildPlugins(appConfig);
+  const filteredAppBrowserPlugins = excludeAppBuildPlugins && excludeAppBuildPlugins.length > 0 ? appBrowserPlugins.filter((plugin) => !excludeAppBuildPlugins.includes(plugin.name)) : appBrowserPlugins;
+  const plugins = mergeCallerBuildPlugins(filteredAppBrowserPlugins, callerPlugins);
+  return {
+    ...resolveBuildProfileOptions("browser-hmr", appConfig, overrides),
+    ...getAppTranspileOptions(appConfig, profile),
+    ...overrides,
+    entrypoints: input.entrypoints,
+    plugins,
+    sourceTransforms: getAppSourceTransforms(appConfig)
+  };
+}
+export {
+  createBrowserBuildRequest,
+  createServerBuildRequest,
+  mergeCallerBuildPlugins,
+  resolveServerAppBuildPlugins
+};

package/src/build/{build-runtime.d.ts → runtime/build-runtime.d.ts}

@@ -1,5 +1,5 @@
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import { type BuildExecutor } from './build-adapter.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { type BuildExecutor } from '../build-adapter.js';
 export type BuildProfile = 'server-entry' | 'route-module' | 'browser-hmr';
 export interface BuildRuntime {
     getProfile(profile: BuildProfile): BuildExecutor;
@@ -14,8 +14,12 @@ export declare function requireBuildRuntime(appConfig: EcoPagesAppConfig): Build
  * Installs profile-based build executors for one app instance.
  *
  * @remarks
- * All profiles use one-shot Rolldown. Server-entry stays serialized
- * single-flight; route-module and browser-HMR run in parallel.
+ * For Rolldown ownership, server-entry stays serialized single-flight while
+ * route-module and browser-HMR run in parallel one-shot builds. Vite-host
+ * profiles wrap a boundary marker and reject framework-owned build attempts.
+ * Profiles do not inject app plugins — assemble complete
+ * {@link BuildOptions} with {@link createServerBuildRequest} /
+ * {@link createBrowserBuildRequest} (or {@link BrowserBundleService}) first.
  */
 export declare function installBuildRuntime(appConfig: EcoPagesAppConfig): BuildRuntime;
 /**

package/src/build/{build-runtime.js → runtime/build-runtime.js}

@@ -1,10 +1,5 @@
 import { availableParallelism } from "node:os";
-import {
-  getAppBrowserBuildPlugins,
-  getAppBuildAdapter,
-  getAppServerBuildPlugins,
-  withBuildExecutorPlugins
-} from "./build-adapter.js";
+import { getAppBuildAdapter } from "../build-adapter.js";
 import { ParallelBuildExecutor } from "./parallel-build-executor.js";
 import { DedupingBuildExecutor } from "./deduping-build-executor.js";
 import { SerializedBuildExecutor } from "./serialized-build-executor.js";
@@ -23,12 +18,10 @@ class AppBuildRuntime {
   hmrExecutor;
   constructor(appConfig) {
     const adapter = getAppBuildAdapter(appConfig);
-    const serverPlugins = withBuildExecutorPlugins(adapter, () => getAppServerBuildPlugins(appConfig));
-    const browserPlugins = withBuildExecutorPlugins(adapter, () => getAppBrowserBuildPlugins(appConfig));
     const limit = resolveParallelismLimit();
-    this.serverEntryExecutor = new SerializedBuildExecutor(serverPlugins);
-    this.routeModuleExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(serverPlugins, limit));
-    this.hmrExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(browserPlugins, Math.min(3, limit)));
+    this.serverEntryExecutor = new SerializedBuildExecutor(adapter);
+    this.routeModuleExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(adapter, limit));
+    this.hmrExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(adapter, Math.min(3, limit)));
   }
   getProfile(profile) {
     switch (profile) {
@@ -40,6 +33,13 @@ class AppBuildRuntime {
         return this.hmrExecutor;
     }
   }
+  /**
+   * No-op for profile teardown.
+   *
+   * @remarks
+   * Rolldown-owned profiles use one-shot builds, and Vite-host profiles only
+   * wrap a boundary marker. Neither owns a long-lived engine to close.
+   */
   async dispose() {
   }
 }

package/src/build/{deduping-build-executor.d.ts → runtime/deduping-build-executor.d.ts}

@@ -1,12 +1,5 @@
-import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
-/**
- * Stable cache key for coalescing concurrent identical build requests.
- *
- * @remarks
- * Reuses the same material as route-module disk cache keys: normalized entrypoints,
- * outdir, splitting, JSX, and plugin setup fingerprints.
- */
-export declare function createBuildOptionsDedupeKey(options: BuildOptions): string;
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
+export { createBuildRequestIdentity, createBuildOptionsDedupeKey } from './build-request-identity.js';
 /**
  * In-flight build coalescing wrapper.
  *

package/src/build/runtime/deduping-build-executor.js

@@ -0,0 +1,34 @@
+import { createBuildRequestIdentity } from "./build-request-identity.js";
+import { createBuildRequestIdentity as createBuildRequestIdentity2, createBuildOptionsDedupeKey } from "./build-request-identity.js";
+class DedupingBuildExecutor {
+  inner;
+  inFlight = /* @__PURE__ */ new Map();
+  constructor(inner) {
+    this.inner = inner;
+  }
+  build(options) {
+    const key = createBuildRequestIdentity(options);
+    const existing = this.inFlight.get(key);
+    if (existing) {
+      return existing;
+    }
+    const buildPromise = this.inner.build(options).finally(() => {
+      if (this.inFlight.get(key) === buildPromise) {
+        this.inFlight.delete(key);
+      }
+    });
+    this.inFlight.set(key, buildPromise);
+    return buildPromise;
+  }
+  unwrap() {
+    return this.inner;
+  }
+  getInFlightCountForTests() {
+    return this.inFlight.size;
+  }
+}
+export {
+  DedupingBuildExecutor,
+  createBuildOptionsDedupeKey,
+  createBuildRequestIdentity2 as createBuildRequestIdentity
+};

package/src/build/{parallel-build-executor.d.ts → runtime/parallel-build-executor.d.ts}

@@ -1,4 +1,4 @@
-import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
 /**
  * Concurrency-limited build executor wrapper.
  *

package/src/build/{serialized-build-executor.d.ts → runtime/serialized-build-executor.d.ts}

@@ -1,4 +1,4 @@
-import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
 /**
  * FIFO-serialized build executor wrapper.
  *

package/src/config/config-builder.d.ts

@@ -3,7 +3,7 @@
  * @module
  */
 import { type BuildOwnership } from '../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig, RobotsPreference } from '../types/internal-types.js';
 import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';

package/src/diagnostics/startup-trace.d.ts

@@ -1,25 +1,72 @@
-export type StartupTracePhase = 'config-ready' | 'setupAppRuntimePlugins' | 'route-registry' | 'server-listen' | 'first-request-ssr';
+export type StartupTracePhase = 'config-ready' | 'setupAppRuntimePlugins' | 'route-registry' | 'server-listen' | 'first-byte' | 'first-page-browser-graph' | 'first-request-ssr' | 'client-transfer' | 'client-hydration';
+type PhaseRecord = {
+    durationMs: number;
+    wallMs: number;
+};
+export type StartupTraceReport = {
+    generatedAt: string;
+    runtime: string;
+    platform: string;
+    phases: Partial<Record<StartupTracePhase, PhaseRecord>>;
+    firstRequest?: {
+        path: string;
+        bundleCount: number;
+        clientBundleBytes: number;
+        graphBuildCount: number;
+        wallMs: number;
+    };
+    client?: {
+        requestCount: number;
+        transferredBytes: number;
+        hmrConnected: boolean;
+        hydrationReadyMs: number | null;
+    };
+};
 declare class StartupTrace {
-    private readonly phaseStarts;
+    private readonly phaseNesting;
     private readonly phases;
     private firstRequestPending;
     private firstRequestPath;
     private firstRequestBundleCount;
     private firstRequestClientBytes;
+    private firstRequestGraphBuildCount;
     private summaryEmitted;
+    private firstPageBrowserGraphEmitted;
+    private clientRequestCount;
+    private clientTransferredBytes;
+    private hmrConnected;
+    private hydrationReadyMs;
     isEnabled(): boolean;
     markPhaseStart(phase: StartupTracePhase): void;
     markPhaseEnd(phase: StartupTracePhase): void;
     markConfigReady(): void;
     markServerListening(): void;
     beginServerListen(): void;
+    markFirstByte(): void;
+    beginFirstByte(): void;
+    markFirstPageBrowserGraphReady(graphBuildCount?: number): void;
     recordBrowserBundle(outputs: Array<{
         path: string;
     }>): void;
+    recordClientTransfer(requestCount: number, transferredBytes: number): void;
+    beginClientTransfer(): void;
+    recordClientHydration(durationMs: number): void;
+    beginClientHydration(): void;
+    recordHmrConnected(): void;
     traceFirstRequest<T>(request: Request, handler: () => Promise<T>): Promise<T>;
     private emitFirstRequestSummary;
+    private writeJsonReport;
+    createReport(): StartupTraceReport;
     /** Resets mutable trace state for unit tests. */
     resetForTests(): void;
+    /**
+     * Resets only the first-request bundle counters.
+     *
+     * @remarks
+     * Used by tests that need to re-measure first-request browser bundle work
+     * without clearing earlier startup phase records.
+     */
+    resetFirstRequestCounters(): void;
 }
 export declare const startupTrace: StartupTrace;
 export {};

package/src/diagnostics/startup-trace.js

@@ -1,4 +1,6 @@
-import { statSync } from "node:fs";
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { availableParallelism } from "node:os";
 import { fileSystem } from "@ecopages/file-system";
 const LOG_PREFIX = "[ecopages:startup-trace]";
 function isStartupTraceEnabled() {
@@ -7,18 +9,35 @@ function isStartupTraceEnabled() {
 function wallMsSinceProcessStart() {
   return Math.round(process.uptime() * 1e3);
 }
+function resolveTraceBuildParallelism() {
+  const fromEnv = process.env.ECOPAGES_DEV_BUILD_PARALLELISM ?? process.env.ECOPAGES_DEV_HMR_PARALLELISM;
+  if (fromEnv) {
+    return fromEnv;
+  }
+  return String(Math.max(1, availableParallelism()));
+}
 function writeTraceLine(message) {
   process.stderr.write(`${LOG_PREFIX} ${message}
 `);
 }
+function resolveStartupTraceJsonPath() {
+  const configured = process.env.ECOPAGES_STARTUP_TRACE_JSON?.trim();
+  return configured && configured.length > 0 ? configured : void 0;
+}
 class StartupTrace {
-  phaseStarts = /* @__PURE__ */ new Map();
+  phaseNesting = /* @__PURE__ */ new Map();
   phases = /* @__PURE__ */ new Map();
   firstRequestPending = true;
   firstRequestPath;
   firstRequestBundleCount = 0;
   firstRequestClientBytes = 0;
+  firstRequestGraphBuildCount = 0;
   summaryEmitted = false;
+  firstPageBrowserGraphEmitted = false;
+  clientRequestCount = 0;
+  clientTransferredBytes = 0;
+  hmrConnected = false;
+  hydrationReadyMs = null;
   isEnabled() {
     return isStartupTraceEnabled();
   }
@@ -26,23 +45,34 @@ class StartupTrace {
     if (!isStartupTraceEnabled() || this.phases.has(phase)) {
       return;
     }
-    this.phaseStarts.set(phase, performance.now());
+    const nesting = this.phaseNesting.get(phase);
+    if (!nesting) {
+      this.phaseNesting.set(phase, { outerStart: performance.now(), depth: 1 });
+      return;
+    }
+    nesting.depth += 1;
   }
   markPhaseEnd(phase) {
     if (!isStartupTraceEnabled() || this.phases.has(phase)) {
       return;
     }
-    const startedAt = this.phaseStarts.get(phase);
-    if (startedAt === void 0) {
+    const nesting = this.phaseNesting.get(phase);
+    if (!nesting) {
       return;
     }
-    const durationMs = Math.round(performance.now() - startedAt);
+    nesting.depth -= 1;
+    if (nesting.depth > 0) {
+      return;
+    }
+    const durationMs = Math.round(performance.now() - nesting.outerStart);
     const record = {
       durationMs,
       wallMs: wallMsSinceProcessStart()
     };
     this.phases.set(phase, record);
+    this.phaseNesting.delete(phase);
     writeTraceLine(`phase=${phase} durationMs=${durationMs} wallMs=${record.wallMs}`);
+    this.writeJsonReport();
   }
   markConfigReady() {
     if (!isStartupTraceEnabled() || this.phases.has("config-ready")) {
@@ -53,7 +83,8 @@ class StartupTrace {
       wallMs: wallMsSinceProcessStart()
     };
     this.phases.set("config-ready", record);
-    writeTraceLine(`phase=config-ready wallMs=${record.wallMs}`);
+    writeTraceLine(`phase=config-ready wallMs=${record.wallMs} buildParallelism=${resolveTraceBuildParallelism()}`);
+    this.writeJsonReport();
   }
   markServerListening() {
     this.markPhaseEnd("server-listen");
@@ -61,6 +92,25 @@ class StartupTrace {
   beginServerListen() {
     this.markPhaseStart("server-listen");
   }
+  markFirstByte() {
+    if (!isStartupTraceEnabled() || this.phases.has("first-byte")) {
+      return;
+    }
+    this.markPhaseEnd("first-byte");
+  }
+  beginFirstByte() {
+    this.markPhaseStart("first-byte");
+  }
+  markFirstPageBrowserGraphReady(graphBuildCount) {
+    if (!isStartupTraceEnabled() || this.firstPageBrowserGraphEmitted) {
+      return;
+    }
+    if (typeof graphBuildCount === "number") {
+      this.firstRequestGraphBuildCount = graphBuildCount;
+    }
+    this.firstPageBrowserGraphEmitted = true;
+    this.markPhaseEnd("first-page-browser-graph");
+  }
   recordBrowserBundle(outputs) {
     if (!isStartupTraceEnabled() || !this.firstRequestPending) {
       return;
@@ -75,11 +125,39 @@ class StartupTrace {
       }
     }
   }
+  recordClientTransfer(requestCount, transferredBytes) {
+    if (!isStartupTraceEnabled()) {
+      return;
+    }
+    this.clientRequestCount = requestCount;
+    this.clientTransferredBytes = transferredBytes;
+    this.markPhaseEnd("client-transfer");
+  }
+  beginClientTransfer() {
+    this.markPhaseStart("client-transfer");
+  }
+  recordClientHydration(durationMs) {
+    if (!isStartupTraceEnabled()) {
+      return;
+    }
+    this.hydrationReadyMs = durationMs;
+    this.markPhaseEnd("client-hydration");
+  }
+  beginClientHydration() {
+    this.markPhaseStart("client-hydration");
+  }
+  recordHmrConnected() {
+    if (!isStartupTraceEnabled()) {
+      return;
+    }
+    this.hmrConnected = true;
+  }
   async traceFirstRequest(request, handler) {
     if (!isStartupTraceEnabled() || !this.firstRequestPending) {
       return handler();
     }
     this.firstRequestPath = new URL(request.url).pathname;
+    this.markPhaseStart("first-page-browser-graph");
     this.markPhaseStart("first-request-ssr");
     try {
       return await handler();
@@ -87,6 +165,7 @@ class StartupTrace {
       this.markPhaseEnd("first-request-ssr");
       this.emitFirstRequestSummary();
       this.firstRequestPending = false;
+      this.writeJsonReport();
     }
   }
   emitFirstRequestSummary() {
@@ -100,19 +179,72 @@ class StartupTrace {
         `path=${this.firstRequestPath ?? "unknown"}`,
         `bundleCount=${this.firstRequestBundleCount}`,
         `clientBundleBytes=${this.firstRequestClientBytes}`,
+        `graphBuildCount=${this.firstRequestGraphBuildCount}`,
         `wallMs=${wallMsSinceProcessStart()}`
       ].join(" ")
     );
   }
+  writeJsonReport() {
+    const outputPath = resolveStartupTraceJsonPath();
+    if (!outputPath) {
+      return;
+    }
+    const report = this.createReport();
+    mkdirSync(path.dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, JSON.stringify(report, null, 2), "utf-8");
+  }
+  createReport() {
+    const phases = {};
+    for (const [phase, record] of this.phases) {
+      phases[phase] = record;
+    }
+    return {
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      runtime: typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.version}`,
+      platform: process.platform,
+      phases,
+      firstRequest: this.firstRequestPath ? {
+        path: this.firstRequestPath,
+        bundleCount: this.firstRequestBundleCount,
+        clientBundleBytes: this.firstRequestClientBytes,
+        graphBuildCount: this.firstRequestGraphBuildCount,
+        wallMs: wallMsSinceProcessStart()
+      } : void 0,
+      client: this.clientRequestCount > 0 || this.hydrationReadyMs !== null ? {
+        requestCount: this.clientRequestCount,
+        transferredBytes: this.clientTransferredBytes,
+        hmrConnected: this.hmrConnected,
+        hydrationReadyMs: this.hydrationReadyMs
+      } : void 0
+    };
+  }
   /** Resets mutable trace state for unit tests. */
   resetForTests() {
-    this.phaseStarts.clear();
+    this.phaseNesting.clear();
     this.phases.clear();
     this.firstRequestPending = true;
     this.firstRequestPath = void 0;
     this.firstRequestBundleCount = 0;
     this.firstRequestClientBytes = 0;
+    this.firstRequestGraphBuildCount = 0;
     this.summaryEmitted = false;
+    this.firstPageBrowserGraphEmitted = false;
+    this.clientRequestCount = 0;
+    this.clientTransferredBytes = 0;
+    this.hmrConnected = false;
+    this.hydrationReadyMs = null;
+  }
+  /**
+   * Resets only the first-request bundle counters.
+   *
+   * @remarks
+   * Used by tests that need to re-measure first-request browser bundle work
+   * without clearing earlier startup phase records.
+   */
+  resetFirstRequestCounters() {
+    this.firstRequestBundleCount = 0;
+    this.firstRequestClientBytes = 0;
+    this.firstRequestGraphBuildCount = 0;
   }
 }
 const startupTrace = new StartupTrace();

package/src/hmr/client/hmr-runtime.js

@@ -68,7 +68,7 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
         return;
       }
       await import(url);
-      if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
+      if (await navigationRuntime.reloadCurrentPage({ clearCache: false, moduleUrl: url })) {
       }
     } catch (e) {
       console.error("[ecopages] Failed to apply HMR update:", e);

package/src/hmr/hmr-file-change-prep.d.ts

@@ -0,0 +1,10 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import { type AffectedGraphIdentity } from '../route-renderer/orchestration/page-browser-graph-session.js';
+export type HmrFileChangePreparation = {
+    affectedGraphIdentities: AffectedGraphIdentity[];
+    invalidatedGraphCount: number;
+};
+/**
+ * Invalidates affected Page Browser Graph records before HMR strategy dispatch.
+ */
+export declare function prepareHmrFileChange(appConfig: EcoPagesAppConfig, filePath: string): HmrFileChangePreparation;

package/src/hmr/hmr-file-change-prep.js

@@ -0,0 +1,17 @@
+import path from "node:path";
+import {
+  getAffectedPageBrowserGraphIdentities,
+  invalidatePageBrowserGraphSession
+} from "../route-renderer/orchestration/page-browser-graph-session.js";
+function prepareHmrFileChange(appConfig, filePath) {
+  const resolvedFilePath = path.resolve(filePath);
+  const affectedGraphIdentities = getAffectedPageBrowserGraphIdentities(appConfig, resolvedFilePath);
+  const invalidatedGraphCount = invalidatePageBrowserGraphSession(appConfig, resolvedFilePath);
+  return {
+    affectedGraphIdentities,
+    invalidatedGraphCount
+  };
+}
+export {
+  prepareHmrFileChange
+};

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

@@ -1,4 +1,4 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import { AliasResolverCache } from './alias-resolver-cache.js';
 export declare function createAliasResolverPlugin(projectRoot: string, options?: {
     cache?: AliasResolverCache;

package/src/plugins/eco-component-meta-plugin.d.ts

@@ -25,7 +25,7 @@
  *
  * @module eco-component-meta-plugin
  */
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import { type EcoSourceTransform, type EcoViteCompatiblePlugin } from './source-transform.js';
 /**

package/src/plugins/foreign-jsx-override-plugin.d.ts

@@ -1,4 +1,4 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 /**
  * Options for the shared foreign-JSX override build plugin.
  */

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

@@ -1,5 +1,5 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import { type BrowserRuntimeManifest } from '../build/browser-runtime-manifest.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
+import { type BrowserRuntimeManifest } from '../build/browser/browser-runtime-manifest.js';
 import type { EcoPagesAppConfig, IHmrManager } from '../types/internal-types.js';
 import type { HmrStrategy } from '../hmr/hmr-strategy.js';
 import type { EcoPagesElement } from '../types/public-types.js';
@@ -9,7 +9,7 @@ import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-p
 import type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
-export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
+export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/contracts/build-types.js';
 export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
 export type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
@@ -82,8 +82,11 @@ type RendererClass<C> = new (options: {
  *
  * Core owns lifecycle ordering. Integrations declare contributions through the
  * hooks on this class, while `ConfigBuilder.build()` and app startup decide when
- * those hooks run. For page-browser and document shaping, integrations should
- * prefer the contribution contracts re-exported from this module:
+ * those hooks run. Build plugins map to {@link AppBuildManifest} buckets:
+ * `plugins` → `runtimePlugins`, `browserBuildPlugins` → `browserBundlePlugins`,
+ * `browserRuntimeManifest` → client import rewrite map. For page-browser and
+ * document shaping, integrations should prefer the contribution contracts
+ * re-exported from this module:
  * `PageBrowserGraphContribution` / `PageBrowserGraphContributionContext` and
  * `HtmlDocumentContribution` / `HtmlDocumentContributionContext`.
  */
@@ -100,6 +103,14 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     protected assetProcessingService?: AssetProcessingService;
     protected hmrManager?: IHmrManager;
     runtimeOrigin: string;
+    /**
+     * Returns build plugins shared by server-oriented and browser-oriented builds.
+     *
+     * @remarks
+     * Collected into {@link AppBuildManifest.runtimePlugins} during config finalization.
+     * MDX loaders, virtual-module resolvers, and other transforms that must run during
+     * route-module transpile belong here—not in {@link browserBuildPlugins}.
+     */
     get plugins(): EcoBuildPlugin[];
     /**
      * Returns build plugins that should only apply to browser-oriented bundles.

package/src/plugins/integration-plugin.js

@@ -1,4 +1,6 @@
-import { createBrowserRuntimeManifest } from "../build/browser-runtime-manifest.js";
+import {
+  createBrowserRuntimeManifest
+} from "../build/browser/browser-runtime-manifest.js";
 import { AssetProcessingService } from "../services/assets/asset-processing-service/asset-processing.service.js";
 import { deepMerge } from "../utils/deep-merge.js";
 import { invariant } from "../utils/invariant.js";
@@ -23,6 +25,14 @@ class IntegrationPlugin {
   appConfig;
   assetProcessingService;
   hmrManager;
+  /**
+   * Returns build plugins shared by server-oriented and browser-oriented builds.
+   *
+   * @remarks
+   * Collected into {@link AppBuildManifest.runtimePlugins} during config finalization.
+   * MDX loaders, virtual-module resolvers, and other transforms that must run during
+   * route-module transpile belong here—not in {@link browserBuildPlugins}.
+   */
   get plugins() {
     return [];
   }