@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.1

package/src/config/config-builder.js

@@ -1,613 +1,648 @@
-import path from "node:path";
-import {
-  DEFAULT_ECOPAGES_DIST_DIR,
-  DEFAULT_ECOPAGES_HOSTNAME,
-  DEFAULT_ECOPAGES_PORT,
-  DEFAULT_ECOPAGES_WORK_DIR
-} from "../config/constants.js";
-import {
-  collectConfiguredAppBuildManifestContributions,
-  createBuildAdapter,
-  setAppBuildAdapter,
-  setAppBuildExecutor,
-  updateAppBuildManifest
-} from "../build/build-adapter.js";
-import { GHTML_PLUGIN_NAME } from "../integrations/ghtml/ghtml.constants.js";
-import { ghtmlPlugin } from "../integrations/ghtml/ghtml.plugin.js";
-import { createEcoComponentMetaPlugin } from "../plugins/eco-component-meta-plugin.js";
-import { createEcoComponentMetaTransform } from "../plugins/eco-component-meta-plugin.js";
-import {
-  NoopEntrypointDependencyGraph,
-  setAppEntrypointDependencyGraph
-} from "../services/runtime-state/entrypoint-dependency-graph.service.js";
-import {
-  CounterServerInvalidationState,
-  setAppServerInvalidationState
-} from "../services/runtime-state/server-invalidation-state.service.js";
-import { invariant } from "../utils/invariant.js";
-import { appLogger } from "../global/app-logger.js";
-import { fileSystem } from "@ecopages/file-system";
-const CONFIG_BUILDER_ERRORS = {
-  DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique",
-  DUPLICATE_INTEGRATION_EXTENSIONS: "Integrations extensions must be unique",
-  MIXED_JSX_ENGINES: "Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).",
-  duplicateProcessorName: (name) => `Processor with name "${name}" already exists`,
-  duplicateLoaderName: (name) => `Loader with name "${name}" already exists`,
-  duplicateSemanticTemplate: (kind, matches) => `Multiple ${kind} templates found: ${matches.join(", ")}`,
-  incompatibleRuntimeCapability: (kind, name, runtime, reason) => `Cannot enable ${kind} "${name}" on ${runtime}: ${reason}`,
-  unsupportedRuntimeVersion: (kind, name, runtime, current, min) => `Cannot enable ${kind} "${name}" on ${runtime} ${current}: requires runtime version ${min} or newer`,
-  invalidRuntimeVersion: (kind, name, version) => `Cannot validate ${kind} "${name}" runtimeCapability.minRuntimeVersion "${version}" because it is not a dot-separated numeric version`
+/**
+ * This module contains the ConfigBuilder class, which is used to build the EcoPagesAppConfig object.
+ * @module
+ */
+import path from 'node:path';
+import { DEFAULT_ECOPAGES_DIST_DIR, DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, DEFAULT_ECOPAGES_WORK_DIR, } from '../config/constants.js';
+import { collectConfiguredAppBuildManifestContributions, createBuildAdapter, setAppBuildAdapter, updateAppBuildManifest, } from '../build/build-adapter.js';
+import { createEcoComponentMetaTransform } from '../plugins/eco-component-meta-plugin.js';
+import { NoopEntrypointDependencyGraph, setAppEntrypointDependencyGraph, } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
+import { CounterServerInvalidationState, setAppServerInvalidationState, } from '../services/runtime-state/server-invalidation-state.service.js';
+import { invariant } from '../utils/invariant.js';
+import { appLogger } from '../global/app-logger.js';
+import { fileSystem } from '@ecopages/file-system';
+export const CONFIG_BUILDER_ERRORS = {
+    DUPLICATE_INTEGRATION_NAMES: 'Integrations names must be unique',
+    DUPLICATE_INTEGRATION_EXTENSIONS: 'Integrations extensions must be unique',
+    MIXED_JSX_ENGINES: 'Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).',
+    duplicateProcessorName: (name) => `Processor with name "${name}" already exists`,
+    duplicateLoaderName: (name) => `Loader with name "${name}" already exists`,
+    duplicateSemanticTemplate: (kind, matches) => `Multiple ${kind} templates found: ${matches.join(', ')}`,
+    incompatibleRuntimeCapability: (kind, name, runtime, reason) => `Cannot enable ${kind} "${name}" on ${runtime}: ${reason}`,
+    unsupportedRuntimeVersion: (kind, name, runtime, current, min) => `Cannot enable ${kind} "${name}" on ${runtime} ${current}: requires runtime version ${min} or newer`,
+    invalidRuntimeVersion: (kind, name, version) => `Cannot validate ${kind} "${name}" runtimeCapability.minRuntimeVersion "${version}" because it is not a dot-separated numeric version`,
 };
-class ConfigBuilder {
-  buildOwnership = "rolldown";
-  config = {
-    baseUrl: "",
-    rootDir: ".",
-    srcDir: "src",
-    pagesDir: "pages",
-    includesDir: "includes",
-    componentsDir: "components",
-    layoutsDir: "layouts",
-    publicDir: "public",
-    robotsTxt: {
-      preferences: {
-        "*": []
-      }
-    },
-    integrations: [],
-    integrationsDependencies: [],
-    distDir: DEFAULT_ECOPAGES_DIST_DIR,
-    defaultMetadata: {
-      title: "Ecopages",
-      description: "This is a static site generated with Ecopages"
-    },
-    additionalWatchPaths: [],
-    templatesExt: [],
-    absolutePaths: {
-      config: "",
-      componentsDir: "",
-      distDir: "",
-      workDir: "",
-      includesDir: "",
-      layoutsDir: "",
-      pagesDir: "",
-      projectDir: "",
-      publicDir: "",
-      srcDir: "",
-      htmlTemplatePath: "",
-      error404TemplatePath: ""
-    },
-    processors: /* @__PURE__ */ new Map(),
-    loaders: /* @__PURE__ */ new Map(),
-    sourceTransforms: /* @__PURE__ */ new Map(),
-    workDir: DEFAULT_ECOPAGES_WORK_DIR
-  };
-  /**
-   * Sets the base URL for the application.
-   * This URL is used as the root URL for all pages and assets.
-   *
-   * @param baseUrl - The base URL for the application (e.g., 'https://example.com')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setBaseUrl(baseUrl) {
-    this.config.baseUrl = baseUrl;
-    return this;
-  }
-  /**
-   * Sets the root directory of the project.
-   * This is the base directory from which all other paths are resolved.
-   *
-   * @param rootDir - The root directory path
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setRootDir(rootDir) {
-    this.config.rootDir = rootDir;
-    return 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) {
-    this.buildOwnership = buildOwnership;
-    return this;
-  }
-  /**
-   * Sets the source directory relative to the root directory.
-   * This directory contains all the source files for the application.
-   *
-   * @param srcDir - The source directory name (default: 'src')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setSrcDir(srcDir) {
-    this.config.srcDir = srcDir;
-    return this;
-  }
-  /**
-   * Sets the pages directory relative to the source directory.
-   * This directory contains all the page files for the application.
-   *
-   * @param pagesDir - The pages directory name (default: 'pages')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setPagesDir(pagesDir) {
-    this.config.pagesDir = pagesDir;
-    return this;
-  }
-  /**
-   * Sets the includes directory relative to the source directory.
-   * This directory contains template includes and partials.
-   *
-   * @param includesDir - The includes directory name (default: 'includes')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setIncludesDir(includesDir) {
-    this.config.includesDir = includesDir;
-    return this;
-  }
-  /**
-   * Sets the components directory relative to the source directory.
-   * This directory contains reusable components.
-   *
-   * @param componentsDir - The components directory name (default: 'components')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setComponentsDir(componentsDir) {
-    this.config.componentsDir = componentsDir;
-    return this;
-  }
-  /**
-   * Sets the layouts directory relative to the source directory.
-   * This directory contains layout templates.
-   *
-   * @param layoutsDir - The layouts directory name (default: 'layouts')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setLayoutsDir(layoutsDir) {
-    this.config.layoutsDir = layoutsDir;
-    return this;
-  }
-  /**
-   * Sets the public directory relative to the source directory.
-   * This directory contains static assets that should be served as-is.
-   *
-   * @param publicDir - The public directory name (default: 'public')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setPublicDir(publicDir) {
-    this.config.publicDir = publicDir;
-    return this;
-  }
-  /**
-   * Sets the robots.txt configuration.
-   * This determines which paths are allowed/disallowed for search engines.
-   *
-   * @param robotsTxt - The robots.txt configuration object
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setRobotsTxt(robotsTxt) {
-    this.config.robotsTxt = robotsTxt;
-    return this;
-  }
-  /**
-   * Sets the integration plugins to use.
-   * These plugins provide additional functionality to the application.
-   *
-   * @param integrations - An array of integration plugins
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setIntegrations(integrations) {
-    this.config.integrations = integrations;
-    return this;
-  }
-  /**
-   * Sets the output directory for the built application.
-   *
-   * @param distDir - The distribution directory name (default: 'dist')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setDistDir(distDir) {
-    this.config.distDir = distDir;
-    return this;
-  }
-  /**
-   * Sets the internal work directory for runtime-only artifacts.
-   *
-   * @remarks
-   * Use this when deployable output should stay clean while Ecopages still
-   * needs a separate workspace for server transpilation caches, runtime
-   * manifests, and other internal build products.
-   *
-   * @param workDir - The internal work directory name
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setWorkDir(workDir) {
-    this.config.workDir = workDir;
-    return this;
-  }
-  /**
-   * Sets the default metadata for pages.
-   * This is used when a page doesn't specify its own metadata.
-   *
-   * @param defaultMetadata - The default metadata object
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setDefaultMetadata(defaultMetadata) {
-    this.config.defaultMetadata = {
-      ...this.config.defaultMetadata,
-      ...defaultMetadata
+/**
+ * A builder class for creating and configuring EcoPages application configuration.
+ * Provides a fluent interface for setting various configuration options and managing
+ * application settings.
+ *
+ * @remarks
+ * The ConfigBuilder follows the builder pattern and allows for:
+ * - Setting directory paths for various components (pages, includes, layouts, etc.)
+ * - Configuring templates and includes
+ * - Managing integrations and plugins
+ * - Setting up processors and loaders
+ * - Configuring API handlers
+ * - Managing metadata and robots.txt preferences
+ *
+ * All setter methods return the instance of the builder for method chaining.
+ * The configuration is finalized by calling the `build()` method, which performs
+ * validation and initialization of the configuration.
+ *
+ * @throws {Error} When building configuration without required fields (e.g., baseUrl)
+ * @throws {Error} When adding duplicate processors or loaders
+ */
+export class ConfigBuilder {
+    buildOwnership = 'rolldown';
+    config = {
+        baseUrl: '',
+        rootDir: '.',
+        srcDir: 'src',
+        pagesDir: 'pages',
+        includesDir: 'includes',
+        componentsDir: 'components',
+        layoutsDir: 'layouts',
+        publicDir: 'public',
+        robotsTxt: {
+            preferences: {
+                '*': [],
+            },
+        },
+        sitemap: {
+            enabled: false,
+            fileName: 'sitemap.xml',
+            extraUrls: [],
+            exclude: [],
+        },
+        integrations: [],
+        integrationsDependencies: [],
+        distDir: DEFAULT_ECOPAGES_DIST_DIR,
+        defaultMetadata: {
+            title: 'Ecopages',
+            description: 'This is a static site generated with Ecopages',
+        },
+        additionalWatchPaths: [],
+        devPrewarmPaths: [],
+        devPrewarmBeforeReadyPaths: [],
+        templatesExt: [],
+        absolutePaths: {
+            config: '',
+            componentsDir: '',
+            distDir: '',
+            workDir: '',
+            includesDir: '',
+            layoutsDir: '',
+            pagesDir: '',
+            projectDir: '',
+            publicDir: '',
+            srcDir: '',
+            htmlTemplatePath: '',
+            error404TemplatePath: '',
+            error500TemplatePath: '',
+        },
+        processors: new Map(),
+        loaders: new Map(),
+        sourceTransforms: new Map(),
+        workDir: DEFAULT_ECOPAGES_WORK_DIR,
     };
-    return this;
-  }
-  /**
-   * Sets additional paths to watch for changes during development.
-   *
-   * @param additionalWatchPaths - An array of additional paths to watch
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setAdditionalWatchPaths(additionalWatchPaths) {
-    this.config.additionalWatchPaths = additionalWatchPaths;
-    return this;
-  }
-  /**
-   * Sets the processors to use for the application.
-   * This replaces any existing processors.
-   *
-   * @param processors - An array of processors
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setProcessors(processors) {
-    this.config.processors.clear();
-    for (const processor of processors) {
-      this.addProcessor(processor);
-    }
-    return this;
-  }
-  /**
-   * Adds a processor to the application.
-   *
-   * @param processor - The processor to add
-   * @returns The ConfigBuilder instance for method chaining
-   * @throws Error if a processor with the same name already exists
-   */
-  addProcessor(processor) {
-    if (this.config.processors.has(processor.name)) {
-      throw new Error(CONFIG_BUILDER_ERRORS.duplicateProcessorName(processor.name));
-    }
-    this.config.processors.set(processor.name, processor);
-    return this;
-  }
-  /**
-   * Sets the loaders to use for the application.
-   * This replaces any existing loaders.
-   *
-   * @param loaders - An array of build plugins to use as loaders
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setLoaders(loaders) {
-    this.config.loaders.clear();
-    for (const loader of loaders) {
-      this.addLoader(loader.name, loader);
-    }
-    return this;
-  }
-  /**
-   * Sets the source transforms to use for transform-first bundlers such as Vite.
-   * This replaces any existing source transforms.
-   */
-  setSourceTransforms(sourceTransforms) {
-    this.config.sourceTransforms.clear();
-    for (const sourceTransform of sourceTransforms) {
-      this.addSourceTransform(sourceTransform.name, sourceTransform);
-    }
-    return this;
-  }
-  /**
-   * Adds a loader to the application.
-   *
-   * @param name - The name of the loader
-   * @param loader - The build plugin to use as a loader
-   * @returns The ConfigBuilder instance for method chaining
-   * @throws Error if a loader with the same name already exists
-   */
-  addLoader(name, loader) {
-    if (this.config.loaders.has(name)) {
-      throw new Error(CONFIG_BUILDER_ERRORS.duplicateLoaderName(name));
-    }
-    this.config.loaders.set(name, loader);
-    return this;
-  }
-  /**
-   * Adds a source transform to the application.
-   *
-   * @throws Error if a source transform with the same name already exists.
-   */
-  addSourceTransform(name, sourceTransform) {
-    if (this.config.sourceTransforms.has(name)) {
-      throw new Error(CONFIG_BUILDER_ERRORS.duplicateLoaderName(name));
-    }
-    this.config.sourceTransforms.set(name, sourceTransform);
-    return this;
-  }
-  /**
-   * Sets the cache configuration for ISR and page caching.
-   *
-   * @param cacheConfig - The cache configuration object
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setCacheConfig(cacheConfig) {
-    this.config.cache = cacheConfig;
-    return this;
-  }
-  setExperimental(experimental) {
-    this.config.experimental = experimental;
-    return this;
-  }
-  createAbsolutePaths(config) {
-    const { srcDir, componentsDir, includesDir, layoutsDir, pagesDir, publicDir, distDir, workDir } = config;
-    const projectDir = config.rootDir;
-    const absoluteSrcDir = path.resolve(projectDir, srcDir);
-    const absoluteDistDir = path.resolve(projectDir, distDir);
-    const absoluteWorkDir = path.resolve(projectDir, workDir);
-    const absoluteIncludesDir = path.join(absoluteSrcDir, includesDir);
-    const absolutePagesDir = path.join(absoluteSrcDir, pagesDir);
-    this.config.absolutePaths = {
-      config: path.join(projectDir, "eco.config.ts"),
-      projectDir,
-      srcDir: absoluteSrcDir,
-      distDir: absoluteDistDir,
-      workDir: absoluteWorkDir,
-      componentsDir: path.join(absoluteSrcDir, componentsDir),
-      includesDir: absoluteIncludesDir,
-      layoutsDir: path.join(absoluteSrcDir, layoutsDir),
-      pagesDir: absolutePagesDir,
-      publicDir: path.join(absoluteSrcDir, publicDir),
-      htmlTemplatePath: this.resolveSemanticTemplatePath({
-        dirPath: absoluteIncludesDir,
-        basename: "html"
-      }),
-      error404TemplatePath: this.resolveSemanticTemplatePath({
-        dirPath: absolutePagesDir,
-        basename: "404"
-      })
-    };
-    return this;
-  }
-  resolveSemanticTemplatePath({ dirPath, basename }) {
-    const extensions = this.config.templatesExt.length > 0 ? this.config.templatesExt : [".ghtml.ts"];
-    const matches = extensions.map((extension) => path.join(dirPath, `${basename}${extension}`)).filter((candidate) => fileSystem.exists(candidate));
-    invariant(matches.length <= 1, CONFIG_BUILDER_ERRORS.duplicateSemanticTemplate(basename, matches));
-    if (matches.length === 1) {
-      return matches[0];
-    }
-    return path.join(dirPath, `${basename}${extensions[0]}`);
-  }
-  createIntegrationTemplatesExt(integrations) {
-    const integrationName = integrations.map((integration) => integration.name);
-    const uniqueName = new Set(integrationName);
-    invariant(integrationName.length === uniqueName.size, CONFIG_BUILDER_ERRORS.DUPLICATE_INTEGRATION_NAMES);
-    const hasKitaJs = uniqueName.has("kitajs");
-    const hasReact = uniqueName.has("react");
-    if (hasKitaJs && hasReact) {
-      appLogger.debug(CONFIG_BUILDER_ERRORS.MIXED_JSX_ENGINES);
-    }
-    const integrationsExtensions = integrations.flatMap((integration) => integration.extensions);
-    const uniqueExtensions = new Set(integrationsExtensions);
-    invariant(
-      integrationsExtensions.length === uniqueExtensions.size,
-      CONFIG_BUILDER_ERRORS.DUPLICATE_INTEGRATION_EXTENSIONS
-    );
-    this.config.templatesExt = integrationsExtensions;
-  }
-  initializeProcessors() {
-    for (const processor of this.config.processors.values()) {
-      processor.setContext(this.config);
-    }
-  }
-  validateRuntimeCapabilities() {
-    const runtimeEnvironment = this.detectRuntimeEnvironment();
-    const contributors = [
-      ...this.config.integrations.map((integration) => ({
-        kind: "integration",
-        name: integration.name,
-        runtimeCapability: integration.runtimeCapability
-      })),
-      ...Array.from(this.config.processors.values(), (processor) => ({
-        kind: "processor",
-        name: processor.name,
-        runtimeCapability: processor.runtimeCapability
-      }))
-    ];
-    for (const contributor of contributors) {
-      this.validateRuntimeCapability(contributor, runtimeEnvironment);
-    }
-  }
-  validateRuntimeCapability(contributor, environment) {
-    const declaration = contributor.runtimeCapability;
-    if (!declaration) {
-      return;
-    }
-    for (const tag of declaration.tags) {
-      if (environment.supportedTags.has(tag)) {
-        continue;
-      }
-      throw new Error(
-        CONFIG_BUILDER_ERRORS.incompatibleRuntimeCapability(
-          contributor.kind,
-          contributor.name,
-          environment.runtime,
-          this.describeUnsupportedRuntimeTag(tag)
-        )
-      );
-    }
-    if (!declaration.minRuntimeVersion) {
-      return;
-    }
-    const minVersion = this.parseVersion(declaration.minRuntimeVersion);
-    if (!minVersion) {
-      throw new Error(
-        CONFIG_BUILDER_ERRORS.invalidRuntimeVersion(
-          contributor.kind,
-          contributor.name,
-          declaration.minRuntimeVersion
-        )
-      );
-    }
-    const currentVersion = this.parseVersion(environment.version);
-    if (!currentVersion) {
-      return;
-    }
-    if (this.compareVersions(currentVersion, minVersion) >= 0) {
-      return;
-    }
-    throw new Error(
-      CONFIG_BUILDER_ERRORS.unsupportedRuntimeVersion(
-        contributor.kind,
-        contributor.name,
-        environment.runtime,
-        environment.version,
-        declaration.minRuntimeVersion
-      )
-    );
-  }
-  detectRuntimeEnvironment() {
-    const bunVersion = this.getBunVersion();
-    if (bunVersion) {
-      return {
-        runtime: "bun",
-        version: bunVersion,
-        supportedTags: /* @__PURE__ */ new Set([
-          "bun-only",
-          "node-compatible",
-          "requires-native-bun-api",
-          "requires-node-builtins"
-        ])
-      };
-    }
-    return {
-      runtime: "node",
-      version: process.versions.node,
-      supportedTags: /* @__PURE__ */ new Set(["node-compatible", "requires-node-builtins"])
-    };
-  }
-  getBunVersion() {
-    const bun = globalThis;
-    return typeof bun.Bun?.version === "string" ? bun.Bun.version : void 0;
-  }
-  describeUnsupportedRuntimeTag(tag) {
-    switch (tag) {
-      case "bun-only":
-        return "it is Bun-only";
-      case "requires-native-bun-api":
-        return "it requires the native Bun API";
-      case "requires-node-builtins":
-        return "it requires Node builtins";
-      case "node-compatible":
-        return "it requires a Node-compatible runtime";
-    }
-  }
-  parseVersion(version) {
-    const normalized = version.trim().replace(/^v/i, "");
-    if (!/^\d+(?:\.\d+)*$/.test(normalized)) {
-      return void 0;
-    }
-    return normalized.split(".").map((segment) => Number(segment));
-  }
-  compareVersions(left, right) {
-    const maxLength = Math.max(left.length, right.length);
-    for (let index = 0; index < maxLength; index += 1) {
-      const leftValue = left[index] ?? 0;
-      const rightValue = right[index] ?? 0;
-      if (leftValue > rightValue) {
-        return 1;
-      }
-      if (leftValue < rightValue) {
-        return -1;
-      }
-    }
-    return 0;
-  }
-  /**
-   * Initializes default loaders that are required for EcoPages to function.
-   *
-   * @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 });
-    if (!this.config.sourceTransforms.has(componentMetaTransform.name)) {
-      this.config.sourceTransforms.set(componentMetaTransform.name, componentMetaTransform);
-    }
-    const componentMetaPlugin = createEcoComponentMetaPlugin({ config: this.config });
-    if (!this.config.loaders.has(componentMetaPlugin.name)) {
-      this.config.loaders.set(componentMetaPlugin.name, componentMetaPlugin);
-    }
-  }
-  reviewBaseUrl(baseUrl) {
-    if (baseUrl) {
-      this.config.baseUrl = baseUrl;
-      return;
-    }
-    const envBaseUrl = process.env.ECOPAGES_BASE_URL;
-    if (envBaseUrl) {
-      this.config.baseUrl = envBaseUrl;
-    } else if (!this.config.baseUrl) {
-      this.config.baseUrl = `http://${DEFAULT_ECOPAGES_HOSTNAME}:${DEFAULT_ECOPAGES_PORT}`;
-    }
-  }
-  /**
-   * Builds and returns the final configuration object.
-   * This performs validation and initialization of the configuration.
-   *
-   * @returns A promise that resolves to the final EcoPagesAppConfig
-   * @throws Error if required configuration is missing (e.g., baseUrl)
-   */
-  async build() {
-    this.reviewBaseUrl(this.config.baseUrl);
-    if (!this.config.integrations.some((integration) => integration.name === GHTML_PLUGIN_NAME)) {
-      this.config.integrations.push(ghtmlPlugin());
-    }
-    this.createIntegrationTemplatesExt(this.config.integrations);
-    this.createAbsolutePaths(this.config);
-    await this.initializeDefaultLoaders();
-    this.initializeProcessors();
-    this.validateRuntimeCapabilities();
-    const buildAdapter = createBuildAdapter({ ownership: this.buildOwnership });
-    setAppBuildAdapter(this.config, buildAdapter);
-    updateAppBuildManifest(this.config, await collectConfiguredAppBuildManifestContributions(this.config));
-    setAppServerInvalidationState(this.config, new CounterServerInvalidationState());
-    setAppEntrypointDependencyGraph(this.config, new NoopEntrypointDependencyGraph());
-    setAppBuildExecutor(this.config, buildAdapter);
-    return this.config;
-  }
+    /**
+     * Sets the base URL for the application.
+     * This URL is used as the root URL for all pages and assets.
+     *
+     * @param baseUrl - The base URL for the application (e.g., 'https://example.com')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setBaseUrl(baseUrl) {
+        this.config.baseUrl = baseUrl;
+        return this;
+    }
+    /**
+     * Sets the root directory of the project.
+     * This is the base directory from which all other paths are resolved.
+     *
+     * @param rootDir - The root directory path
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setRootDir(rootDir) {
+        this.config.rootDir = rootDir;
+        return 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.
+     * - `'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) {
+        this.buildOwnership = buildOwnership;
+        return this;
+    }
+    /**
+     * Sets the source directory relative to the root directory.
+     * This directory contains all the source files for the application.
+     *
+     * @param srcDir - The source directory name (default: 'src')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setSrcDir(srcDir) {
+        this.config.srcDir = srcDir;
+        return this;
+    }
+    /**
+     * Sets the pages directory relative to the source directory.
+     * This directory contains all the page files for the application.
+     *
+     * @param pagesDir - The pages directory name (default: 'pages')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setPagesDir(pagesDir) {
+        this.config.pagesDir = pagesDir;
+        return this;
+    }
+    /**
+     * Sets the includes directory relative to the source directory.
+     * This directory contains template includes and partials.
+     *
+     * @param includesDir - The includes directory name (default: 'includes')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setIncludesDir(includesDir) {
+        this.config.includesDir = includesDir;
+        return this;
+    }
+    /**
+     * Sets the components directory relative to the source directory.
+     * This directory contains reusable components.
+     *
+     * @param componentsDir - The components directory name (default: 'components')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setComponentsDir(componentsDir) {
+        this.config.componentsDir = componentsDir;
+        return this;
+    }
+    /**
+     * Sets the layouts directory relative to the source directory.
+     * This directory contains layout templates.
+     *
+     * @param layoutsDir - The layouts directory name (default: 'layouts')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setLayoutsDir(layoutsDir) {
+        this.config.layoutsDir = layoutsDir;
+        return this;
+    }
+    /**
+     * Sets the public directory relative to the source directory.
+     * This directory contains static assets that should be served as-is.
+     *
+     * @param publicDir - The public directory name (default: 'public')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setPublicDir(publicDir) {
+        this.config.publicDir = publicDir;
+        return this;
+    }
+    /**
+     * Sets the robots.txt configuration.
+     * This determines which paths are allowed/disallowed for search engines.
+     *
+     * @param robotsTxt - The robots.txt configuration object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setRobotsTxt(robotsTxt) {
+        this.config.robotsTxt = robotsTxt;
+        return this;
+    }
+    /**
+     * Sets automatic sitemap.xml generation during static export.
+     *
+     * @remarks
+     * Merged over `{ enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }`.
+     * Existing apps stay unchanged until `enabled: true` is set. Page-level
+     * `metadata.robots.index: false` and metadata resolution failures are handled
+     * during static generation (not by this config merge).
+     */
+    setSitemap(sitemap) {
+        const defaults = {
+            enabled: false,
+            fileName: 'sitemap.xml',
+            extraUrls: [],
+            exclude: [],
+        };
+        this.config.sitemap = {
+            ...defaults,
+            ...this.config.sitemap,
+            ...sitemap,
+            extraUrls: sitemap.extraUrls ?? this.config.sitemap.extraUrls ?? defaults.extraUrls,
+            exclude: sitemap.exclude ?? this.config.sitemap.exclude ?? defaults.exclude,
+        };
+        return this;
+    }
+    /**
+     * Configures the in-browser development toolbar shown during watch mode.
+     *
+     * @remarks
+     * Requires `package` to point at a browser bootstrap module installed in the app.
+     * Prefer {@link defineDevTool} for config authoring.
+     */
+    setDevToolbar(devToolbar) {
+        this.config.devToolbar = {
+            ...this.config.devToolbar,
+            ...devToolbar,
+        };
+        return this;
+    }
+    /**
+     * Sets the integration plugins to use.
+     * Rendering apps must register at least one Integration that owns their route file extensions.
+     *
+     * @param integrations - An array of integration plugins. Pass an empty array for an intentionally integration-free config.
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setIntegrations(integrations) {
+        this.config.integrations = integrations;
+        return this;
+    }
+    /**
+     * Sets the output directory for the built application.
+     *
+     * @param distDir - The distribution directory name (default: 'dist')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setDistDir(distDir) {
+        this.config.distDir = distDir;
+        return this;
+    }
+    /**
+     * Sets the internal work directory for runtime-only artifacts.
+     *
+     * @remarks
+     * Use this when deployable output should stay clean while Ecopages still
+     * needs a separate workspace for server transpilation caches, runtime
+     * manifests, and other internal build products.
+     *
+     * @param workDir - The internal work directory name
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setWorkDir(workDir) {
+        this.config.workDir = workDir;
+        return this;
+    }
+    /**
+     * Sets the default metadata for pages.
+     * This is used when a page doesn't specify its own metadata.
+     *
+     * @param defaultMetadata - The default metadata object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setDefaultMetadata(defaultMetadata) {
+        this.config.defaultMetadata = {
+            ...this.config.defaultMetadata,
+            ...defaultMetadata,
+        };
+        return this;
+    }
+    /**
+     * Sets additional paths to watch for changes during development.
+     *
+     * @param additionalWatchPaths - An array of additional paths to watch
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setAdditionalWatchPaths(additionalWatchPaths) {
+        this.config.additionalWatchPaths = additionalWatchPaths;
+        return this;
+    }
+    /**
+     * Sets static paths to SSR-prewarm in development.
+     *
+     * @param devPrewarmPaths - Absolute URL pathnames such as `/` or `/docs`.
+     * @returns The ConfigBuilder instance for method chaining.
+     */
+    setDevPrewarmPaths(devPrewarmPaths) {
+        this.config.devPrewarmPaths = devPrewarmPaths;
+        return this;
+    }
+    /**
+     * Sets static paths to SSR-prewarm before the development server reports ready.
+     *
+     * @param devPrewarmBeforeReadyPaths - Critical absolute URL pathnames such as `/`.
+     * @returns The ConfigBuilder instance for method chaining.
+     */
+    setDevPrewarmBeforeReadyPaths(devPrewarmBeforeReadyPaths) {
+        this.config.devPrewarmBeforeReadyPaths = devPrewarmBeforeReadyPaths;
+        return this;
+    }
+    /**
+     * Sets the processors to use for the application.
+     * This replaces any existing processors.
+     *
+     * @param processors - An array of processors
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setProcessors(processors) {
+        this.config.processors.clear();
+        for (const processor of processors) {
+            this.addProcessor(processor);
+        }
+        return this;
+    }
+    /**
+     * Adds a processor to the application.
+     *
+     * @param processor - The processor to add
+     * @returns The ConfigBuilder instance for method chaining
+     * @throws Error if a processor with the same name already exists
+     */
+    addProcessor(processor) {
+        if (this.config.processors.has(processor.name)) {
+            throw new Error(CONFIG_BUILDER_ERRORS.duplicateProcessorName(processor.name));
+        }
+        this.config.processors.set(processor.name, processor);
+        return this;
+    }
+    /**
+     * Sets the loaders to use for the application.
+     * This replaces any existing loaders.
+     *
+     * @param loaders - An array of build plugins to use as loaders
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setLoaders(loaders) {
+        this.config.loaders.clear();
+        for (const loader of loaders) {
+            this.addLoader(loader.name, loader);
+        }
+        return this;
+    }
+    /**
+     * Sets the source transforms to use for transform-first bundlers such as Vite.
+     * This replaces any existing source transforms.
+     */
+    setSourceTransforms(sourceTransforms) {
+        this.config.sourceTransforms.clear();
+        for (const sourceTransform of sourceTransforms) {
+            this.addSourceTransform(sourceTransform.name, sourceTransform);
+        }
+        return this;
+    }
+    /**
+     * Adds a loader to the application.
+     *
+     * @param name - The name of the loader
+     * @param loader - The build plugin to use as a loader
+     * @returns The ConfigBuilder instance for method chaining
+     * @throws Error if a loader with the same name already exists
+     */
+    addLoader(name, loader) {
+        if (this.config.loaders.has(name)) {
+            throw new Error(CONFIG_BUILDER_ERRORS.duplicateLoaderName(name));
+        }
+        this.config.loaders.set(name, loader);
+        return this;
+    }
+    /**
+     * Adds a source transform to the application.
+     *
+     * @throws Error if a source transform with the same name already exists.
+     */
+    addSourceTransform(name, sourceTransform) {
+        if (this.config.sourceTransforms.has(name)) {
+            throw new Error(CONFIG_BUILDER_ERRORS.duplicateLoaderName(name));
+        }
+        this.config.sourceTransforms.set(name, sourceTransform);
+        return this;
+    }
+    /**
+     * Sets the cache configuration for ISR and page caching.
+     *
+     * @param cacheConfig - The cache configuration object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setCacheConfig(cacheConfig) {
+        this.config.cache = cacheConfig;
+        return this;
+    }
+    setExperimental(experimental) {
+        this.config.experimental = experimental;
+        return this;
+    }
+    createAbsolutePaths(config) {
+        const { srcDir, componentsDir, includesDir, layoutsDir, pagesDir, publicDir, distDir, workDir } = config;
+        const projectDir = config.rootDir;
+        const absoluteSrcDir = path.resolve(projectDir, srcDir);
+        const absoluteDistDir = path.resolve(projectDir, distDir);
+        const absoluteWorkDir = path.resolve(projectDir, workDir);
+        const absoluteIncludesDir = path.join(absoluteSrcDir, includesDir);
+        const absolutePagesDir = path.join(absoluteSrcDir, pagesDir);
+        this.config.absolutePaths = {
+            config: path.join(projectDir, 'eco.config.ts'),
+            projectDir: projectDir,
+            srcDir: absoluteSrcDir,
+            distDir: absoluteDistDir,
+            workDir: absoluteWorkDir,
+            componentsDir: path.join(absoluteSrcDir, componentsDir),
+            includesDir: absoluteIncludesDir,
+            layoutsDir: path.join(absoluteSrcDir, layoutsDir),
+            pagesDir: absolutePagesDir,
+            publicDir: path.join(absoluteSrcDir, publicDir),
+            htmlTemplatePath: this.resolveSemanticTemplatePath({
+                dirPath: absoluteIncludesDir,
+                basename: 'html',
+            }),
+            error404TemplatePath: this.resolveSemanticTemplatePath({
+                dirPath: absolutePagesDir,
+                basename: '404',
+            }),
+            error500TemplatePath: this.resolveSemanticTemplatePath({
+                dirPath: absolutePagesDir,
+                basename: '500',
+            }),
+        };
+        return this;
+    }
+    resolveSemanticTemplatePath({ dirPath, basename, }) {
+        const extensions = this.config.templatesExt;
+        if (extensions.length === 0) {
+            return '';
+        }
+        const matches = extensions
+            .map((extension) => path.join(dirPath, `${basename}${extension}`))
+            .filter((candidate) => fileSystem.exists(candidate));
+        invariant(matches.length <= 1, CONFIG_BUILDER_ERRORS.duplicateSemanticTemplate(basename, matches));
+        if (matches.length === 1) {
+            return matches[0];
+        }
+        return path.join(dirPath, `${basename}${extensions[0]}`);
+    }
+    createIntegrationTemplatesExt(integrations) {
+        const integrationName = integrations.map((integration) => integration.name);
+        const uniqueName = new Set(integrationName);
+        invariant(integrationName.length === uniqueName.size, CONFIG_BUILDER_ERRORS.DUPLICATE_INTEGRATION_NAMES);
+        const hasKitaJs = uniqueName.has('kitajs');
+        const hasReact = uniqueName.has('react');
+        if (hasKitaJs && hasReact) {
+            appLogger.debug(CONFIG_BUILDER_ERRORS.MIXED_JSX_ENGINES);
+        }
+        const integrationsExtensions = integrations.flatMap((integration) => integration.extensions);
+        const uniqueExtensions = new Set(integrationsExtensions);
+        invariant(integrationsExtensions.length === uniqueExtensions.size, CONFIG_BUILDER_ERRORS.DUPLICATE_INTEGRATION_EXTENSIONS);
+        this.config.templatesExt = integrationsExtensions;
+    }
+    initializeProcessors() {
+        for (const processor of this.config.processors.values()) {
+            processor.setContext(this.config);
+        }
+    }
+    validateRuntimeCapabilities() {
+        const runtimeEnvironment = this.detectRuntimeEnvironment();
+        const contributors = [
+            ...this.config.integrations.map((integration) => ({
+                kind: 'integration',
+                name: integration.name,
+                runtimeCapability: integration.runtimeCapability,
+            })),
+            ...Array.from(this.config.processors.values(), (processor) => ({
+                kind: 'processor',
+                name: processor.name,
+                runtimeCapability: processor.runtimeCapability,
+            })),
+        ];
+        for (const contributor of contributors) {
+            this.validateRuntimeCapability(contributor, runtimeEnvironment);
+        }
+    }
+    validateRuntimeCapability(contributor, environment) {
+        const declaration = contributor.runtimeCapability;
+        if (!declaration) {
+            return;
+        }
+        for (const tag of declaration.tags) {
+            if (environment.supportedTags.has(tag)) {
+                continue;
+            }
+            throw new Error(CONFIG_BUILDER_ERRORS.incompatibleRuntimeCapability(contributor.kind, contributor.name, environment.runtime, this.describeUnsupportedRuntimeTag(tag)));
+        }
+        if (!declaration.minRuntimeVersion) {
+            return;
+        }
+        const minVersion = this.parseVersion(declaration.minRuntimeVersion);
+        if (!minVersion) {
+            throw new Error(CONFIG_BUILDER_ERRORS.invalidRuntimeVersion(contributor.kind, contributor.name, declaration.minRuntimeVersion));
+        }
+        const currentVersion = this.parseVersion(environment.version);
+        if (!currentVersion) {
+            return;
+        }
+        if (this.compareVersions(currentVersion, minVersion) >= 0) {
+            return;
+        }
+        throw new Error(CONFIG_BUILDER_ERRORS.unsupportedRuntimeVersion(contributor.kind, contributor.name, environment.runtime, environment.version, declaration.minRuntimeVersion));
+    }
+    detectRuntimeEnvironment() {
+        const bunVersion = this.getBunVersion();
+        if (bunVersion) {
+            return {
+                runtime: 'bun',
+                version: bunVersion,
+                supportedTags: new Set([
+                    'bun-only',
+                    'node-compatible',
+                    'requires-native-bun-api',
+                    'requires-node-builtins',
+                ]),
+            };
+        }
+        return {
+            runtime: 'node',
+            version: process.versions.node,
+            supportedTags: new Set(['node-compatible', 'requires-node-builtins']),
+        };
+    }
+    getBunVersion() {
+        const bun = globalThis;
+        return typeof bun.Bun?.version === 'string' ? bun.Bun.version : undefined;
+    }
+    describeUnsupportedRuntimeTag(tag) {
+        switch (tag) {
+            case 'bun-only':
+                return 'it is Bun-only';
+            case 'requires-native-bun-api':
+                return 'it requires the native Bun API';
+            case 'requires-node-builtins':
+                return 'it requires Node builtins';
+            case 'node-compatible':
+                return 'it requires a Node-compatible runtime';
+        }
+    }
+    parseVersion(version) {
+        const normalized = version.trim().replace(/^v/i, '');
+        if (!/^\d+(?:\.\d+)*$/.test(normalized)) {
+            return undefined;
+        }
+        return normalized.split('.').map((segment) => Number(segment));
+    }
+    compareVersions(left, right) {
+        const maxLength = Math.max(left.length, right.length);
+        for (let index = 0; index < maxLength; index += 1) {
+            const leftValue = left[index] ?? 0;
+            const rightValue = right[index] ?? 0;
+            if (leftValue > rightValue) {
+                return 1;
+            }
+            if (leftValue < rightValue) {
+                return -1;
+            }
+        }
+        return 0;
+    }
+    /**
+     * Initializes default loaders that are required for EcoPages to function.
+     *
+     * @remarks
+     * Component identity attribution is a source transform so browser, HMR, and
+     * server module paths share one component-identity attribution mechanism.
+     */
+    async initializeDefaultLoaders() {
+        const componentMetaTransform = createEcoComponentMetaTransform({ config: this.config });
+        if (!this.config.sourceTransforms.has(componentMetaTransform.name)) {
+            this.config.sourceTransforms.set(componentMetaTransform.name, componentMetaTransform);
+        }
+    }
+    reviewBaseUrl(baseUrl) {
+        if (baseUrl) {
+            this.config.baseUrl = baseUrl;
+            return;
+        }
+        const envBaseUrl = process.env.ECOPAGES_BASE_URL;
+        if (envBaseUrl) {
+            this.config.baseUrl = envBaseUrl;
+        }
+        else if (!this.config.baseUrl) {
+            this.config.baseUrl = `http://${DEFAULT_ECOPAGES_HOSTNAME}:${DEFAULT_ECOPAGES_PORT}`;
+        }
+    }
+    /**
+     * Builds and returns the final configuration object.
+     * This performs validation and initialization of the configuration.
+     *
+     * @returns A promise that resolves to the final EcoPagesAppConfig
+     * @throws Error if required configuration is missing (e.g., baseUrl)
+     */
+    async build() {
+        this.reviewBaseUrl(this.config.baseUrl);
+        this.createIntegrationTemplatesExt(this.config.integrations);
+        this.createAbsolutePaths(this.config);
+        await this.initializeDefaultLoaders();
+        this.initializeProcessors();
+        this.validateRuntimeCapabilities();
+        const buildAdapter = createBuildAdapter({ ownership: this.buildOwnership });
+        setAppBuildAdapter(this.config, buildAdapter);
+        updateAppBuildManifest(this.config, await collectConfiguredAppBuildManifestContributions(this.config));
+        setAppServerInvalidationState(this.config, new CounterServerInvalidationState());
+        setAppEntrypointDependencyGraph(this.config, new NoopEntrypointDependencyGraph());
+        return this.config;
+    }
 }
-export {
-  CONFIG_BUILDER_ERRORS,
-  ConfigBuilder
-};