@ecopages/core 0.2.0-beta.8 → 0.2.1-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.8",
+  "version": "0.2.1-alpha.0",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -13,11 +13,11 @@
   "sideEffects": false,
   "repository": {
     "type": "git",
-    "url": "https://github.com/ecopages/ecopages.git",
+    "url": "git+https://github.com/ecopages/ecopages.git",
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.8",
+    "@ecopages/file-system": "0.2.1-alpha.0",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",

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

@@ -16,6 +16,7 @@
  *   the `set*` counterparts) — the supported way for runtime code to read
  *   and mutate the active adapter per `EcoPagesAppConfig`.
  */
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
 import type { EcoBuildPlugin } from './build-types.js';
 import { type AppBuildManifest } from './build-manifest.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
@@ -191,6 +192,20 @@ export interface BuildOptions {
      * bridge.
      */
     plugins?: EcoBuildPlugin[];
+    /**
+     * App-owned source transforms for browser-targeted Rolldown builds.
+     *
+     * @remarks
+     * Applied by the Rolldown plugin bridge after first-wins `onLoad` plugins
+     * produce module contents. This is the canonical browser/HMR path for
+     * `eco-component-meta` and other transforms registered in
+     * `appConfig.sourceTransforms`. Server builds continue to use loader plugins
+     * instead; this field is ignored unless `target` is `'browser'`.
+     *
+     * {@link BrowserBundleService} forwards {@link getAppSourceTransforms} here
+     * automatically.
+     */
+    sourceTransforms?: EcoSourceTransform[];
     /**
      * Escape hatch for backends that need to forward unknown options
      * to their underlying driver. Consumers should prefer the typed
@@ -468,6 +483,10 @@ export declare function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig):
  * Reads from the app's sealed build manifest. The browser-bundle
  * manifest is the source of truth for which plugins participate in the
  * browser bundle.
+ *
+ * Plugins whose `name` matches a registered {@link EcoSourceTransform} are
+ * excluded here because browser builds run those transforms via the Rolldown
+ * bridge post-load pass instead of as competing `onLoad` handlers.
  */
 export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
 /**

package/src/build/build-adapter.js

@@ -5,6 +5,7 @@ import {
   getBrowserBuildPlugins,
   getServerBuildPlugins
 } from "./build-manifest.js";
+import { getAppSourceTransforms } from "../plugins/source-transform.js";
 import { getJsxOwnershipPlugins } from "./jsx-ownership-plugins.js";
 import { createRolldownBuildAdapter } from "./rolldown-build-adapter.js";
 import { createRolldownDevBuildAdapter } from "./rolldown-dev-build-adapter.js";
@@ -200,7 +201,11 @@ function getAppServerBuildPlugins(appConfig) {
 }
 function getAppBrowserBuildPlugins(appConfig) {
   const manifest = getAppBuildManifest(appConfig);
-  return [...getBrowserBuildPlugins(manifest), ...getJsxOwnershipPlugins(appConfig)];
+  const sourceTransformNames = new Set(getAppSourceTransforms(appConfig).map((transform) => transform.name));
+  const browserPlugins = getBrowserBuildPlugins(manifest).filter(
+    (plugin) => !sourceTransformNames.has(plugin.name)
+  );
+  return [...browserPlugins, ...getJsxOwnershipPlugins(appConfig)];
 }
 function getAppBuildExecutor(appConfig) {
   return appConfig.runtime?.routeModuleBuildExecutor ?? appConfig.runtime?.buildExecutor ?? getAppBuildAdapter(appConfig);

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

@@ -201,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,

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,13 @@ 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.
+ *
+ * @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[];

package/src/build/rolldown-plugin-bridge.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { finalizeLoadResultWithSourceTransforms } from "./rolldown-source-transform-pass.js";
 import { escapeRegExp } from "./browser-runtime-plugin-helpers.js";
 const NAMESPACE_SEPARATOR = ":";
 function joinNamespace(namespace, value) {
@@ -124,7 +125,7 @@ function convertPluginOnResolveResult(result, importer, contextRoot) {
   }
   return partial;
 }
-function createRolldownPluginBridge(plugins, contextRoot) {
+function createRolldownPluginBridge(plugins, contextRoot, sourceTransforms = []) {
   if (plugins.length === 0) {
     return [];
   }
@@ -152,18 +153,29 @@ function createRolldownPluginBridge(plugins, contextRoot) {
     return void 0;
   };
   const loadHandler = async (id) => {
+    let loadResult;
     for (const { filter, callback } of loadRegistrations) {
       if (!filter.test(id)) {
         continue;
       }
-      const { namespace, path: sourcePath } = splitNamespace(id);
-      const result = await callback({ path: sourcePath, namespace });
+      const { namespace: namespace2, path: sourcePath2 } = splitNamespace(id);
+      const result = await callback({ path: sourcePath2, namespace: namespace2 });
       const converted = convertPluginOnLoadResult({ id }, result);
       if (converted !== void 0) {
-        return converted;
+        loadResult = converted;
+        break;
       }
     }
-    return void 0;
+    const { namespace, path: sourcePath } = splitNamespace(id);
+    return finalizeLoadResultWithSourceTransforms({
+      id,
+      namespace,
+      sourcePath,
+      loadResult,
+      sourceTransforms,
+      contextRoot,
+      inferModuleTypeFromPath: (filePath) => inferRolldownModuleTypeFromPath(filePath)
+    });
   };
   const plugin = {
     name: "ecopages-plugin-bridge",

package/src/build/rolldown-source-transform-pass.d.ts

@@ -0,0 +1,15 @@
+import type { LoadResult, SourceDescription } from 'rolldown';
+import { type EcoSourceTransform } from '../plugins/source-transform.js';
+/**
+ * Runs app-owned source transforms after first-wins `onLoad` plugins produce
+ * module contents for one Rolldown load request.
+ */
+export declare function finalizeLoadResultWithSourceTransforms(options: {
+    id: string;
+    namespace: string | undefined;
+    sourcePath: string;
+    loadResult: LoadResult | undefined;
+    sourceTransforms: readonly EcoSourceTransform[];
+    contextRoot: string;
+    inferModuleTypeFromPath: (filePath: string) => SourceDescription['moduleType'];
+}): Promise<LoadResult | undefined>;

package/src/build/rolldown-source-transform-pass.js

@@ -0,0 +1,58 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { applySourceTransforms, normalizeTransformId } from "../plugins/source-transform.js";
+const TRANSFORMABLE_SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mdx"]);
+function shouldApplySourceTransforms(namespace, sourcePath) {
+  if (namespace !== void 0) {
+    return false;
+  }
+  const normalizedPath = normalizeTransformId(sourcePath);
+  return TRANSFORMABLE_SOURCE_EXTENSIONS.has(path.extname(normalizedPath).toLowerCase());
+}
+function shouldTransformLoadedModule(moduleType) {
+  return moduleType !== "css" && moduleType !== "asset";
+}
+function applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, code) {
+  if (sourceTransforms.length === 0) {
+    return code;
+  }
+  return applySourceTransforms(sourceTransforms, code, sourcePath);
+}
+async function finalizeLoadResultWithSourceTransforms(options) {
+  const { id, namespace, sourcePath, loadResult, sourceTransforms, contextRoot, inferModuleTypeFromPath } = options;
+  if (!shouldApplySourceTransforms(namespace, sourcePath)) {
+    return loadResult;
+  }
+  if (typeof loadResult === "object" && loadResult !== null && "code" in loadResult && typeof loadResult.code === "string") {
+    if (!shouldTransformLoadedModule(loadResult.moduleType)) {
+      return loadResult;
+    }
+    const transformedCode2 = applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, loadResult.code);
+    if (transformedCode2 === loadResult.code) {
+      return loadResult;
+    }
+    return {
+      code: transformedCode2,
+      moduleType: loadResult.moduleType
+    };
+  }
+  if (loadResult !== void 0 || sourceTransforms.length === 0) {
+    return loadResult;
+  }
+  const normalizedPath = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(contextRoot, sourcePath);
+  if (!fileSystem.exists(normalizedPath)) {
+    return loadResult;
+  }
+  const originalCode = fileSystem.readFileSync(normalizedPath);
+  const transformedCode = applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, originalCode);
+  if (transformedCode === originalCode) {
+    return loadResult;
+  }
+  return {
+    code: transformedCode,
+    moduleType: inferModuleTypeFromPath(normalizedPath)
+  };
+}
+export {
+  finalizeLoadResultWithSourceTransforms
+};

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

