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

package/src/build/runtime-build-output-normalizer.js

@@ -0,0 +1,111 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const corePackageRequire = createRequire(new URL("../../package.json", import.meta.url));
+const appDeclaredPackageCache = /* @__PURE__ */ new Map();
+function tryResolveRuntimeImport(specifier, resolver) {
+  try {
+    return resolver.resolve(specifier);
+  } catch {
+    return void 0;
+  }
+}
+function isBareRuntimeImport(specifier) {
+  return !specifier.startsWith(".") && !path.isAbsolute(specifier) && !specifier.startsWith("/") && !specifier.startsWith("node:") && !specifier.startsWith("@/") && !specifier.startsWith("~/") && !specifier.startsWith("#") && !specifier.includes(":");
+}
+function getPackageNameFromSpecifier(specifier) {
+  if (specifier.startsWith("@")) {
+    return specifier.split("/").slice(0, 2).join("/");
+  }
+  return specifier.split("/")[0] ?? specifier;
+}
+function getDeclaredAppPackages(rootDir) {
+  const cacheKey = path.resolve(rootDir);
+  const cached = appDeclaredPackageCache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+  const packageJsonPath = path.resolve(rootDir, "package.json");
+  const declaredPackages = /* @__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 packageName of Object.keys(entries)) {
+        declaredPackages.add(packageName);
+      }
+    }
+  } catch {
+    appDeclaredPackageCache.set(cacheKey, declaredPackages);
+    return declaredPackages;
+  }
+  appDeclaredPackageCache.set(cacheKey, declaredPackages);
+  return declaredPackages;
+}
+function isDeclaredAppPackageImport(specifier, rootDir) {
+  return getDeclaredAppPackages(rootDir).has(getPackageNameFromSpecifier(specifier));
+}
+function rewriteRuntimeImportSpecifier(specifier, quote, rootDir) {
+  if (!isBareRuntimeImport(specifier)) {
+    return void 0;
+  }
+  if (isDeclaredAppPackageImport(specifier, rootDir)) {
+    return void 0;
+  }
+  const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);
+  if (!resolvedPath || !/\.(?:[cm]?[jt]s|tsx|jsx)$/u.test(resolvedPath)) {
+    return void 0;
+  }
+  return `${quote}${pathToFileURL(resolvedPath).href}${quote}`;
+}
+function rewriteRuntimeBuildOutputImports(code, rootDir) {
+  const rewriteSpecifier = (prefix, quote, specifier) => {
+    const rewrittenSpecifier = rewriteRuntimeImportSpecifier(specifier, quote, rootDir);
+    return `${prefix}${rewrittenSpecifier ?? `${quote}${specifier}${quote}`}`;
+  };
+  const withResolvedPackages = code.replace(
+    /(\bfrom\s+)(['"])([^'"\\]+)\2/g,
+    (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier)
+  ).replace(
+    /(\bimport\s+)(['"])([^'"\\]+)\2/g,
+    (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier)
+  ).replace(
+    /(\bimport\s*\(\s*)(['"])([^'"\\]+)\2/g,
+    (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier)
+  );
+  return withResolvedPackages.replace(
+    /(['"])(@oxc-project\/runtime\/(?:helpers(?:\/esm)?\/[^'"\\]+))\1/g,
+    (match, quote, specifier) => {
+      const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);
+      return resolvedPath ? `${quote}${pathToFileURL(resolvedPath).href}${quote}` : match;
+    }
+  );
+}
+function normalizeNodeRuntimeBuildOutputFile(filePath, rootDir) {
+  if (!/\.(?:[cm]?js)$/u.test(filePath)) {
+    return;
+  }
+  const fileSystem = corePackageRequire("node:fs");
+  if (!fileSystem.existsSync(filePath)) {
+    return;
+  }
+  const code = fileSystem.readFileSync(filePath, "utf-8");
+  const rewritten = rewriteRuntimeBuildOutputImports(code, rootDir);
+  if (rewritten !== code) {
+    fileSystem.writeFileSync(filePath, rewritten);
+  }
+}
+function normalizeNodeRuntimeBuildOutputs(outputPaths, rootDir) {
+  for (const outputPath of outputPaths) {
+    normalizeNodeRuntimeBuildOutputFile(outputPath, rootDir);
+  }
+}
+export {
+  isDeclaredAppPackageImport,
+  normalizeNodeRuntimeBuildOutputFile,
+  normalizeNodeRuntimeBuildOutputs
+};

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

@@ -0,0 +1,64 @@
+import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
+/**
+ * FIFO-serialized build executor wrapper.
+ *
+ * @remarks
+ * Wraps any `BuildExecutor` and ensures that no two builds run
+ * concurrently. The next build waits for the previous one to finish
+ * (success or failure) before starting.
+ *
+ * This is a bundler-agnostic primitive. It is unaware of bundler
+ * lifecycle events and exists purely to enforce one build at a time.
+ * Use it from the dev watch pipeline, the static preview path, or any
+ * caller that issues builds concurrently.
+ */
+/**
+ * FIFO-serialized wrapper around a {@link BuildExecutor}.
+ *
+ * Every `build()` call enqueues onto the wrapper's internal queue. A
+ * build only starts after the previous build's promise has settled.
+ */
+export declare class SerializedBuildExecutor implements BuildExecutor {
+    private readonly inner;
+    private tail;
+    constructor(inner: BuildExecutor);
+    /**
+     * Run a build through the serialized queue. The returned promise
+     * resolves with the inner executor's `BuildResult`. A rejected
+     * inner build does not block the queue — the next caller can
+     * proceed.
+     */
+    build(options: BuildOptions): Promise<BuildResult>;
+    /**
+     * Run an arbitrary async operation through the serialized queue.
+     *
+     * Use this when the work is not a `build()` call against a wrapped
+     * executor (e.g. when composing with a coordinator that needs to
+     * inject recovery around the inner call). The returned promise
+     * resolves with the operation's result. A rejected operation does
+     * not block the queue.
+     */
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Returns the wrapped executor. Tests use this to assert the
+     * delegation chain.
+     */
+    unwrap(): BuildExecutor;
+    /**
+     * Reset the queue to an empty state. Tests use this to recover
+     * from a poisoned tail.
+     */
+    resetForTests(): void;
+    /**
+     * Overrides the internal queue tail for fault-recovery tests. The
+     * supplied promise is awaited before the next enqueued operation
+     * starts.
+     */
+    setBuildQueueForTests(queue: Promise<unknown>): void;
+    /**
+     * Returns the current internal queue tail for fault-recovery
+     * tests. Tests await this to assert that recovery has cleared a
+     * wedged queue.
+     */
+    getBuildQueueForTests(): Promise<unknown>;
+}

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

@@ -0,0 +1,63 @@
+class SerializedBuildExecutor {
+  inner;
+  tail = Promise.resolve();
+  constructor(inner) {
+    this.inner = inner;
+  }
+  /**
+   * Run a build through the serialized queue. The returned promise
+   * resolves with the inner executor's `BuildResult`. A rejected
+   * inner build does not block the queue — the next caller can
+   * proceed.
+   */
+  build(options) {
+    return this.run(() => this.inner.build(options));
+  }
+  /**
+   * Run an arbitrary async operation through the serialized queue.
+   *
+   * Use this when the work is not a `build()` call against a wrapped
+   * executor (e.g. when composing with a coordinator that needs to
+   * inject recovery around the inner call). The returned promise
+   * resolves with the operation's result. A rejected operation does
+   * not block the queue.
+   */
+  run(operation) {
+    const next = this.tail.catch(() => void 0).then(() => operation());
+    this.tail = next.catch(() => void 0);
+    return next;
+  }
+  /**
+   * Returns the wrapped executor. Tests use this to assert the
+   * delegation chain.
+   */
+  unwrap() {
+    return this.inner;
+  }
+  /**
+   * Reset the queue to an empty state. Tests use this to recover
+   * from a poisoned tail.
+   */
+  resetForTests() {
+    this.tail = Promise.resolve();
+  }
+  /**
+   * Overrides the internal queue tail for fault-recovery tests. The
+   * supplied promise is awaited before the next enqueued operation
+   * starts.
+   */
+  setBuildQueueForTests(queue) {
+    this.tail = queue;
+  }
+  /**
+   * Returns the current internal queue tail for fault-recovery
+   * tests. Tests await this to assert that recovery has cleared a
+   * wedged queue.
+   */
+  getBuildQueueForTests() {
+    return this.tail;
+  }
+}
+export {
+  SerializedBuildExecutor
+};

package/src/build/server-side-css-shim-plugin.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Server-side CSS shim plugin for the bundler adapter.
+ *
+ * @remarks
+ * Page modules imported by the server (so the framework can read
+ * `getStaticProps` / `staticPaths` / page metadata) commonly have
+ * `import './style.css'` at the top. The bundler does not bundle
+ * CSS, and the server only needs the JS exports — the CSS itself
+ * is delivered to the browser via the page's `dependencies.stylesheets`
+ * declarations. This plugin:
+ *
+ * - Resolves `.css` imports to the absolute on-disk path.
+ * - Loads them and returns an empty ESM module with
+ *   `moduleSideEffects: true` so the bundler keeps the import in
+ *   the dependency graph without trying to bundle the bytes.
+ *
+ * The plugin is added by the adapter on every server-side build.
+ * Browser-side builds that want real CSS bundling should keep using
+ * a dedicated CSS pipeline (e.g. the postcss processor's output)
+ * and continue to declare stylesheets in `dependencies.stylesheets`
+ * — the shim is intentionally inert for those flows.
+ */
+type RolldownPluginLike = {
+    name: string;
+    resolveId: (source: string, importer: string | undefined) => Promise<string | null> | string | null;
+    load: (id: string) => Promise<{
+        code: string;
+        moduleType: 'js';
+        moduleSideEffects: boolean;
+    } | null> | {
+        code: string;
+        moduleType: 'js';
+        moduleSideEffects: boolean;
+    } | null;
+};
+/**
+ * Builds a Rolldown plugin that turns `.css` imports into no-op ESM
+ * modules while preserving the dependency graph.
+ */
+export declare function createServerSideCssShimPlugin(): RolldownPluginLike;
+export {};

package/src/build/server-side-css-shim-plugin.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+const CSS_PATH = /\.css$/u;
+const CSS_QUERY = "?ecopages-css-shim";
+function stripShimQuery(id) {
+  const queryIndex = id.indexOf("?");
+  return queryIndex === -1 ? id : id.slice(0, queryIndex);
+}
+function createServerSideCssShimPlugin() {
+  return {
+    name: "ecopages:server-side-css-shim",
+    async resolveId(source, importer) {
+      if (!CSS_PATH.test(source)) {
+        return null;
+      }
+      const resolved = importer ? path.resolve(path.dirname(importer), source) : path.resolve(source);
+      return existsSync(resolved) ? `${resolved}${CSS_QUERY}` : null;
+    },
+    async load(id) {
+      if (!id.endsWith(CSS_QUERY)) {
+        return null;
+      }
+      const realPath = stripShimQuery(id);
+      readFileSync(realPath, "utf-8");
+      return {
+        code: 'export default "";',
+        moduleType: "js",
+        moduleSideEffects: true
+      };
+    }
+  };
+}
+export {
+  createServerSideCssShimPlugin
+};

package/src/cache/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public cache exports for the bundler plugin chain.
+ *
+ * @module @ecopages/core/cache
+ */
+export { ModuleParseCache, moduleParseCache, cachedParseSync, type ModuleParseOptions } from './module-parse-cache.js';

package/src/cache/index.js

@@ -0,0 +1,6 @@
+import { ModuleParseCache, moduleParseCache, cachedParseSync } from "./module-parse-cache.js";
+export {
+  ModuleParseCache,
+  cachedParseSync,
+  moduleParseCache
+};

package/src/cache/module-parse-cache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Process-wide parse cache for `oxc-parser.parseSync`.
+ *
+ * @remarks
+ * Several build plugins (eco-component-meta, client-graph-boundary,
+ * browser-runtime) each call `parseSync` on the same source file with
+ * overlapping options. This cache memoizes the parse result keyed by
+ * `(absolute path, source, options)`. When the source is unchanged,
+ * subsequent calls return the cached result without re-parsing.
+ *
+ * The cache is LRU-bounded (10 000 entries) and key-stable across a
+ * single HMR session. It is **content-hashed** rather than
+ * mtime-hashed so that `touch`/`utimes` does not invalidate a
+ * still-valid parse.
+ */
+import { type ParseResult, type ParserOptions } from 'oxc-parser';
+export type ModuleParseOptions = ParserOptions & {
+    /**
+     * Optional parser language override. If omitted, derived from the file
+     * extension at lookup time. Set this explicitly if your caller already
+     * computed the language (avoids re-deriving inside the cache).
+     */
+    lang?: ParserOptions['lang'];
+};
+/**
+ * LRU-bounded module parse cache.
+ *
+ * Single instance shared across the process. Constructed lazily; use
+ * {@link moduleParseCache} for the default shared instance.
+ */
+export declare class ModuleParseCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private hits;
+    private misses;
+    constructor(maxEntries?: number);
+    /**
+     * Parse `source` for `filePath`, memoizing by (filePath, source, options).
+     *
+     * @returns the {@link ParseResult} from `oxc-parser.parseSync`.
+     */
+    getOrParse(filePath: string, source: string, options?: ModuleParseOptions): ParseResult;
+    /** Clear all cached entries. Useful in tests and on full-rebuild signals. */
+    clear(): void;
+    /** Current cache size (for observability). */
+    get size(): number;
+    /** Cumulative hit/miss counters (for observability). */
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        hitRate: number;
+    };
+}
+/**
+ * Default shared cache. Use this from plugin code so the cache is
+ * amortized across plugins and build invocations.
+ */
+export declare const moduleParseCache: ModuleParseCache;
+/**
+ * Drop-in replacement for `oxc-parser.parseSync` that uses the shared
+ * {@link moduleParseCache}. Use everywhere we currently call `parseSync`
+ * on user/source files during a build.
+ */
+export declare function cachedParseSync(filePath: string, source: string, options?: ModuleParseOptions): ParseResult;

