@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

package/src/config/config-builder.js

@@ -1,17 +1,47 @@
 import path from "node:path";
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../constants.js";
-import { GHTML_PLUGIN_NAME, ghtmlPlugin } from "../integrations/ghtml/ghtml.plugin.js";
+import {
+  DEFAULT_ECOPAGES_DIST_DIR,
+  DEFAULT_ECOPAGES_HOSTNAME,
+  DEFAULT_ECOPAGES_PORT,
+  DEFAULT_ECOPAGES_WORK_DIR
+} from "../config/constants.js";
+import {
+  collectConfiguredAppBuildManifestContributions,
+  createBuildAdapter,
+  getAppServerBuildPlugins,
+  setAppBuildAdapter,
+  setAppBuildExecutor,
+  updateAppBuildManifest
+} from "../build/build-adapter.js";
+import { createAppBuildExecutor } from "../build/dev-build-coordinator.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`
+  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 = "bun-native";
   config = {
     baseUrl: "",
     rootDir: ".",
@@ -21,12 +51,6 @@ class ConfigBuilder {
     componentsDir: "components",
     layoutsDir: "layouts",
     publicDir: "public",
-    includesTemplates: {
-      head: "head.ghtml.ts",
-      html: "html.ghtml.ts",
-      seo: "seo.ghtml.ts"
-    },
-    error404Template: "404.ghtml.ts",
     robotsTxt: {
       preferences: {
         "*": []
@@ -34,7 +58,7 @@ class ConfigBuilder {
     },
     integrations: [],
     integrationsDependencies: [],
-    distDir: ".eco",
+    distDir: DEFAULT_ECOPAGES_DIST_DIR,
     defaultMetadata: {
       title: "Ecopages",
       description: "This is a static site generated with Ecopages"
@@ -45,6 +69,7 @@ class ConfigBuilder {
       config: "",
       componentsDir: "",
       distDir: "",
+      workDir: "",
       includesDir: "",
       layoutsDir: "",
       pagesDir: "",
@@ -55,7 +80,9 @@ class ConfigBuilder {
       error404TemplatePath: ""
     },
     processors: /* @__PURE__ */ new Map(),
-    loaders: /* @__PURE__ */ new Map()
+    loaders: /* @__PURE__ */ new Map(),
+    sourceTransforms: /* @__PURE__ */ new Map(),
+    workDir: DEFAULT_ECOPAGES_WORK_DIR
   };
   /**
    * Sets the base URL for the application.
@@ -79,6 +106,18 @@ class ConfigBuilder {
     this.config.rootDir = rootDir;
     return this;
   }
+  /**
+   * Sets which runtime path owns build execution for the finalized app config.
+   *
+   * @remarks
+   * Bun-native remains the default. Vite-host ownership should be selected only
+   * for host-driven compatibility flows where core must not silently fall back to
+   * Bun build execution.
+   */
+  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.
@@ -145,27 +184,6 @@ class ConfigBuilder {
     this.config.publicDir = publicDir;
     return this;
   }
-  /**
-   * Sets the templates used for includes.
-   * These templates are used to build the HTML structure of pages.
-   *
-   * @param includesTemplates - An object containing the template file names
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setIncludesTemplates(includesTemplates) {
-    this.config.includesTemplates = includesTemplates;
-    return this;
-  }
-  /**
-   * Sets the template file for the 404 error page.
-   *
-   * @param error404Template - The file name of the 404 error template (default: '404.ghtml.ts')
-   * @returns The ConfigBuilder instance for method chaining
-   */
-  setError404Template(error404Template) {
-    this.config.error404Template = error404Template;
-    return this;
-  }
   /**
    * Sets the robots.txt configuration.
    * This determines which paths are allowed/disallowed for search engines.
@@ -191,13 +209,28 @@ class ConfigBuilder {
   /**
    * Sets the output directory for the built application.
    *
-   * @param distDir - The distribution directory name (default: '.eco')
+   * @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.
@@ -264,6 +297,17 @@ class ConfigBuilder {
     }
     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.
    *
@@ -279,6 +323,18 @@ class ConfigBuilder {
     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.
    *
@@ -294,35 +350,44 @@ class ConfigBuilder {
     return this;
   }
   createAbsolutePaths(config) {
-    const {
-      srcDir,
-      componentsDir,
-      includesDir,
-      layoutsDir,
-      pagesDir,
-      publicDir,
-      distDir,
-      includesTemplates,
-      error404Template
-    } = 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: path.join(absoluteSrcDir, includesDir),
+      includesDir: absoluteIncludesDir,
       layoutsDir: path.join(absoluteSrcDir, layoutsDir),
-      pagesDir: path.join(absoluteSrcDir, pagesDir),
+      pagesDir: absolutePagesDir,
       publicDir: path.join(absoluteSrcDir, publicDir),
-      htmlTemplatePath: path.join(absoluteSrcDir, includesDir, includesTemplates.html),
-      error404TemplatePath: path.join(absoluteSrcDir, pagesDir, error404Template)
+      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);
@@ -345,11 +410,138 @@ class ConfigBuilder {
       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.
    * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
    */
   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);
@@ -379,10 +571,24 @@ class ConfigBuilder {
     if (!this.config.integrations.some((integration) => integration.name === GHTML_PLUGIN_NAME)) {
       this.config.integrations.push(ghtmlPlugin());
     }
-    this.createAbsolutePaths(this.config);
     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,
+      createAppBuildExecutor({
+        development: false,
+        adapter: buildAdapter,
+        getPlugins: () => getAppServerBuildPlugins(this.config)
+      })
+    );
     return this.config;
   }
 }

package/src/{constants.d.ts → config/constants.d.ts}

@@ -30,3 +30,16 @@ export declare const GENERATED_BASE_PATHS: {
 };
 export declare const DEFAULT_ECOPAGES_PORT = 3000;
 export declare const DEFAULT_ECOPAGES_HOSTNAME = "localhost";
+/**
+ * Default directory used for deployable output.
+ */
+export declare const DEFAULT_ECOPAGES_DIST_DIR = "dist";
+/**
+ * Default internal working directory used for runtime-only artifacts.
+ *
+ * @remarks
+ * This directory is a local tool workspace and is not intended for deployment.
+ * It owns transpiled server modules, runtime manifests, and processor caches
+ * so the export directory can remain a clean deployable tree.
+ */
+export declare const DEFAULT_ECOPAGES_WORK_DIR = ".eco";

package/src/{constants.js → config/constants.js}

@@ -10,9 +10,13 @@ const GENERATED_BASE_PATHS = {
 };
 const DEFAULT_ECOPAGES_PORT = 3e3;
 const DEFAULT_ECOPAGES_HOSTNAME = "localhost";
+const DEFAULT_ECOPAGES_DIST_DIR = "dist";
+const DEFAULT_ECOPAGES_WORK_DIR = ".eco";
 export {
+  DEFAULT_ECOPAGES_DIST_DIR,
   DEFAULT_ECOPAGES_HOSTNAME,
   DEFAULT_ECOPAGES_PORT,
+  DEFAULT_ECOPAGES_WORK_DIR,
   GENERATED_BASE_PATHS,
   IS_BUN,
   RESOLVED_ASSETS_DIR,

package/src/declarations.d.ts

@@ -1,22 +1,27 @@
-import type { EcoPagesAppConfig } from './internal-types';
+import type { EcoPagesAppConfig } from './types/internal-types';
+import type { EcoNavigationRuntime } from './router/client/navigation-coordinator';
 
 type HMRHandler = (url: string) => Promise<void>;
-
-type ReloadPageFunction = (options: { clearCache: boolean }) => Promise<void>;
+type CleanupPageRootFunction = () => void;
+type EcoPageRoot = { render: (node: unknown) => void; unmount: () => void };
+type EcoPageData = {
+	module: string;
+	props: Record<string, unknown>;
+};
+type EcoPagesWindowRuntime = {
+	hmrHandlers?: Record<string, HMRHandler>;
+	navigation?: EcoNavigationRuntime;
+	react?: {
+		cleanupPageRoot?: CleanupPageRootFunction;
+		pageRoot?: EcoPageRoot | null;
+	};
+	page?: EcoPageData;
+};
 
 declare global {
-	var ecoConfig: EcoPagesAppConfig;
-
 	interface Window {
-		/** Registered HMR handlers for specific module paths */
-		__ecopages_hmr_handlers__?: Record<string, HMRHandler>;
-		/** Function to reload the current page, used for layout updates */
-		__ecopages_reload_current_page__?: ReloadPageFunction;
-		/** Page data registry - contains module path and props for current page */
-		__ECO_PAGE__?: {
-			module: string;
-			props: Record<string, unknown>;
-		};
+		/** Shared Ecopages browser runtime state */
+		__ECO_PAGES__?: EcoPagesWindowRuntime;
 	}
 }
 

package/src/dev/host-runtime.d.ts

@@ -0,0 +1,10 @@
+import type { EcoPagesAppConfig } from '../types/public-types.js';
+import { type DevelopmentInvalidationPlan } from '../services/invalidation/development-invalidation.service.js';
+export type HostRuntimeModuleLoader = (id: string) => Promise<unknown>;
+export interface DevelopmentHostRuntime {
+    registerHostModuleLoader(loader: HostRuntimeModuleLoader): void;
+    planFileChange(filePath: string): DevelopmentInvalidationPlan;
+    invalidateServerModules(changedFiles?: string[]): void;
+    resetRuntimeState(changedFiles?: string[]): void;
+}
+export declare function createDevelopmentHostRuntime(appConfig: EcoPagesAppConfig): DevelopmentHostRuntime;

package/src/dev/host-runtime.js

@@ -0,0 +1,24 @@
+import {
+  DevelopmentInvalidationService
+} from "../services/invalidation/development-invalidation.service.js";
+import { setHostModuleLoader } from "../services/module-loading/host-module-loader-registry.js";
+function createDevelopmentHostRuntime(appConfig) {
+  const invalidationService = new DevelopmentInvalidationService(appConfig);
+  return {
+    registerHostModuleLoader(loader) {
+      setHostModuleLoader(loader);
+    },
+    planFileChange(filePath) {
+      return invalidationService.planFileChange(filePath);
+    },
+    invalidateServerModules(changedFiles) {
+      invalidationService.invalidateServerModules(changedFiles);
+    },
+    resetRuntimeState(changedFiles) {
+      invalidationService.resetRuntimeState(changedFiles);
+    }
+  };
+}
+export {
+  createDevelopmentHostRuntime
+};

package/src/dev/sc-server.d.ts

@@ -1,5 +1,5 @@
 import type { Server } from 'bun';
-import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
 type StaticContentServerOptions = {
     port?: number;
 };

package/src/dev/sc-server.js

@@ -1,5 +1,5 @@
 import { extname, join } from "node:path";
-import { STATUS_MESSAGE } from "../constants.js";
+import { STATUS_MESSAGE } from "../config/constants.js";
 import { fileSystem } from "@ecopages/file-system";
 import { ServerUtils } from "../utils/server-utils.module.js";
 import { getRequiredBunRuntime } from "../utils/runtime.js";