@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.41

package/src/hmr/strategies/js-hmr-strategy.js

@@ -1,14 +1,14 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
-import { HmrStrategy, HmrStrategyType } from "../hmr-strategy";
-import { appLogger } from "../../global/app-logger";
-import { defaultBuildAdapter } from "../../build/build-adapter.js";
+import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
+import { appLogger } from "../../global/app-logger.js";
 class JsHmrStrategy extends HmrStrategy {
+  type = HmrStrategyType.SCRIPT;
+  context;
   constructor(context) {
     super();
     this.context = context;
   }
-  type = HmrStrategyType.SCRIPT;
   /**
    * Determines if the file is a JS/TS file that could affect registered entrypoints.
    *
@@ -23,18 +23,19 @@ class JsHmrStrategy extends HmrStrategy {
     const watchedFiles = this.context.getWatchedFiles();
     const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
     const isInSrc = filePath.startsWith(this.context.getSrcDir());
+    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
     if (watchedFiles.size === 0) {
       return false;
     }
     if (!isJsTs || !isInSrc) {
       return false;
     }
+    if (isIntegrationTemplate) {
+      return false;
+    }
     if (watchedFiles.has(filePath)) {
       return true;
     }
-    if (this.context.getDependencyEntrypoints) {
-      return this.context.getDependencyEntrypoints(filePath).size > 0;
-    }
     return true;
   }
   /**
@@ -45,6 +46,8 @@ class JsHmrStrategy extends HmrStrategy {
    * @remarks
    * If runtime-specific dependency graph hooks are unavailable, this strategy
    * falls back to rebuilding all watched entrypoints.
+   * When multiple entrypoints are impacted they are bundled in a single esbuild
+   * invocation to share AST parsing and chunk deduplication.
    * @returns Action to broadcast update events
    */
   async process(filePath) {
@@ -54,24 +57,37 @@ class JsHmrStrategy extends HmrStrategy {
       appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
       return { type: "none" };
     }
-    const updates = [];
-    let reloadRequired = false;
-    const dependencyHits = this.context.getDependencyEntrypoints?.(filePath) ?? /* @__PURE__ */ new Set();
+    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
     const hasDependencyHit = dependencyHits.size > 0;
     const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint)) : Array.from(watchedFiles.keys());