package/src/cache/module-parse-cache.js

@@ -0,0 +1,75 @@
+import { parseSync } from "oxc-parser";
+import { rapidhash } from "../utils/hash.js";
+const DEFAULT_MAX_ENTRIES = 1e4;
+class ModuleParseCache {
+  entries = /* @__PURE__ */ new Map();
+  maxEntries;
+  hits = 0;
+  misses = 0;
+  constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+    if (maxEntries <= 0) {
+      throw new Error(`ModuleParseCache: maxEntries must be > 0, got ${maxEntries}`);
+    }
+    this.maxEntries = maxEntries;
+  }
+  /**
+   * Parse `source` for `filePath`, memoizing by (filePath, source, options).
+   *
+   * @returns the {@link ParseResult} from `oxc-parser.parseSync`.
+   */
+  getOrParse(filePath, source, options = {}) {
+    const hash = rapidhash(source);
+    const key = makeKey(filePath, hash, options);
+    const existing = this.entries.get(key);
+    if (existing && existing.hash === hash) {
+      this.hits += 1;
+      this.entries.delete(key);
+      this.entries.set(key, existing);
+      return existing.result;
+    }
+    this.misses += 1;
+    const result = parseSync(filePath, source, options);
+    this.entries.set(key, { hash, result });
+    if (this.entries.size > this.maxEntries) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.entries.delete(oldestKey);
+      }
+    }
+    return result;
+  }
+  /** Clear all cached entries. Useful in tests and on full-rebuild signals. */
+  clear() {
+    this.entries.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+  /** Current cache size (for observability). */
+  get size() {
+    return this.entries.size;
+  }
+  /** Cumulative hit/miss counters (for observability). */
+  stats() {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      size: this.entries.size,
+      hitRate: total === 0 ? 0 : this.hits / total
+    };
+  }
+}
+const moduleParseCache = new ModuleParseCache();
+function cachedParseSync(filePath, source, options = {}) {
+  return moduleParseCache.getOrParse(filePath, source, options);
+}
+function makeKey(filePath, sourceHash, options) {
+  const lang = options.lang ?? "";
+  const sourceType = options.sourceType ?? "";
+  return `${filePath} ${sourceHash.toString(36)} ${lang} ${sourceType}`;
+}
+export {
+  ModuleParseCache,
+  cachedParseSync,
+  moduleParseCache
+};

