@ecopages/core 0.2.0-alpha.34 → 0.2.0-alpha.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.34",
+  "version": "0.2.0-alpha.36",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,15 +17,15 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.34",
+    "@ecopages/file-system": "0.2.0-alpha.36",
     "@ecopages/logger": "^0.2.3",
-    "@ecopages/scripts-injector": "^0.1.3",
+    "@ecopages/scripts-injector": "^0.1.5",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
     "chokidar": "^5.0.0",
     "esbuild": "^0.28.0",
     "ghtml": "^4.0.2",
     "oxc-parser": "^0.124.0",
-    "ws": "^8.18.0"
+    "ws": "^8.20.1"
   },
   "exports": {
     ".": {
@@ -43,6 +43,11 @@
       "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
+    "./route-renderer/component-render-context": {
+      "import": "./src/route-renderer/orchestration/component-render-context.js",
+      "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
+      "default": "./src/route-renderer/orchestration/component-render-context.js"
+    },
     "./router/navigation-coordinator": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
@@ -145,6 +150,11 @@
       "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
+    "./route-renderer/component-render-context.ts": {
+      "import": "./src/route-renderer/orchestration/component-render-context.js",
+      "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
+      "default": "./src/route-renderer/orchestration/component-render-context.js"
+    },
     "./router/navigation-coordinator.ts": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"

package/src/adapters/create-app.js

@@ -1,12 +1,12 @@
 import { AbstractApplicationAdapter } from "./abstract/application-adapter.js";
 import { SharedApplicationAdapter } from "./shared/application-adapter.js";
+import { createApp as createBunApp } from "./bun/create-app.js";
+import { createNodeApp } from "./node/create-app.js";
 async function createRuntimeApp(options) {
   const bun = globalThis.Bun;
   if (bun) {
-    const { createApp: createBunApp } = await import("./bun/create-app.js");
     return await createBunApp(options);
   }
-  const { createApp: createNodeApp } = await import("./node/create-app.js");
   return await createNodeApp(options);
 }
 async function createApp(options) {

package/src/adapters/node/node-hmr-manager.js

@@ -138,6 +138,11 @@ class NodeHmrManager {
     this.bridge.broadcast(event);
   }
   async handleFileChange(filePath, options = {}) {
+    if (!fileSystem.exists(filePath)) {
+      appLogger.debug(`[NodeHmrManager] Skipping missing file change: ${filePath}`);
+      this.clearFailedEntrypointRegistration(filePath);
+      return;
+    }
     const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
     const strategy = sorted.find((s) => {
       try {

package/src/adapters/node/server-adapter.d.ts

@@ -53,6 +53,9 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     private previewServer;
     private bridge;
     private hmrManager;
+    private shouldInjectHmrScript;
+    private isHtmlResponse;
+    private maybeInjectHmrScript;
     constructor(options: NodeServerAdapterParams);
     /**
      * Prepares the adapter for use.

package/src/adapters/node/server-adapter.js

@@ -1,6 +1,8 @@
 import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
 import { appLogger } from "../../global/app-logger.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
+import { NodeHmrManager } from "./node-hmr-manager.js";
 import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
 import { SharedServerAdapter } from "../shared/server-adapter.js";
 import { ServerStaticBuilder } from "../shared/server-static-builder.js";
@@ -13,6 +15,11 @@ import {
 } from "../shared/runtime-bootstrap.js";
 import { NodeStaticContentServer } from "./static-content-server.js";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+} from "../shared/hmr-html-response.js";
 class ClientAbortError extends Error {
   constructor() {
     super("Client closed the request");
@@ -28,6 +35,18 @@ class NodeServerAdapter extends SharedServerAdapter {
   previewServer = null;
   bridge = null;
   hmrManager = null;
+  shouldInjectHmrScript() {
+    return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager ?? void 0);
+  }
+  isHtmlResponse(response) {
+    return isHtmlResponse(response);
+  }
+  async maybeInjectHmrScript(response) {
+    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
+      return injectHmrRuntimeIntoHtmlResponse(response);
+    }
+    return response;
+  }
   constructor(options) {
     super(options);
     this.apiHandlers = options.apiHandlers || [];
@@ -283,12 +302,13 @@ class NodeServerAdapter extends SharedServerAdapter {
       throw new Error("Node server adapter is not initialized. Call createAdapter() first.");
     }
     try {
-      return await this.handleSharedRequest(request, {
+      const response = await this.handleSharedRequest(request, {
         apiHandlers: this.apiHandlers,
         errorHandler: this.errorHandler,
         serverInstance: this.serverInstance,
         hmrManager: this.hmrManager
       });
+      return await this.maybeInjectHmrScript(response);
     } catch (error) {
       if (error instanceof ClientAbortError) {
         return new Response(null, { status: 499 });
@@ -315,8 +335,6 @@ class NodeServerAdapter extends SharedServerAdapter {
   async completeInitialization(server) {
     this.serverInstance = server;
     if (this.options?.watch) {
-      const { NodeHmrManager } = await import("./node-hmr-manager.js");
-      const { WebSocketServer } = await import("ws");
       const wss = new WebSocketServer({ noServer: true });
       this.bridge = new NodeClientBridge();
       this.hmrManager = new NodeHmrManager({ appConfig: this.appConfig, bridge: this.bridge });

package/src/adapters/shared/hmr-html-response.js

@@ -9,16 +9,17 @@ function shouldInjectHmrHtmlResponse(watch, hmrManager) {
 }
 async function injectHmrRuntimeIntoHtmlResponse(response) {
   const html = await response.text();
+  const headers = new Headers(response.headers);
+  headers.set("Cache-Control", "no-store, must-revalidate");
+  headers.delete("Content-Length");
   if (html.includes(HMR_RUNTIME_IMPORT)) {
     return new Response(html, {
       status: response.status,
       statusText: response.statusText,
-      headers: response.headers
+      headers
     });
   }
   const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
-  const headers = new Headers(response.headers);
-  headers.delete("Content-Length");
   return new Response(updatedHtml, {
     status: response.status,
     statusText: response.statusText,

package/src/adapters/shared/render-context.d.ts

@@ -3,6 +3,7 @@ import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
     integrations: AnyIntegrationPlugin[];
     rendererModules?: unknown;
+    importServerModule?: (filePath: string) => Promise<unknown>;
 }
 /**
  * Creates a render context for route handlers.

package/src/adapters/shared/render-context.js

@@ -1,4 +1,8 @@
+import { fileURLToPath } from "node:url";
 import { invariant } from "../../utils/invariant.js";
+function resolveServerModulePath(filePath) {
+  return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
+}
 function mergePropsWithLocals(props, locals) {
   if (!locals || typeof props !== "object" || props === null) {
     return props;
@@ -20,6 +24,23 @@ function createRenderContext(options) {
     });
   };
   const renderContext = {
+    importServerModule: async (filePath) => {
+      invariant(!!options.importServerModule, "Server module importing is not available in this render context.");
+      return await options.importServerModule(resolveServerModulePath(filePath));
+    },
+    async renderServerModule(filePath, props, renderOptions) {
+      const module = await renderContext.importServerModule(filePath);
+      const view = module.default;
+      const locals = this?.locals;
+      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+      const renderer = getRendererForView(view);
+      const ctx = {
+        partial: false,
+        status: renderOptions?.status,
+        headers: renderOptions?.headers
+      };
+      return await renderer.renderToResponse(view, mergedProps, ctx);
+    },
     async render(view, props, renderOptions) {
       const locals = this?.locals;
       const mergedProps = mergePropsWithLocals(props ?? {}, locals);

package/src/adapters/shared/server-adapter.js

@@ -157,9 +157,16 @@ class SharedServerAdapter extends AbstractServerAdapter {
     return this.fileSystemResponseMatcher?.getCacheService() ?? null;
   }
   getRenderContext() {
+    const serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
     return createRenderContext({
       integrations: this.appConfig.integrations,
-      rendererModules: this.appConfig.runtime?.rendererModuleContext
+      rendererModules: this.appConfig.runtime?.rendererModuleContext,
+      importServerModule: async (filePath) => await serverModuleTranspiler.importModule({
+        filePath,
+        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+        externalPackages: true,
+        bypassCache: this.options?.watch === true
+      })
     });
   }
   /**

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

@@ -54,6 +54,14 @@ export interface BuildOptions {
     bundle?: boolean;
     externalPackages?: boolean;
     external?: string[];
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
     plugins?: EcoBuildPlugin[];
     [key: string]: unknown;
 }

package/src/build/build-adapter.js

@@ -415,6 +415,8 @@ class BunBuildAdapter {
     try {
       const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
       const outdir = path.resolve(options.outdir ?? "dist/assets");
+      const tsconfigPath = path.join(contextRoot, "tsconfig.json");
+      const tsconfigExists = fs.existsSync(tsconfigPath);
       const plugins = this.getPluginsForBuild(options.plugins);
       const result = await bun.build({
         entrypoints: options.entrypoints,
@@ -429,6 +431,8 @@ class BunBuildAdapter {
         splitting: !!options.splitting,
         minify: !!options.minify,
         packages: options.target !== "browser" && options.externalPackages !== false ? "external" : void 0,
+        tsconfig: tsconfigExists ? tsconfigPath : void 0,
+        jsx: options.jsx,
         plugins: plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : void 0
       });
       return this.rewriteAliasedRuntimeSpecifiers(

package/src/config/config-builder.js

@@ -395,7 +395,7 @@ class ConfigBuilder {
     const hasKitaJs = uniqueName.has("kitajs");
     const hasReact = uniqueName.has("react");
     if (hasKitaJs && hasReact) {
-      appLogger.warn(CONFIG_BUILDER_ERRORS.MIXED_JSX_ENGINES);
+      appLogger.debug(CONFIG_BUILDER_ERRORS.MIXED_JSX_ENGINES);
     }
     const integrationsExtensions = integrations.flatMap((integration) => integration.extensions);
     const uniqueExtensions = new Set(integrationsExtensions);

package/src/eco/eco.js

@@ -1,5 +1,6 @@
 import {
   finalizeComponentRender,
+  getComponentRenderContext,
   interceptForeignChild
 } from "../route-renderer/orchestration/component-render-context.js";
 import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
@@ -7,19 +8,31 @@ function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;
   const comp = ((props) => {
     const componentProps = props ?? {};
-    const renderInline = () => finalizeComponentRender(comp, options.render(props));
+    const renderInline = (nextProps = props) => finalizeComponentRender(comp, options.render(nextProps));
+    const activeRenderContext = getComponentRenderContext();
     const foreignChildRender = interceptForeignChild({
       component: comp,
       props: componentProps,
       targetIntegration: integrationName
     });
     if (isThenable(foreignChildRender)) {
-      return foreignChildRender.then(
-        (resolvedForeignChildRender) => resolvedForeignChildRender !== void 0 ? resolvedForeignChildRender : renderInline()
-      );
+      return foreignChildRender.then((resolvedForeignChildRender) => {
+        if (resolvedForeignChildRender?.kind === "resolved") {
+          return resolvedForeignChildRender.value;
+        }
+        return renderInline(resolvedForeignChildRender?.props ?? props);
+      });
+    }
+    if (foreignChildRender?.kind === "resolved") {
+      return foreignChildRender.value;
     }
-    if (foreignChildRender !== void 0) {
-      return foreignChildRender;
+    if (foreignChildRender?.kind === "inline") {
+      return renderInline(foreignChildRender.props ?? props);
+    }
+    if (activeRenderContext && activeRenderContext.foreignChildRuntime && integrationName && integrationName !== activeRenderContext.currentIntegration) {
+      throw new Error(
+        `[ecopages] Missing foreign-child interception from ${activeRenderContext.currentIntegration} to ${integrationName} for ${options.__eco?.file ?? "unknown component"}.`
+      );
     }
     return renderInline();
   });

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

@@ -23,8 +23,7 @@ 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 isRouteTemplate = filePath.startsWith(this.context.getPagesDir()) || filePath.startsWith(this.context.getLayoutsDir());
-    const isIntegrationTemplate = isRouteTemplate && this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
+    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
     if (watchedFiles.size === 0) {
       return false;
     }

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

@@ -33,15 +33,22 @@ function resolveAliasedBarrelTarget(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: resolveAliasedBarrelTarget(resolved) };
+          return { path: resolved };
         }
         return {};
       });
@@ -49,5 +56,6 @@ function createAliasResolverPlugin(srcDir) {
   };
 }
 export {
-  createAliasResolverPlugin
+  createAliasResolverPlugin,
+  resolveAppSourceAliasPath
 };

package/src/plugins/eco-component-meta-plugin.js

@@ -18,7 +18,13 @@ function buildExtensionToIntegrationMap(integrations) {
   const mapping = [];
   for (const integration of integrations) {
     for (const ext of integration.extensions) {
-      mapping.push([ext, integration.name]);
+      mapping.push([
+        ext,
+        {
+          name: integration.name,
+          jsxImportSource: integration.jsxImportSource
+        }
+      ]);
     }
   }
   mapping.sort((a, b) => b[0].length - a[0].length);
@@ -30,7 +36,14 @@ function detectIntegration(filePath, extensionToIntegration) {
       return integration;
     }
   }
-  return "ghtml";
+  return { name: "ghtml" };
+}
+function prependJsxImportSource(code, jsxImportSource) {
+  if (!jsxImportSource || code.includes("@jsxImportSource")) {
+    return code;
+  }
+  return `/** @jsxImportSource ${jsxImportSource} */
+${code}`;
 }
 function createExtensionPattern(extensions) {
   if (extensions.length === 0) {
@@ -54,7 +67,7 @@ function createEcoComponentMetaTransform(options) {
     transform(code, id) {
       const integration = detectIntegration(id, extensionToIntegration);
       return {
-        code: injectEcoMeta(code, id, integration)
+        code: prependJsxImportSource(injectEcoMeta(code, id, integration.name), integration.jsxImportSource)
       };
     }
   };

package/src/plugins/foreign-jsx-override-plugin.d.ts

@@ -7,6 +7,8 @@ export interface ForeignJsxOverrideOptions {
     hostJsxImportSource: string;
     /** Extensions claimed by other JSX integrations that may appear in the host graph. */
     foreignExtensions: string[];
+    /** More specific owned suffixes that must not be claimed by this override. */
+    excludeExtensions?: string[];
     /** Optional plugin name override for debug output. */
     name?: string;
 }

package/src/plugins/foreign-jsx-override-plugin.js

@@ -2,6 +2,9 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 function createForeignJsxOverridePlugin(options) {
   const extensions = options.foreignExtensions.filter((ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx"));
+  const excludedExtensions = (options.excludeExtensions ?? []).filter(
+    (ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx")
+  );
   if (extensions.length === 0) {
     return {
       name: options.name ?? "foreign-jsx-override",
@@ -16,6 +19,9 @@ function createForeignJsxOverridePlugin(options) {
     name: options.name ?? "foreign-jsx-override",
     setup(build) {
       build.onLoad({ filter }, (args) => {
+        if (excludedExtensions.some((extension) => args.path.endsWith(extension))) {
+          return void 0;
+        }
         const source = readFileSync(args.path, "utf-8");
         const loader = args.path.endsWith(".jsx") ? "jsx" : "tsx";
         if (source.includes("@jsxImportSource")) {

package/src/route-renderer/orchestration/component-render-context.d.ts

@@ -8,10 +8,18 @@ import type { EcoComponent } from '../../types/public-types.js';
  */
 export type ForeignChildInterceptionResult = {
     kind: 'inline';
+    props?: Record<string, unknown>;
 } | {
     kind: 'resolved';
     value: unknown;
 };
+export type ForeignChildRenderInterception = {
+    kind: 'inline';
+    props?: Record<string, unknown>;
+} | {
+    kind: 'resolved';
+    value: unknown;
+} | undefined;
 /**
  * Foreign-child metadata passed into the active renderer-owned runtime.
  */
@@ -50,7 +58,7 @@ type ForeignChildRenderInput = {
 export type ComponentRenderContext = {
     currentIntegration: string;
     foreignChildRuntime?: ForeignChildRuntime;
-    interceptForeignChild(input: ForeignChildRenderInput): Promise<unknown | undefined> | unknown | undefined;
+    interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
     finalizeComponentRender<T>(component: EcoComponent, content: T): T;
 };
 /**
@@ -64,7 +72,7 @@ export declare function getComponentRenderContext(): ComponentRenderContext | un
  *
  * The active runtime may resolve the foreign child immediately or keep it inline.
  */
-export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<unknown | undefined> | unknown | undefined;
+export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
 /**
  * Applies lazy trigger or injector wrapping to completed component output.
  *

package/src/route-renderer/orchestration/component-render-context.js

@@ -32,9 +32,9 @@ class ContextualComponentRenderRuntime extends ComponentRenderOutputRuntime {
   }
   applyForeignChildInterceptionResult(result) {
     if (result.kind === "resolved") {
-      return result.value;
+      return result;
     }
-    return void 0;
+    return result.props ? result : void 0;
   }
   /**
    * Resolves one foreign-child interception through the active runtime.

package/src/route-renderer/orchestration/foreign-subtree-execution.service.d.ts

@@ -47,6 +47,7 @@ export interface ForeignSubtreeQueuedHtmlOptions<TContext extends QueuedForeignS
     queueLabel: string;
     renderQueuedChildren(children: unknown, runtimeContext: TContext, queuedResolutionsByToken: Map<string, QueuedForeignSubtreeResolution>, resolveToken: (token: string) => Promise<string>): Promise<{
         assets: ProcessedAsset[];
+        children?: unknown;
         html?: string;
     }>;
     getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
@@ -64,6 +65,7 @@ export interface ForeignSubtreeQueuedHtmlOptions<TContext extends QueuedForeignS
 export declare class ForeignSubtreeExecutionService {
     private readonly queuedForeignSubtreeResolutionService;
     constructor(queuedForeignSubtreeResolutionService?: QueuedForeignSubtreeResolutionService);
+    private requiresForeignChildRuntime;
     /**
      * Returns whether the current render pass must hand the child off to a foreign owner.
      */

package/src/route-renderer/orchestration/foreign-subtree-execution.service.js

@@ -5,11 +5,27 @@ import {
 import {
   QueuedForeignSubtreeResolutionService
 } from "./queued-foreign-subtree-resolution.service.js";
+function isMarkupNodeLike(value) {
+  return typeof value === "object" && value !== null && "nodeType" in value && typeof value.nodeType === "number" && (!("outerHTML" in value) || typeof value.outerHTML === "string");
+}
 class ForeignSubtreeExecutionService {
   queuedForeignSubtreeResolutionService;
   constructor(queuedForeignSubtreeResolutionService = new QueuedForeignSubtreeResolutionService()) {
     this.queuedForeignSubtreeResolutionService = queuedForeignSubtreeResolutionService;
   }
+  requiresForeignChildRuntime(input) {
+    const children = input.children ?? input.props.children;
+    if (children === void 0 || children === null) {
+      return false;
+    }
+    if (typeof children === "string") {
+      return false;
+    }
+    if (typeof children !== "object") {
+      return false;
+    }
+    return !isMarkupNodeLike(children);
+  }
   /**
    * Returns whether the current render pass must hand the child off to a foreign owner.
    */
@@ -25,7 +41,10 @@ class ForeignSubtreeExecutionService {
   createFailFastRuntime(rendererName) {
     const interceptForeignChild = (input) => {
       if (!this.shouldDelegateForeignChild(input)) {
-        return { kind: "inline" };
+        return {
+          kind: "inline",
+          props: "props" in input && input.props ? { ...input.props } : void 0
+        };
       }
       throw new Error(
         `[ecopages] ${rendererName} renderer crossed into ${input.targetIntegration} without a renderer-owned foreign-child runtime. Override createForeignChildRuntime() to resolve foreign children inside the owning renderer.`
@@ -63,8 +82,11 @@ class ForeignSubtreeExecutionService {
         if (children === void 0) {
           return { assets: [], html: void 0 };
         }
+        if (typeof children !== "string" && !isMarkupNodeLike(children)) {
+          return { assets: [], children };
+        }
         const html = await this.resolveQueuedTokens(
-          typeof children === "string" ? children : String(children ?? ""),
+          typeof children === "string" ? children : children.outerHTML ?? String(children ?? ""),
           queuedResolutionsByToken,
           resolveToken
         );
@@ -105,7 +127,7 @@ class ForeignSubtreeExecutionService {
     if (delegatedForeignChildRender) {
       return delegatedForeignChildRender;
     }
-    const hasForeignChildren = options.hasForeignChildDescendants(options.input.component);
+    const hasForeignChildren = options.hasForeignChildDescendants(options.input.component) || this.requiresForeignChildRuntime(options.input);
     const activeRenderContext = getComponentRenderContext();
     if (!hasForeignChildren) {
       if (!activeRenderContext || activeRenderContext.currentIntegration === options.currentIntegrationName) {
@@ -188,7 +210,12 @@ class ForeignSubtreeExecutionService {
     if (owningRenderer.name === options.currentIntegrationName) {
       return void 0;
     }
-    return await options.run(owningRenderer, this.withRendererCache(options.input, options.rendererCache));
+    const delegatedInputWithCache = this.withRendererCache(options.input, options.rendererCache);
+    const delegatedChildren = delegatedInputWithCache.children ?? delegatedInputWithCache.props.children;
+    return await options.run(owningRenderer, {
+      ...delegatedInputWithCache,
+      children: delegatedChildren
+    });
   }
   async resolveQueuedTokens(html, queuedResolutionsByToken, resolveToken) {
     let resolvedHtml = html;

package/src/route-renderer/orchestration/integration-renderer.js

@@ -15,6 +15,9 @@ import {
   ForeignSubtreeExecutionService
 } from "./foreign-subtree-execution.service.js";
 import {} from "./queued-foreign-subtree-resolution.service.js";
+function isMarkupNodeLike(value) {
+  return typeof value === "object" && value !== null && "nodeType" in value && typeof value.nodeType === "number" && "outerHTML" in value && typeof value.outerHTML === "string";
+}
 class IntegrationRenderer {
   appConfig;
   assetProcessingService;
@@ -348,7 +351,15 @@ class IntegrationRenderer {
    * @returns Structured component render result for orchestration paths.
    */
   async renderStringComponentWithSerializedChildren(input, component) {
-    const props = input.children === void 0 ? input.props : { ...input.props, children: input.children };
+    const serializedChildren = input.children === void 0 ? void 0 : typeof input.children === "string" ? input.children : isMarkupNodeLike(input.children) ? input.children.outerHTML : void 0;
+    if (input.children !== void 0 && serializedChildren === void 0) {
+      const componentFile = input.component.config?.__eco?.file ?? "unknown component";
+      const childTag = Object.prototype.toString.call(input.children);
+      throw new TypeError(
+        `[ecopages] ${this.name} renderer expected serialized children for ${componentFile}, received ${childTag}.`
+      );
+    }
+    const props = serializedChildren === void 0 ? input.props : { ...input.props, children: serializedChildren };
     const content = await component(props);
     const html = String(content);
     const assets = input.component.config?.dependencies && typeof this.assetProcessingService?.processDependencies === "function" ? await this.processComponentDependencies([input.component]) : void 0;

package/src/route-renderer/orchestration/queued-foreign-subtree-resolution.service.d.ts

@@ -30,6 +30,7 @@ type QueuedForeignSubtreeIntegrationContext = BaseIntegrationContext & Record<st
 type QueuedForeignSubtreeChildRenderResult = {
     assets: ProcessedAsset[];
     html?: string;
+    children?: unknown;
 };
 /**
  * Lower-level queue orchestration for renderer-owned foreign-child runtimes that emit

package/src/route-renderer/orchestration/queued-foreign-subtree-resolution.service.js

@@ -21,7 +21,10 @@ class QueuedForeignSubtreeResolutionService {
     const runtimeContext = this.ensureRuntimeContext(options);
     const interceptForeignChild = (input) => {
       if (!options.shouldQueueForeignChild(input)) {
-        return { kind: "inline" };
+        return {
+          kind: "inline",
+          props: { ...input.props }
+        };
       }
       runtimeContext.nextForeignSubtreeId += 1;
       const foreignSubtreeId = runtimeContext.nextForeignSubtreeId;
@@ -54,13 +57,19 @@ class QueuedForeignSubtreeResolutionService {
       return { assets: [], html: options.html };
     }
     const runtimeContext = options.runtimeContext;
-    const queuedResolutionsByToken = new Map(
-      runtimeContext.queuedResolutions.map((resolution) => [resolution.token, resolution])
-    );
+    const queuedResolutionsByToken = /* @__PURE__ */ new Map();
     const resolvedHtmlByToken = /* @__PURE__ */ new Map();
     const resolvingTokens = /* @__PURE__ */ new Set();
     const collectedAssets = [];
+    const syncQueuedResolutions = () => {
+      for (const resolution of runtimeContext.queuedResolutions) {
+        if (!queuedResolutionsByToken.has(resolution.token)) {
+          queuedResolutionsByToken.set(resolution.token, resolution);
+        }
+      }
+    };
     const resolveToken = async (token) => {
+      syncQueuedResolutions();
       const cachedHtml = resolvedHtmlByToken.get(token);
       if (cachedHtml) {
         return cachedHtml;
@@ -82,6 +91,7 @@ class QueuedForeignSubtreeResolutionService {
           queuedResolutionsByToken,
           resolveToken
         );
+        syncQueuedResolutions();
         if (renderedChildren.assets.length > 0) {
           collectedAssets.push(...renderedChildren.assets);
         }
@@ -89,7 +99,7 @@ class QueuedForeignSubtreeResolutionService {
           {
             component: resolution.component,
             props: { ...resolution.props },
-            children: renderedChildren.html,
+            children: renderedChildren.html ?? renderedChildren.children,
             integrationContext: {
               rendererCache: runtimeContext.rendererCache,
               componentInstanceId: resolution.componentInstanceId
@@ -116,7 +126,9 @@ class QueuedForeignSubtreeResolutionService {
       }
     };
     let resolvedHtml = options.html;
-    for (const resolution of runtimeContext.queuedResolutions) {
+    for (let index = 0; index < runtimeContext.queuedResolutions.length; index += 1) {
+      syncQueuedResolutions();
+      const resolution = runtimeContext.queuedResolutions[index];
       if (!resolvedHtml.includes(resolution.token)) {
         continue;
       }

package/src/services/module-loading/app-module-loader.service.d.ts

@@ -1,7 +1,7 @@
-import type { PageModuleImportOptions } from './page-module-import.service.js';
+import type { PageModuleBuildImportOptions } from './page-module-import.service.js';
 export type AppModuleLoaderOwner = 'bun' | 'host';
 export interface AppModuleLoader {
     readonly owner: AppModuleLoaderOwner;
-    importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
+    importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T>;
     invalidateDevelopmentGraph(): void;
 }

package/src/services/module-loading/app-server-module-transpiler.service.js

@@ -1,5 +1,6 @@
 import { getAppBuildExecutor } from "../../build/build-adapter.js";
 import path from "node:path";
+import { createForeignJsxOverridePlugin } from "../../plugins/foreign-jsx-override-plugin.js";
 import { DevelopmentInvalidationService } from "../invalidation/development-invalidation.service.js";
 import {} from "./app-module-loader.service.js";
 import { createAppNodeBootstrapPlugin } from "./node-bootstrap-plugin.js";
@@ -37,6 +38,24 @@ function setAppHostModuleLoader(appConfig, hostModuleLoader) {
     hostModuleLoader
   };
 }
+function getOwningIntegration(appConfig, filePath) {
+  return appConfig.integrations?.flatMap(
+    (integration) => integration.extensions.filter((extension) => filePath.endsWith(extension)).map((extension) => ({ integration, extension }))
+  ).sort((left, right) => right.extension.length - left.extension.length)[0]?.integration;
+}
+function getBunOwnedJsxPlugins(appConfig) {
+  const jsxExtensions = (appConfig.integrations ?? []).filter((integration) => integration.jsxImportSource).flatMap(
+    (integration) => integration.extensions.filter((extension) => extension.endsWith(".tsx") || extension.endsWith(".jsx")).map((extension) => ({ integration, extension }))
+  ).sort((left, right) => right.extension.length - left.extension.length);
+  return jsxExtensions.map(
+    ({ integration, extension }) => createForeignJsxOverridePlugin({
+      hostJsxImportSource: integration.jsxImportSource,
+      foreignExtensions: [extension],
+      excludeExtensions: jsxExtensions.filter((candidate) => candidate.extension.length > extension.length).filter((candidate) => candidate.extension.endsWith(extension)).map((candidate) => candidate.extension),
+      name: `ecopages-bun-jsx-ownership-${integration.name}-${extension.replace(/[^a-zA-Z0-9]+/g, "-")}`
+    })
+  );
+}
 function createAppModuleLoader(appConfig) {
   const invalidationService = new DevelopmentInvalidationService(appConfig);
   const pageModuleImportService = new PageModuleImportService({
@@ -44,18 +63,35 @@ function createAppModuleLoader(appConfig) {
     getHostModuleLoader: () => getAppHostModuleLoader(appConfig)
   });
   const getDefaultPlugins = typeof Bun === "undefined" && appConfig.rootDir ? () => [createAppNodeBootstrapPlugin(appConfig)] : () => [];
+  const appLoaderPlugins = Array.from(appConfig.loaders?.values() ?? []);
+  const bunOwnedJsxPlugins = typeof Bun !== "undefined" ? getBunOwnedJsxPlugins(appConfig) : [];
   const appModuleLoader = {
     get owner() {
       return getAppModuleLoaderOwner(appConfig);
     },
     pageModuleImportService,
     async importModule(options) {
-      const mergedPlugins = [...getDefaultPlugins(), ...options.plugins ?? []];
+      const invalidationVersion = options.invalidationVersion ?? invalidationService.getServerModuleInvalidationVersion();
+      const owningIntegration = getOwningIntegration(appConfig, options.filePath);
+      const owningJsxImportSource = owningIntegration?.jsxImportSource;
+      const mergedPlugins = [
+        ...getDefaultPlugins(),
+        ...appLoaderPlugins,
+        ...bunOwnedJsxPlugins,
+        ...options.plugins ?? []
+      ];
       return await pageModuleImportService.importModule({
         ...options,
         ...mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {},
+        ...typeof Bun !== "undefined" && owningJsxImportSource ? {
+          jsx: {
+            development: process.env.NODE_ENV === "development",
+            importSource: owningJsxImportSource,
+            runtime: "automatic"
+          }
+        } : {},
         buildExecutor: options.buildExecutor ?? getAppBuildExecutor(appConfig),
-        invalidationVersion: options.invalidationVersion ?? invalidationService.getServerModuleInvalidationVersion()
+        invalidationVersion
       });
     },
     invalidateDevelopmentGraph() {

package/src/services/module-loading/node-bootstrap-plugin.js

@@ -91,6 +91,78 @@ function resolveSpecifier(specifier, parentPath) {
 function resolveFromCore(specifier) {
   return createRequire(import.meta.url).resolve(specifier);
 }
+function readPackageManifest(packageDir) {
+  const packageJsonPath = path.join(packageDir, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function findInstalledPackageDir(packageName, parentPath) {
+  let currentPath = path.dirname(parentPath);
+  const packageSegments = packageName.split("/");
+  while (true) {
+    const candidateDir = path.join(currentPath, "node_modules", ...packageSegments);
+    if (existsSync(path.join(candidateDir, "package.json"))) {
+      return candidateDir;
+    }
+    const nextPath = path.dirname(currentPath);
+    if (nextPath === currentPath) {
+      return void 0;
+    }
+    currentPath = nextPath;
+  }
+}
+function resolvePackageExportTarget(packageDir, target) {
+  if (typeof target === "string") {
+    return path.resolve(packageDir, target);
+  }
+  if (Array.isArray(target)) {
+    for (const candidate of target) {
+      const resolvedTarget = resolvePackageExportTarget(packageDir, candidate);
+      if (resolvedTarget) {
+        return resolvedTarget;
+      }
+    }
+    return void 0;
+  }
+  if (!target || typeof target !== "object") {
+    return void 0;
+  }
+  const record = target;
+  return resolvePackageExportTarget(packageDir, record.import) ?? resolvePackageExportTarget(packageDir, record.default) ?? resolvePackageExportTarget(packageDir, record.require);
+}
+function resolveInstalledPackageTarget(specifier, parentPath) {
+  const packageName = getPackageNameFromSpecifier(specifier);
+  const packageDir = findInstalledPackageDir(packageName, parentPath);
+  if (!packageDir) {
+    return void 0;
+  }
+  const manifest = readPackageManifest(packageDir);
+  if (!manifest) {
+    return void 0;
+  }
+  const subpath = specifier === packageName ? "." : `./${specifier.slice(packageName.length + 1)}`;
+  const exportsField = manifest.exports;
+  if (exportsField !== void 0) {
+    const exportsRecord = exportsField;
+    const hasSubpathKeys = typeof exportsField === "object" && exportsField !== null && Object.keys(exportsRecord).some((key) => key.startsWith("."));
+    const exportTarget = hasSubpathKeys ? resolvePackageExportTarget(packageDir, exportsRecord[subpath]) : subpath === "." ? resolvePackageExportTarget(packageDir, exportsField) : void 0;
+    if (exportTarget && existsSync(exportTarget)) {
+      return exportTarget;
+    }
+  }
+  if (subpath !== ".") {
+    return void 0;
+  }
+  const mainTarget = manifest.module ?? manifest.main ?? "index.js";
+  const resolvedMainTarget = path.resolve(packageDir, mainTarget);
+  return existsSync(resolvedMainTarget) ? resolvedMainTarget : void 0;
+}
 function findResolutionParent(importer, projectDir) {
   if (!importer || !path.isAbsolute(importer)) {
     return path.join(projectDir, "package.json");
@@ -135,6 +207,16 @@ function resolveNodeBootstrapDependency(args, options) {
   }
   const resolveParent = findResolutionParent(args.importer, options.projectDir);
   if (args.path.startsWith("@ecopages/")) {
+    const packageName = getPackageNameFromSpecifier(args.path);
+    const isBareWorkspacePackage = args.path === packageName;
+    const installedResolvedPath = resolveInstalledPackageTarget(args.path, resolveParent);
+    if (installedResolvedPath) {
+      return { path: installedResolvedPath };
+    }
+    if (!isBareWorkspacePackage) {
+      const resolvedSubpath = resolveSpecifier(args.path, resolveParent);
+      return { path: resolvedSubpath };
+    }
     let resolvedPath2;
     try {
       resolvedPath2 = resolveFromCore(args.path);
@@ -142,7 +224,6 @@ function resolveNodeBootstrapDependency(args, options) {
       try {
         resolvedPath2 = resolveSpecifier(args.path, resolveParent);
       } catch {
-        const packageName = getPackageNameFromSpecifier(args.path);
         const candidatePath = path.join(options.projectDir, "node_modules", packageName);
         const candidatePackageJson = path.join(candidatePath, "package.json");
         if (existsSync(candidatePackageJson)) {

package/src/services/module-loading/page-module-import.service.d.ts

@@ -1,16 +1,33 @@
 import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
 import type { SourceModuleLoaderFactory } from './module-loading-types.js';
-export interface PageModuleImportOptions {
+interface PageModuleImportBaseOptions {
     filePath: string;
-    rootDir: string;
-    outdir: string;
     bypassCache?: boolean;
     cacheScope?: string;
-    buildExecutor?: BuildExecutor;
     invalidationVersion?: number;
+}
+/**
+ * Options for imports that must pass through the Ecopages build pipeline.
+ *
+ * @remarks
+ * Callers should use build mode for framework-owned page modules and any other
+ * source that relies on Ecopages build resolution before runtime execution.
+ */
+export interface PageModuleBuildImportOptions extends PageModuleImportBaseOptions {
+    rootDir: string;
+    outdir: string;
+    buildExecutor?: BuildExecutor;
     splitting?: boolean;
     externalPackages?: boolean;
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
     plugins?: EcoBuildPlugin[];
     transpileErrorMessage?: (details: string) => string;
     noOutputMessage?: (filePath: string) => string;
@@ -30,12 +47,13 @@ export interface PageModuleImportDependencies {
     getHostModuleLoader: SourceModuleLoaderFactory;
 }
 /**
- * Loads source page modules in a runtime-agnostic way.
+ * Loads page-like modules through the Ecopages build pipeline.
  *
- * This service centralizes the Bun-vs-Node import strategy used by route
- * scanning, page data loading, and request-time page inspection. In Bun it can
- * import source files directly; in Node it transpiles the file into a dedicated
- * output directory first and then imports the generated module.
+ * This service centralizes the shared build-first import strategy used by route
+ * scanning, page data loading, and request-time page inspection. In Node
+ * development it can still delegate compatible source imports to the active
+ * host loader, but the public contract remains one transpile-targeted module
+ * loading path.
  *
  * Keeping this logic in one place prevents subtle drift in cache-busting,
  * transpilation settings, and error semantics across the different callers.
@@ -71,6 +89,7 @@ export declare class PageModuleImportService {
      * @param options Runtime-specific import settings.
      * @returns The loaded module.
      */
-    importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
+    importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T>;
     private loadModule;
 }
+export {};

package/src/services/module-loading/page-module-import.service.js

@@ -47,8 +47,9 @@ class PageModuleImportService {
    * @returns The loaded module.
    */
   async importModule(options) {
-    const { filePath, rootDir, externalPackages, splitting } = options;
+    const { filePath } = options;
     const invalidationVersion = options.invalidationVersion ?? this.developmentInvalidationVersion;
+    const { externalPackages, splitting } = options;
     const fileHash = this.dependencies.hashFile(filePath);
     const hostModuleLoader = typeof Bun === "undefined" && process.env.NODE_ENV === "development" && this.dependencies.canLoadSourceModuleFromHost(filePath) ? this.dependencies.getHostModuleLoader() : void 0;
     if (hostModuleLoader) {
@@ -67,10 +68,12 @@ class PageModuleImportService {
     const cacheKey = [
       runtime,
       filePath,
-      rootDir,
+      options.rootDir,
       splitting ?? "default",
       externalPackages ?? "default",
       options.cacheScope ?? "default",
+      createJsxCacheKey(options.jsx),
+      createPluginCacheKey(options.plugins),
       fileHash,
       invalidationVersion
     ].join("::");
@@ -91,28 +94,20 @@ class PageModuleImportService {
     }
   }
   async loadModule(options) {
+    const { filePath, invalidationVersion = this.developmentInvalidationVersion, cacheScope, fileHash } = options;
     const {
-      filePath,
       rootDir,
       outdir,
-      invalidationVersion = this.developmentInvalidationVersion,
       splitting,
       externalPackages,
-      cacheScope,
       transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
-      noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
-      fileHash
+      noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`
     } = options;
-    const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheScope);
-    if (typeof Bun !== "undefined") {
-      return await import(
-        /* @vite-ignore */
-        sourceModuleUrl.href
-      );
-    }
     const fileBaseName = path.basename(filePath, path.extname(filePath));
     const cacheScopeSuffix = cacheScope ? `-${sanitizeCacheScope(cacheScope)}` : "";
-    const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}.js`;
+    const invalidationSuffix = shouldVersionBuildOutputPath(invalidationVersion) ? `-v${invalidationVersion}` : "";
+    const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${invalidationSuffix}.js`;
+    const outputNamingTemplate = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${invalidationSuffix}.[ext]`;
     const buildResult = await this.dependencies.buildModule(
       {
         entrypoints: [filePath],
@@ -123,8 +118,9 @@ class PageModuleImportService {
         sourcemap: "none",
         splitting: splitting ?? true,
         minify: false,
-        naming: outputFileName,
+        naming: outputNamingTemplate,
         externalPackages: true,
+        jsx: options.jsx,
         plugins: options.plugins,
         ...externalPackages !== void 0 ? { externalPackages } : {}
       },
@@ -140,7 +136,7 @@ class PageModuleImportService {
       throw new Error(noOutputMessage(filePath));
     }
     const compiledOutputUrl = pathToFileURL(compiledOutput);
-    if (process.env.NODE_ENV === "development" || cacheScope) {
+    if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
       compiledOutputUrl.searchParams.set(
         "update",
         [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : void 0].filter((value) => value !== void 0).join("-")
@@ -154,7 +150,7 @@ class PageModuleImportService {
 }
 function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheScope) {
   const moduleUrl = pathToFileURL(filePath);
-  if (process.env.NODE_ENV === "development" || cacheScope) {
+  if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
     moduleUrl.searchParams.set(
       "update",
       [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : void 0].filter((value) => value !== void 0).join("-")
@@ -162,9 +158,34 @@ function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheSc
   }
   return moduleUrl;
 }
+function shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope) {
+  return process.env.NODE_ENV === "development" || invalidationVersion > 0 || !!cacheScope;
+}
+function shouldVersionBuildOutputPath(invalidationVersion) {
+  return typeof Bun !== "undefined" && invalidationVersion > 0;
+}
 function sanitizeCacheScope(cacheScope) {
   return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
 }
+function createJsxCacheKey(jsx) {
+  if (!jsx) {
+    return "jsx:default";
+  }
+  return JSON.stringify({
+    development: jsx.development ?? false,
+    factory: jsx.factory ?? null,
+    fragment: jsx.fragment ?? null,
+    importSource: jsx.importSource ?? null,
+    runtime: jsx.runtime ?? null,
+    sideEffects: jsx.sideEffects ?? null
+  });
+}
+function createPluginCacheKey(plugins) {
+  if (!plugins || plugins.length === 0) {
+    return "plugins:default";
+  }
+  return `plugins:${plugins.map((plugin) => plugin.name).join(",")}`;
+}
 export {
   PageModuleImportService
 };

package/src/services/module-loading/server-module-transpiler.service.d.ts

@@ -1,9 +1,9 @@
 import type { BuildExecutor } from '../../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
 import type { AppModuleLoader } from './app-module-loader.service.js';
-import { type PageModuleImportOptions } from './page-module-import.service.js';
+import { type PageModuleBuildImportOptions } from './page-module-import.service.js';
 import type { SourceModuleLoaderFactory } from './module-loading-types.js';
-export type ServerModuleTranspilerOptions = Omit<PageModuleImportOptions, 'rootDir' | 'buildExecutor'>;
+export type ServerModuleTranspilerOptions = Omit<PageModuleBuildImportOptions, 'rootDir' | 'buildExecutor'>;
 export type ServerModuleImportDependency = Pick<AppModuleLoader, 'importModule' | 'invalidateDevelopmentGraph'>;
 /**
  * Immutable execution context for one server-transpiler instance.

package/src/types/public-types.d.ts

@@ -127,7 +127,7 @@ export interface DefaultHmrContext {
     /**
      * Server-side module loader owned by the active app/runtime.
      */
-    importServerModule<T = unknown>(filePath: string): Promise<T>;
+    importServerModule<T = unknown>(filePath: string | URL): Promise<T>;
 }
 /**
  * Represents an event broadcast to connected clients via the ClientBridge.
@@ -431,10 +431,10 @@ export interface LayoutProps<T = EcoPagesElement> extends Partial<RequestPageCon
 /**
  * Represents the props for the HTML template of a page.
  */
-export interface HtmlTemplateProps extends PageHeadProps {
-    children: EcoPagesElement;
+export interface HtmlTemplateProps<T = EcoPagesElement> extends PageHeadProps<T> {
+    children: T;
     language?: string;
-    headContent?: EcoPagesElement;
+    headContent?: T;
     pageProps: Record<string, unknown>;
 }
 /**
@@ -823,6 +823,24 @@ export interface ResponseOptions {
  * Provides methods to render eco.page views and return formatted responses.
  */
 export interface RenderContext {
+    /**
+     * Import a server-executed module through the active Ecopages module loader.
+     *
+     * This applies the runtime's cache-busting and source-transpilation rules so
+     * request-time lazy imports participate in development invalidation.
+     *
+     * @param filePath - Absolute filesystem path or file URL for the server module
+     */
+    importServerModule<T = unknown>(filePath: string | URL): Promise<T>;
+    /**
+     * Import a server module through the active Ecopages module loader and render
+     * its default-exported eco.page view.
+     *
+     * @param filePath - Absolute filesystem path or file URL for the server module
+     * @param props - Props to pass to the default-exported view
+     * @param options - Optional status code and headers
+     */
+    renderServerModule<P = Record<string, unknown>>(filePath: string | URL, props?: P, options?: RenderOptions): Promise<Response>;
     /**
      * Render an eco.page view with full layout and includes.
      * @param view - The eco.page component to render
@@ -1020,7 +1038,7 @@ export interface ApiHandlerContext<TRequest extends Request = Request, TServer =
  * response helpers, but final document rendering stays owned by the page route
  * execution path.
  */
-export interface FileRouteMiddlewareContext<TRequest extends Request = Request, TServer = any> extends Omit<ApiHandlerContext<TRequest, TServer>, 'render' | 'renderPartial'> {
+export interface FileRouteMiddlewareContext<TRequest extends Request = Request, TServer = any> extends Omit<ApiHandlerContext<TRequest, TServer>, 'render' | 'renderPartial' | 'importServerModule' | 'renderServerModule'> {
 }
 /**
  * Next function for middleware chain.

package/CHANGELOG.md

@@ -1,91 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/core` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [UNRELEASED] — TBD
-
-### Features
-
-- Added app-owned runtime and build ownership around `createApp()`, host module loading, the browser-safe `eco` export, `eco.html()`, `eco.layout()`, and the published `EcoPagesAppConfig` surface.
-- Added boundary-plan metadata and a compatibility `renderBoundary()` payload contract for mixed-renderer orchestration.
-
-### Refactoring
-
-- Renamed route-renderer ownership and foreign-child contracts across core so ownership planning, foreign-subtree payloads, and queued foreign-subtree resolution now use the simplified terminology.
-- Introduced a single `RouteRenderFlow` owner for route render preparation and execution, removing the separate execution service seam while keeping boundary planning shared.
-- Narrowed route-render orchestration onto an explicit `RouteRenderFlowAdapter` seam and one structural Html finalization plan, reducing callback-bag plumbing between `RouteRenderFlow` and `IntegrationRenderer`.
-- Renamed renderer-owned page browser asset preparation onto an explicit `buildPageBrowserGraph()` seam so route orchestration no longer treats emitted browser dependencies as a flat route-asset append.
-- Removed the generic HMR runtime-specifier registry and plugin registration seam so core no longer carries import-map-era runtime state that integrations no longer use.
-- Moved foreign-boundary ownership validation out of boundary-plan construction so route root graphs are validated before dependency and data preparation.
-- Moved page-package classification into the asset-processing module so render orchestration no longer carries a dedicated packaging service wrapper.
-- Split file-route page middleware onto its own context contract so page middleware no longer exposes handler-only `ctx.render()` helpers and the pipeline stops carrying fake render traps.
-- Narrowed route-renderer consumers onto explicit resolver contracts, moved filesystem custom 404 rendering back under the filesystem matcher, and shared explicit static render preparation between runtime and static generation.
-
-- Added the `@ecopages/core/dev/host-runtime` seam so host integrations such as the Vite plugin use one explicit development bridge instead of importing host-module-loader and invalidation internals directly.
-- Moved extension-facing merge and assertion helpers behind the integration and processor plugin entrypoints so MDX and image processing no longer depend on raw `utils/deep-merge` or `utils/invariant` package paths.
-- Re-exported shared build-plugin authoring types through the integration and processor plugin entrypoints so extension packages depend on plugin surfaces instead of the raw `build/build-types` module.
-- Removed the legacy `@ecopages/core/errors/locals-access-error` and `@ecopages/core/adapters/bun/client-bridge` exports after moving their remaining consumers to the public `errors` and root type surfaces.
-- Removed the unused `@ecopages/core/utils/parse-cli-args` and `@ecopages/core/services/module-loading/app-server-module-transpiler.service` exports from the published package surface.
-- Removed the unused `@ecopages/core/bun/create-app` and `@ecopages/core/route-renderer/template-serialization` exports to keep the published package surface aligned with the documented entrypoints.
-- Removed the legacy `@ecopages/core/internal-types` export now that the public root package exposes the supported `EcoPagesAppConfig` contract.
-- Removed the duplicate `@ecopages/core/router/client/navigation-coordinator` export in favor of the canonical `@ecopages/core/router/navigation-coordinator` subpath.
-- Bundled page-local component stylesheets and standard file scripts into page-owned assets before processing, reducing per-page asset fan-out in emitted HTML.
-- Grouped Ecopages JSX page and lazy dependency entries into one multi-entry browser build so shared chunks can be emitted once without relying on the runtime alias vendor path.
-- Removed the transitional flat dependency write from render preparation so final HTML injection now follows the structured page-package path only.
-- Consolidated runtime state around shared module-loading services, app-owned build execution, and the universal `createApp()` boundary.
-- Simplified route-renderer orchestration around renderer-owned boundary runtimes, shared string-boundary queue helpers, and a smaller component render context.
-- Centralized shared integration renderer bootstrapping so package integrations only append renderer-specific config instead of duplicating core lifecycle wiring.
-- Moved shared queued boundary resolution to attachment-policy payloads and constructor-injectable planning services.
-- Extracted shared page, layout, and document-shell composition into a narrow `RouteShellComposer` while keeping renderer-owned boundary handoff in `IntegrationRenderer`.
-- Removed marker-era compatibility capture, the shared route-level fallback resolver, deprecated `@ecopages/core/node*` escape hatches, and other dead route-renderer internals.
-- Replaced the split `FSRouter` and `FSRouterScanner` flow with one `RouteRegistry` seam for filesystem route discovery, request matching, and static-generation planning.
-
-### Bug Fixes
-
-- Fixed integration registry typing so `ConfigBuilder.setIntegrations()` accepts heterogeneous framework plugins without rejecting valid JSX or React integrations at type-check time.
-- Fixed page-owned dependency packaging so final Html output suppresses bundled source stylesheet assets that were reintroduced later during shell-time asset merging.
-- Fixed development page dependency packaging so script Dependencies stay source-backed for HMR instead of being collapsed into one page-owned script bundle.
-- Fixed Bun preview builds to start the static preview server only after static generation releases the live build server port, preventing preview mode from double-binding the configured port.
-- Fixed router-owned HMR current-page reloads to clear persisted layout caches so active shared layouts pick up updated implementations during development.
-- Fixed router-owned HMR layout refreshes to reuse the active HMR page entry instead of stale static bootstrap assets during persisted-layout reloads.
-- Fixed fetch-mode static generation to normalize absolute routes onto the active build runtime origin, restoring preview prerendering for routes discovered from absolute router entries.
-- Fixed global lazy-trigger bootstrap emission to inline the full bootstrap runtime in final HTML, removing separate initial injector bootstrap and runtime requests.
-- Fixed Ecopages JSX lazy-trigger finalization to preserve SSR custom-element markup nodes instead of coercing them to `[object Object]` inside parent renders.
-- Fixed legacy scripts-injector wrapping and grouped content-script bundling cleanup so non-string JSX SSR output stays intact and failed grouped builds do not leak temporary entries.
-- Fixed Ecopages JSX dependency resolution so page bundling now follows only declared `dependencies.scripts` entries, preventing SSR-only imports and lazy-declared scripts from being promoted into the page bundle.
-- Fixed Ecopages JSX lazy dependency bundling to keep page and lazy entries separate, preventing lazy scripts from forcing extra shared chunk requests into the page bundle.
-- Fixed Ecopages JSX dependency emission to collapse bundleable component CSS and module scripts into page-owned assets while preserving lazy trigger scripts.
-- Fixed Ecopages JSX page-owned dependency bundles to keep using the shared JSX and Radiant vendor runtimes so lazy chunks do not trigger duplicate runtime downloads.
-- Fixed Ecopages JSX page-owned browser bundles to keep intrinsic custom-element scripts out of final HTML when the current component tree already imports them, reducing docs home page script fan-out to one page bundle.
-- Fixed Node static builds so `ecopages build` no longer fails when the configured serve port is already in use.
-- Fixed mixed-integration page, layout, document, and component rendering to resolve foreign boundaries inside their owning renderer across the built-in integrations.
-- Fixed host/runtime module loading, published build-helper exports, asset output normalization, explicit render flows, and static or preview build stability across Bun, Node, Vite, and Nitro.
-- Fixed development project watcher setup to register chokidar paths and handlers only once per app runtime.
-- Fixed development script-entry registration to build only the requested HMR entrypoint instead of fanning out across all watched script entrypoints during startup.
-- Fixed Node bootstrap runtime package linking to refresh dangling `.eco/node_modules` symlinks instead of failing with `EEXIST` during page transpilation.
-- Fixed request-time and static-generation page inspection to preserve integration-specific page loading without reusing the normal render module identity.
-- Fixed Node preview and static-generation React runtime resolution so app-owned page modules and server rendering share one React module identity.
-- Fixed Bun browser output normalization so batched multi-entrypoint HMR rebuilds match emitted files to their expected served paths instead of Bun output order.
-- Fixed render-preparation graph traversal so sparse component dependency arrays do not break custom 404 rendering or file-system response fallback flows.
-
-### Documentation
-
-- Added architecture and API documentation for config, plugins, services, adapters, HMR, routing, and rendering.
-- Documented that Html-owned dependency assets stay shared while page, layout, and component dependency assets are packaged per route.
-
-### Tests
-
-- Added regression coverage for app-owned runtime services, Node fallback paths, and cross-runtime invalidation behavior.
-- Strengthened the core ghtml integration tests so route and explicit render paths await real outcomes and cover `renderToResponse` behavior.
-- Added core regression coverage for boundary plans, payload contracts, and typed mixed-boundary context flow.
-- Added router and static-generation regression coverage for `RouteRegistry`, explicit static route expansion, and file-response fallbacks.
-
----
-
-## Migration Notes
-
-- `createApp` is now the recommended entrypoint. Import it from `@ecopages/core/create-app`.
-- `defineApiHandler` keeps the same call shape, but the handler context is now explicitly runtime-agnostic.
-- The old explicit `renderingMode` config option has been removed and full orchestration is always active.