+    const buildableEntrypoints = impactedEntrypoints.filter(
+      (entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true
+    );
     if (!hasDependencyHit) {
       appLogger.debug("[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints");
     }
-    for (const entrypoint of impactedEntrypoints) {
+    if (buildableEntrypoints.length === 0) {
+      return { type: "none" };
+    }
+    const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
+    if (!buildResult.success) {
+      return { type: "none" };
+    }
+    const updates = [];
+    let reloadRequired = false;
+    for (const entrypoint of buildableEntrypoints) {
       const outputUrl = watchedFiles.get(entrypoint);
-      if (!outputUrl) {
-        continue;
+      if (!outputUrl) continue;
+      if (buildResult.dependencies) {
+        const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
+        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
       }
-      const result = await this.bundleEntrypoint(entrypoint, outputUrl);
+      const srcDir = this.context.getSrcDir();
+      const relativePath = path.relative(srcDir, entrypoint);
+      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
+      const result = await this.processOutput(outputPath, outputUrl);
       if (result.success) {
-        if (result.dependencies && this.context.setEntrypointDependencies) {
-          this.context.setEntrypointDependencies(entrypoint, result.dependencies);
-        }
         updates.push(outputUrl);
         if (result.requiresReload) {
           reloadRequired = true;
@@ -83,18 +99,14 @@ class JsHmrStrategy extends HmrStrategy {
         appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
         return {
           type: "broadcast",
-          events: [
-            {
-              type: "reload"
-            }
-          ]
+          events: [{ type: "reload" }]
         };
       }
       return {
         type: "broadcast",
-        events: updates.map((path2) => ({
+        events: updates.map((p) => ({
           type: "update",
-          path: path2,
+          path: p,
           timestamp: Date.now()
         }))
       };
@@ -102,44 +114,40 @@ class JsHmrStrategy extends HmrStrategy {
     return { type: "none" };
   }
   /**
-   * Bundles a single entrypoint and processes the output.
-   *
-   * @param entrypointPath - Absolute path to the source file
-   * @param outputUrl - URL path for the bundled file
-   * @returns True if bundling was successful
+   * Bundles one or more entrypoints in a single esbuild invocation.
+   * Uses the source directory as the output base so that the directory structure
+   * is preserved under the HMR dist folder.
    */
-  async bundleEntrypoint(entrypointPath, outputUrl) {
+  async bundleEntrypoints(entrypoints) {
     try {
-      const srcDir = this.context.getSrcDir();
-      const relativePath = path.relative(srcDir, entrypointPath);
-      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?)$/, ".js");
-      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
-      const result = await defaultBuildAdapter.build({
-        entrypoints: [entrypointPath],
+      const result = await this.context.getBrowserBundleService().bundle({
+        profile: "hmr-entrypoint",
+        entrypoints,
         outdir: this.context.getDistDir(),
-        naming: relativePathJs,
-        ...defaultBuildAdapter.getTranspileOptions("hmr-entrypoint"),
+        outbase: this.context.getSrcDir(),
+        naming: "[dir]/[name]",
         plugins: this.context.getPlugins(),
-        minify: false,
-        external: ["react", "react-dom"]
+        minify: false
       });
       if (!result.success) {
-        appLogger.error(`[JsHmrStrategy] Failed to build ${entrypointPath}:`, result.logs);
-        return { success: false, requiresReload: false, dependencies: void 0 };
+        appLogger.error("[JsHmrStrategy] Batched build failed:", result.logs);
+        return { success: false };
       }
-      const dependencyGraph = result.dependencyGraph?.entrypoints?.[path.resolve(entrypointPath)] ?? [];
-      const output = await this.processOutput(outputPath, outputUrl);
-      return {
-        ...output,
-        dependencies: dependencyGraph
-      };
+      const dependencies = /* @__PURE__ */ new Map();
+      if (result.dependencyGraph?.entrypoints) {
+        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+          dependencies.set(path.resolve(entrypoint), deps);
+        }
+      }
+      return { success: true, dependencies };
     } catch (error) {
-      appLogger.error(`[JsHmrStrategy] Error bundling ${entrypointPath}:`, error);
-      return { success: false, requiresReload: false, dependencies: void 0 };
+      appLogger.error("[JsHmrStrategy] Error in batched build:", error);
+      return { success: false };
     }
   }
   /**
-   * Processes bundled output by replacing specifiers and injecting HMR code.
+   * Processes bundled output and determines whether the browser can hot-accept
+   * the update or must fall back to a full reload.
    *
    * @param filepath - Path to the bundled output file
    * @param url - URL path for the bundled file
@@ -147,12 +155,10 @@ class JsHmrStrategy extends HmrStrategy {
    */
   async processOutput(filepath, url) {
     try {
-      let code = await fileSystem.readFile(filepath);
+      const code = await fileSystem.readFile(filepath);
       if (code.includes("/* [ecopages] hmr */")) {
         return { success: true, requiresReload: !code.includes("import.meta.hot.accept") };
       }
-      code = this.replaceBareSpecifiers(code);
-      await fileSystem.writeAsync(filepath, code);
       appLogger.debug(`[JsHmrStrategy] Processed ${url}`);
       const hasHmrAccept = code.includes("import.meta.hot.accept");
       return { success: true, requiresReload: !hasHmrAccept };
@@ -161,27 +167,6 @@ class JsHmrStrategy extends HmrStrategy {
       return { success: false, requiresReload: false };
     }
   }
-  /**
-   * Replaces bare specifiers with vendor URLs.
-   *
-   * Handles both static imports and dynamic imports.
-   *
-   * @param code - The bundled code to transform
-   * @returns The transformed code with vendor URLs
-   */
-  replaceBareSpecifiers(code) {
-    const specifierMap = this.context.getSpecifierMap();
-    if (specifierMap.size === 0) {
-      return code;
-    }
-    let result = code;
-    for (const [bareSpec, vendorUrl] of specifierMap.entries()) {
-      const escaped = bareSpec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      result = result.replace(new RegExp(`from\\s*["']${escaped}["']`, "g"), `from "${vendorUrl}"`);
-      result = result.replace(new RegExp(`import\\(["']${escaped}["']\\)`, "g"), `import("${vendorUrl}")`);
-    }
-    return result;
-  }
 }
 export {
   JsHmrStrategy

package/src/index.browser.d.ts

@@ -1,3 +1,3 @@
-export type * from './public-types.js';
+export type * from './types/public-types.js';
 export type * from './eco/eco.types.js';
-export { eco } from './eco/eco.js';
+export { eco } from './eco/eco.browser.js';

package/src/index.browser.js

@@ -1,4 +1,4 @@
-import { eco } from "./eco/eco.js";
+import { eco } from "./eco/eco.browser.js";
 export {
   eco
 };

package/src/index.d.ts

@@ -1,5 +1,6 @@
-export type * from './public-types.js';
+export type * from './types/public-types.js';
 export type * from './eco/eco.types.js';
 export { eco } from './eco/eco.js';
-export { EcopagesApp, createApp, type EcopagesAppOptions } from './create-app.js';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from './define-api-handler.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './adapters/shared/define-api-handler.js';
+export { createEcoBuildPluginFromSourceTransform, createVitePluginsFromAppSourceTransforms, getAppSourceTransforms, createVitePluginFromSourceTransform, normalizeTransformId, type EcoSourceTransform, type EcoSourceTransformResult, type EcoViteCompatiblePlugin, } from './plugins/source-transform.js';
+export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.js';

package/src/index.js

@@ -1,10 +1,21 @@
 import { eco } from "./eco/eco.js";
-import { EcopagesApp, createApp } from "./create-app.js";
-import { defineApiHandler, defineGroupHandler } from "./define-api-handler.js";
+import { defineApiHandler, defineGroupHandler } from "./adapters/shared/define-api-handler.js";
+import {
+  createEcoBuildPluginFromSourceTransform,
+  createVitePluginsFromAppSourceTransforms,
+  getAppSourceTransforms,
+  createVitePluginFromSourceTransform,
+  normalizeTransformId
+} from "./plugins/source-transform.js";
+import { createEcoComponentMetaTransform } from "./plugins/eco-component-meta-plugin.js";
 export {
-  EcopagesApp,
-  createApp,
+  createEcoBuildPluginFromSourceTransform,
+  createEcoComponentMetaTransform,
+  createVitePluginFromSourceTransform,
+  createVitePluginsFromAppSourceTransforms,
   defineApiHandler,
   defineGroupHandler,
-  eco
+  eco,
+  getAppSourceTransforms,
+  normalizeTransformId
 };

package/src/integrations/ghtml/ghtml-renderer.d.ts

@@ -2,14 +2,15 @@
  * This module contains the ghtml renderer
  * @module
  */
-import type { EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../public-types.js';
-import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/integration-renderer.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.js';
+import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/orchestration/integration-renderer.js';
 /**
  * A renderer for the ghtml integration.
  * It renders a page using the HtmlTemplate and Page components.
  */
 export declare class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
     render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }

package/src/integrations/ghtml/ghtml-renderer.js

@@ -1,7 +1,15 @@
-import { IntegrationRenderer } from "../../route-renderer/integration-renderer.js";
-import { GHTML_PLUGIN_NAME } from "./ghtml.plugin.js";
+import {
+  IntegrationRenderer
+} from "../../route-renderer/orchestration/integration-renderer.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
 class GhtmlRenderer extends IntegrationRenderer {
   name = GHTML_PLUGIN_NAME;
+  async renderComponent(input) {
+    return this.renderStringComponentWithQueuedForeignSubtrees(
+      input,
+      input.component
+    );
+  }
   async render({
     params,
     query,
@@ -14,42 +22,31 @@ class GhtmlRenderer extends IntegrationRenderer {
     HtmlTemplate
   }) {
     try {
-      const pageContent = await Page({ params, query, ...props, locals: pageLocals });
-      const children = Layout && typeof Layout === "function" ? await Layout({ children: pageContent, locals }) : pageContent;
-      const body = await HtmlTemplate({
+      return await this.renderPageWithDocumentShell({
+        page: {
+          component: Page,
+          props: { params, query, ...props, locals: pageLocals }
+        },
+        layout: Layout ? {
+          component: Layout,
+          props: locals ? { locals } : {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
         metadata,
-        children,
-        pageProps: props || {}
+        pageProps: props ?? {}
       });
-      return this.DOC_TYPE + body;
     } catch (error) {
       throw this.createRenderError("Error rendering page", error);
     }
   }
   async renderToResponse(view, props, ctx) {
     try {
-      const Layout = view.config?.layout;
-      const viewFn = view;
-      const pageContent = await viewFn(props);
-      let body;
-      if (ctx.partial) {
-        body = pageContent;
-      } else {
-        const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-        const HtmlTemplate = await this.getHtmlTemplate();
-        const metadata = view.metadata ? await view.metadata({
-          params: {},
-          query: {},
-          props,
-          appConfig: this.appConfig
-        }) : this.appConfig.defaultMetadata;
-        body = this.DOC_TYPE + await HtmlTemplate({
-          metadata,
-          children,
-          pageProps: props
-        });
-      }
-      return this.createHtmlResponse(body, ctx);
+      return await this.renderViewWithDocumentShell({
+        view,
+        props,
+        ctx,
+        layout: view.config?.layout
+      });
     } catch (error) {
       throw this.createRenderError("Error rendering view", error);
     }

package/src/integrations/ghtml/ghtml.constants.d.ts

@@ -0,0 +1 @@
+export declare const GHTML_PLUGIN_NAME = "ghtml";

package/src/integrations/ghtml/ghtml.constants.js

@@ -0,0 +1,4 @@
+const GHTML_PLUGIN_NAME = "ghtml";
+export {
+  GHTML_PLUGIN_NAME
+};

package/src/integrations/ghtml/ghtml.plugin.d.ts

@@ -1,9 +1,5 @@
-import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin';
-import { GhtmlRenderer } from './ghtml-renderer';
-/**
- * The name of the ghtml plugin
- */
-export declare const GHTML_PLUGIN_NAME = "ghtml";
+import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin.js';
+import { GhtmlRenderer } from './ghtml-renderer.js';
 /**
  * The Ghtml plugin class
  * This plugin provides support for ghtml components in Ecopages

package/src/integrations/ghtml/ghtml.plugin.js

@@ -1,6 +1,6 @@
-import { IntegrationPlugin } from "../../plugins/integration-plugin";
-import { GhtmlRenderer } from "./ghtml-renderer";
-const GHTML_PLUGIN_NAME = "ghtml";
+import { IntegrationPlugin } from "../../plugins/integration-plugin.js";
+import { GhtmlRenderer } from "./ghtml-renderer.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
 class GhtmlPlugin extends IntegrationPlugin {
   renderer = GhtmlRenderer;
   constructor(options) {
@@ -15,7 +15,6 @@ function ghtmlPlugin(options) {
   return new GhtmlPlugin(options);
 }
 export {
-  GHTML_PLUGIN_NAME,
   GhtmlPlugin,
   ghtmlPlugin
 };

package/src/plugins/README.md

@@ -0,0 +1,35 @@
+# Plugin Contracts
+
+This directory contains the authoring contracts for Ecopages integrations, processors, and related plugin-facing runtime declarations.
+
+## Purpose
+
+The plugin layer defines what packages are allowed to declare about themselves, while core retains orchestration ownership.
+
+These contracts are responsible for:
+
+- integration registration and lifecycle hooks
+- processor registration and asset capability declaration
+- runtime capability declaration and validation input
+- shared build-plugin bridge types used by integrations and processors
+
+## Main Files
+
+- `integration-plugin.ts`: framework-semantics contract for render integrations
+- `processor.ts`: asset-transformation contract for processors
+- `runtime-capability.ts`: runtime compatibility declaration types
+- `source-transform.ts`: bundler-neutral source-transform primitive with Ecopages adapters plus app-level Vite plugin composition helpers
+- `eco-component-meta-plugin.ts`: shared metadata transform used by core loading/build paths
+
+## Ownership Rules
+
+- Integrations own rendering semantics, hydration behavior, and integration-specific HMR strategy.
+- Processors own asset semantics, cache ownership, and processor-specific watch behavior.
+- Core owns lifecycle ordering, startup orchestration, and manifest assembly.
+
+## Lifecycle Summary
+
+1. Config build validates and prepares plugin contributions.
+2. Core seals the app-owned build manifest.
+3. Runtime startup calls runtime-only setup hooks.
+4. Request-time rendering and development invalidation reuse those finalized contracts.

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

@@ -1,2 +1,3 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
+export declare function resolveAppSourceAliasPath(srcDir: string, specifier: string): string | undefined;
 export declare function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin;

package/src/plugins/alias-resolver-plugin.js

@@ -1,9 +1,11 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
 function findResolvablePath(candidate) {
   if (path.extname(candidate)) {
-    return existsSync(candidate) ? candidate : void 0;
+    if (existsSync(candidate)) {
+      return candidate;
+    }
   }
   for (const extension of RESOLVABLE_EXTENSIONS) {
     const fileCandidate = `${candidate}${extension}`;
@@ -19,13 +21,32 @@ function findResolvablePath(candidate) {
   }
   return void 0;
 }
+function resolveAliasedBarrelTarget(resolvedPath) {
+  if (!path.basename(resolvedPath).startsWith("index.")) {
+    return resolvedPath;
+  }
+  const source = readFileSync(resolvedPath, "utf8").trim();
+  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+  if (!match?.[1]?.startsWith(".")) {
+    return resolvedPath;
+  }
+  const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
+  return target ?? resolvedPath;
+}
+function resolveAppSourceAliasPath(srcDir, specifier) {
+  if (!specifier.startsWith("@/")) {
+    return void 0;
+  }
+  const candidate = path.join(srcDir, specifier.slice(2));
+  const resolved = findResolvablePath(candidate);
+  return resolved ? resolveAliasedBarrelTarget(resolved) : void 0;
+}
 function createAliasResolverPlugin(srcDir) {
   return {
     name: "ecopages-alias-resolver",
     setup(build) {
       build.onResolve({ filter: /^@\// }, (args) => {
-        const candidate = path.join(srcDir, args.path.slice(2));
-        const resolved = findResolvablePath(candidate);
+        const resolved = resolveAppSourceAliasPath(srcDir, args.path);
         if (resolved) {
           return { path: resolved };
         }
@@ -35,5 +56,6 @@ function createAliasResolverPlugin(srcDir) {
   };
 }
 export {
-  createAliasResolverPlugin
+  createAliasResolverPlugin,
+  resolveAppSourceAliasPath
 };

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

@@ -26,7 +26,8 @@
  * @module eco-component-meta-plugin
  */
 import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import { type EcoSourceTransform, type EcoViteCompatiblePlugin } from './source-transform.js';
 /**
  * Options for creating the eco-component-meta-plugin.
  */
@@ -34,6 +35,11 @@ export interface EcoComponentDirPluginOptions {
     /** The EcoPages application configuration containing integration settings */
     config: EcoPagesAppConfig;
 }
+/**
+ * Creates the bundler-neutral metadata transform used by Ecopages loaders and
+ * Vite-compatible adapters.
+ */
+export declare function createEcoComponentMetaTransform(options: EcoComponentDirPluginOptions): EcoSourceTransform;
 /**
  * Creates a build plugin that auto-injects `__eco` metadata into EcoComponent config objects.
  *
@@ -47,6 +53,8 @@ export interface EcoComponentDirPluginOptions {
  * Supported patterns:
  * - `eco.page({ ... })` - Page component declarations
  * - `eco.component({ ... })` - Reusable component declarations
+ * - `eco.html({ ... })` - HTML shell declarations
+ * - `eco.layout({ ... })` - Layout declarations
  * - `Component.config = { ... }` - Config assignment pattern
  * - `config: { ... }` - Config property in object literals
  * - `export const config = { ... }` - Exported config declarations
@@ -63,6 +71,11 @@ export interface EcoComponentDirPluginOptions {
  * ```
  */
 export declare function createEcoComponentMetaPlugin(options: EcoComponentDirPluginOptions): EcoBuildPlugin;
+/**
+ * Creates a Vite-compatible metadata injection plugin from the shared
+ * Ecopages source-transform primitive.
+ */
+export declare function createEcoComponentMetaVitePlugin(options: EcoComponentDirPluginOptions): EcoViteCompatiblePlugin;
 /**
  * Injects `__eco` metadata into EcoComponent config objects in file content.
  *