package/src/config/README.md

@@ -12,8 +12,9 @@ It is responsible for:
 
 - validating integration, processor, and loader registration
 - resolving semantic paths such as `html` and `404` templates
-- creating app-owned runtime state such as the build adapter, build executor, build manifest, dev graph service, runtime specifier registry, and Node runtime manifest
+- selecting explicit build ownership and creating app-owned runtime state such as the build adapter, build executor, build manifest, dev graph service, and remaining compatibility-only runtime state
 - enforcing runtime capability requirements before startup
+- carrying host-injected runtime dependencies only through abstract slots such as host module loaders, never through bundler-specific core defaults
 
 ## Main Files
 
@@ -23,9 +24,11 @@ It is responsible for:
 ## Ownership Rules
 
 - Integrations and processors declare contributions.
-- `ConfigBuilder.build()` decides ordering and validates compatibility.
+- `ConfigBuilder.build()` decides ordering, validates compatibility, and seals build ownership for the finalized app config.
 - Runtime startup reuses finalized config/build state; it should not recompute manifest ownership.
 
+App-owned is the default ownership path. Host-owned is explicit and should be selected during config construction when a host-driven compatibility flow must avoid silently falling back to app build execution.
+
 ## Output
 
 The result of this layer is a built `EcoPagesAppConfig` with resolved absolute paths and app-owned runtime services attached under `appConfig.runtime`.

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