@@ -250,7 +250,17 @@ export declare class ConfigBuilder {
     private compareVersions;
     /**
      * Initializes default loaders that are required for EcoPages to function.
-     * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+     *
+     * @remarks
+     * `eco-component-meta` is registered twice on purpose:
+     *
+     * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
+     *   runs these after first-wins `onLoad` plugins rewrite module source.
+     * - `loaders` keeps the same transform available to server-oriented builds
+     *   that still use competing `onLoad` handlers directly.
+     *
+     * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
+     * when the transform name is already present in `sourceTransforms`.
      */
     private initializeDefaultLoaders;
     private reviewBaseUrl;

package/src/config/config-builder.js

@@ -547,7 +547,17 @@ class ConfigBuilder {
   }
   /**
    * Initializes default loaders that are required for EcoPages to function.
-   * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+   *
+   * @remarks
+   * `eco-component-meta` is registered twice on purpose:
+   *
+   * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
+   *   runs these after first-wins `onLoad` plugins rewrite module source.
+   * - `loaders` keeps the same transform available to server-oriented builds
+   *   that still use competing `onLoad` handlers directly.
+   *
+   * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
+   * when the transform name is already present in `sourceTransforms`.
    */
   async initializeDefaultLoaders() {
     const componentMetaTransform = createEcoComponentMetaTransform({ config: this.config });

package/src/plugins/source-transform.d.ts

@@ -4,9 +4,21 @@ export interface EcoSourceTransformResult {
     code: string;
     map?: unknown;
 }
+/**
+ * Bundler-neutral source transform registered on {@link EcoPagesAppConfig.sourceTransforms}.
+ *
+ * @remarks
+ * Prefer this shape over a competing {@link EcoBuildPlugin} `onLoad` handler when
+ * the transform only rewrites module source. Browser/HMR builds run source
+ * transforms after first-wins `onLoad` plugins, so metadata injection and similar
+ * passes still run on rewritten output from boundary/runtime plugins.
+ */
 export interface EcoSourceTransform {
+    /** Stable transform name. Also used to dedupe loader plugins in browser builds. */
     name: string;
+    /** File-path filter tested against {@link normalizeTransformId | normalized ids}. */
     filter: RegExp;
+    /** Runs before default transforms, or after them when set to `post`. */
     enforce?: 'pre' | 'post';
     transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
 }
@@ -24,8 +36,27 @@ export declare function normalizeTransformId(id: string): string;
  * Applies one source transform if the normalized id matches its filter.
  */
 export declare function applySourceTransform(transform: EcoSourceTransform, code: string, id: string): EcoSourceTransformResult | string | undefined;
+/**
+ * Applies app-owned source transforms in deterministic `pre` → default → `post` order.
+ *
+ * @remarks
+ * Used by the Rolldown plugin bridge after `onLoad` plugins produce final module
+ * contents. Transforms that do not match `filter` are skipped; matching transforms
+ * are chained left-to-right on the current source string.
+ *
+ * @param transforms - App-owned transforms, usually from {@link getAppSourceTransforms}.
+ * @param code - Current module source.
+ * @param id - Module id forwarded to each transform after query/hash normalization.
+ * @returns The transformed source, or the original `code` when no transform matches.
+ */
+export declare function applySourceTransforms(transforms: readonly EcoSourceTransform[], code: string, id: string): string;
 /**
  * Adapts a source transform into the existing Ecopages build-plugin contract.
+ *
+ * @remarks
+ * Server-oriented builds and loader registration still use this adapter.
+ * Browser/HMR builds should register the transform in `appConfig.sourceTransforms`
+ * instead so the Rolldown bridge can run it after competing `onLoad` plugins.
  */
 export declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
 /**

package/src/plugins/source-transform.js

@@ -13,6 +13,27 @@ function applySourceTransform(transform, code, id) {
   }
   return transform.transform(code, normalizedId);
 }
+const SOURCE_TRANSFORM_ENFORCE_ORDER = {
+  pre: 0,
+  default: 1,
+  post: 2
+};
+function getSourceTransformEnforceOrder(transform) {
+  return SOURCE_TRANSFORM_ENFORCE_ORDER[transform.enforce ?? "default"];
+}
+function applySourceTransforms(transforms, code, id) {
+  let current = code;
+  for (const transform of [...transforms].sort(
+    (left, right) => getSourceTransformEnforceOrder(left) - getSourceTransformEnforceOrder(right)
+  )) {
+    const result = applySourceTransform(transform, current, id);
+    if (!result) {
+      continue;
+    }
+    current = typeof result === "string" ? result : result.code;
+  }
+  return current;
+}
 function inferLoaderFromPath(filePath) {
   const extension = path.extname(filePath).toLowerCase();
   switch (extension) {
@@ -56,13 +77,14 @@ function createVitePluginFromSourceTransform(transform) {
   };
 }
 function getAppSourceTransforms(appConfig) {
-  return Array.from(appConfig.sourceTransforms.values());
+  return appConfig.sourceTransforms ? Array.from(appConfig.sourceTransforms.values()) : [];
 }
 function createVitePluginsFromAppSourceTransforms(appConfig) {
   return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
 }
 export {
   applySourceTransform,
+  applySourceTransforms,
   createEcoBuildPluginFromSourceTransform,
   createVitePluginFromSourceTransform,
   createVitePluginsFromAppSourceTransforms,

package/src/services/assets/browser-bundle.service.d.ts

@@ -66,7 +66,8 @@ export declare class BrowserBundleService implements BrowserBundleExecutor {
      * @remarks
      * Browser defaults and app-owned browser build plugins are applied here so HMR
      * and runtime asset generation do not have to recreate that policy at each call
-     * site.
+     * site. Also forwards {@link getAppSourceTransforms | app source transforms} so
+     * metadata injection runs after boundary/runtime `onLoad` rewrites.
      */
     bundle(options: BrowserBundleOptions): Promise<BuildResult>;
     bundleGroupedEntries(entries: BrowserBundleGroupedEntry[], options: BrowserBundleGroupedOptions): Promise<BuildResult>;

package/src/services/assets/browser-bundle.service.js

@@ -5,6 +5,7 @@ import {
   getAppTranspileOptions
 } from "../../build/build-adapter.js";
 import { mergeEcoBuildPlugins } from "../../build/build-manifest.js";
+import { getAppSourceTransforms } from "../../plugins/source-transform.js";
 class BrowserBundleService {
   appConfig;
   /**
@@ -19,7 +20,8 @@ class BrowserBundleService {
    * @remarks
    * Browser defaults and app-owned browser build plugins are applied here so HMR
    * and runtime asset generation do not have to recreate that policy at each call
-   * site.
+   * site. Also forwards {@link getAppSourceTransforms | app source transforms} so
+   * metadata injection runs after boundary/runtime `onLoad` rewrites.
    */
   async bundle(options) {
     const { profile, excludeAppBuildPlugins, plugins, executor = "hmr", ...rawBuildOptions } = options;
@@ -29,7 +31,8 @@ class BrowserBundleService {
       ...rawBuildOptions,
       entrypoints: options.entrypoints,
       ...getAppTranspileOptions(this.appConfig, profile),
-      plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins)
+      plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins),
+      sourceTransforms: getAppSourceTransforms(this.appConfig)
     };
     const buildExecutor = executor === "build" ? getAppBuildExecutor(this.appConfig) : getAppHmrBuildExecutor(this.appConfig);
     return await buildExecutor.build(request);