@@ -2,11 +2,13 @@
  * This module contains the ConfigBuilder class, which is used to build the EcoPagesAppConfig object.
  * @module
  */
+import { type BuildOwnership } from '../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig, RobotsPreference } from '../internal-types.js';
-import type { IntegrationPlugin } from '../plugins/integration-plugin.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';
-import type { PageMetadataProps } from '../public-types.js';
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
+import type { PageMetadataProps } from '../types/public-types.js';
 import type { CacheConfig } from '../services/cache/cache.types.js';
 export declare const CONFIG_BUILDER_ERRORS: {
     readonly DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique";
@@ -25,15 +27,6 @@ type RuntimeKind = 'node' | 'bun';
  * Provides a fluent interface for setting various configuration options and managing
  * application settings.
  *
- * @example
- * ```typescript
- * const config = new ConfigBuilder()
- *   .setBaseUrl('https://example.com')
- *   .setRootDir('./myproject')
- *   .setSrcDir('source')
- *   .build();
- * ```
- *
  * @remarks
  * The ConfigBuilder follows the builder pattern and allows for:
  * - Setting directory paths for various components (pages, includes, layouts, etc.)
@@ -51,6 +44,7 @@ type RuntimeKind = 'node' | 'bun';
  * @throws {Error} When adding duplicate processors or loaders
  */
 export declare class ConfigBuilder {
+    private buildOwnership;
     config: EcoPagesAppConfig;
     /**
      * Sets the base URL for the application.
@@ -68,6 +62,29 @@ export declare class ConfigBuilder {
      * @returns The ConfigBuilder instance for method chaining
      */
     setRootDir(rootDir: string): this;
+    /**
+     * Sets which runtime path owns build execution for the finalized app config.
+     *
+     * @remarks
+     * Three ownership values are accepted:
+     *
+     * - `'rolldown'` (default): Ecopages runs builds through
+     *   {@link RolldownBuildAdapter}, creating a new `rolldown()` instance
+     *   per build. Best for one-shot production builds and benchmarks.
+     * - `'rolldown-dev'`: Ecopages runs builds through
+     *   {@link RolldownDevBuildAdapter}, which wraps Rolldown's experimental
+     *   `DevEngine` and reuses the cached module graph, resolver, and
+     *   transform cache across rebuilds. Best for HMR and watch mode where
+     *   the same entrypoints are rebuilt repeatedly.
+     * - `'vite-host'`: a host runtime owns the build. Ecopages exposes a
+     *   {@link ViteHostBuildAdapter} boundary marker that throws on direct
+     *   use. Select this only for host-driven compatibility flows where
+     *   core must not silently fall back to app build execution.
+     *
+     * Defaults to `'rolldown'` when {@link ConfigBuilder.build} runs
+     * without an explicit ownership.
+     */
+    setBuildOwnership(buildOwnership: BuildOwnership): this;
     /**
      * Sets the source directory relative to the root directory.
      * This directory contains all the source files for the application.
@@ -133,7 +150,7 @@ export declare class ConfigBuilder {
      * @param integrations - An array of integration plugins
      * @returns The ConfigBuilder instance for method chaining
      */
-    setIntegrations(integrations: IntegrationPlugin<unknown>[]): this;
+    setIntegrations(integrations: AnyIntegrationPlugin[]): this;
     /**
      * Sets the output directory for the built application.
      *
@@ -192,6 +209,11 @@ export declare class ConfigBuilder {
      * @returns The ConfigBuilder instance for method chaining
      */
     setLoaders(loaders: EcoBuildPlugin[]): this;
+    /**
+     * Sets the source transforms to use for transform-first bundlers such as Vite.
+     * This replaces any existing source transforms.
+     */
+    setSourceTransforms(sourceTransforms: EcoSourceTransform[]): this;
     /**
      * Adds a loader to the application.
      *
@@ -201,6 +223,12 @@ export declare class ConfigBuilder {
      * @throws Error if a loader with the same name already exists
      */
     addLoader(name: string, loader: EcoBuildPlugin): this;
+    /**
+     * Adds a source transform to the application.
+     *
+     * @throws Error if a source transform with the same name already exists.
+     */
+    addSourceTransform(name: string, sourceTransform: EcoSourceTransform): this;
     /**
      * Sets the cache configuration for ISR and page caching.
      *