@ecopages/core 0.2.0-alpha.12 → 0.2.0-alpha.13

package/CHANGELOG.md

@@ -8,39 +8,18 @@ All notable changes to `@ecopages/core` are documented here.
 
 ### Features
 
-- Added a shared runtime boundary around `createApp()`, host module loading, and explicit build ownership for Bun-native execution, Node fallback support, and Vite or Nitro hosts.
-- Added the browser-safe `eco` export, semantic `eco.html()` and `eco.layout()` helpers, and the internal `.eco` work directory.
-- Added the public `EcoPagesAppConfig` export for published integration packages.
+- 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.
 
 ### Refactoring
 
 - Consolidated runtime state around shared module-loading services, app-owned build execution, and the universal `createApp()` boundary.
-- Removed the deprecated `@ecopages/core/node*` public escape hatches and the old thin-host bootstrap internals from core.
-- Added renderer-owned deferred-template serializers so integration-specific template-shape adapters live on `IntegrationRenderer` subclasses instead of global registration state.
-- Refactored `eco` component factories to delegate deferred-boundary and lazy-output runtime behavior through component render context instead of coupling `eco.ts` directly to marker-graph internals.
-- Moved component render-context implementation under route-renderer orchestration and left `eco` with a thin compatibility re-export.
-- Moved lazy render-output helpers under route-renderer orchestration and left `eco/eco.utils` as a thin compatibility re-export so orchestration no longer depends on the `eco` implementation folder.
+- Simplified route-renderer orchestration around renderer-owned boundary runtimes, shared string-boundary queue helpers, and a smaller component render context.
+- Removed marker-era compatibility capture, the shared route-level fallback resolver, deprecated `@ecopages/core/node*` escape hatches, and other dead route-renderer internals.
 
 ### Bug Fixes
 
-- Fixed request-time module loading, host-runner interop, and include or layout HMR across Bun, Vite, and Nitro development flows.
-- Fixed published core build helpers to expose runtime specifier alias rewriting through the package export surface so integrations do not couple to core source-file paths.
-- Fixed Bun-backed browser asset output normalization to preserve concrete hashed filenames instead of leaking literal `[hash]` placeholders into emitted script URLs.
-- Fixed generated module wrapper scripts to emit canonical named-import order so identical logical wrappers reuse the same bundled asset across routes.
-- Fixed preview, static-generation, and browser bundle stability for esbuild-backed production paths.
-- Fixed deep marker-graph resolution, watch-mode route refreshes, and duplicate-core fallback references in mixed-runtime rendering.
-- Fixed deferred boundary child serialization to accept explicit template-shape payloads while ignoring unrelated plain-object props unless a renderer-specific serializer or node-like shape supports them.
-- Fixed page-root and marker-graph rendering to preserve captured component graph context and render deferred foreign components under the correct integration context.
-- Fixed npm package output to rewrite workspace dependency versions and publish built JavaScript and declaration artifacts.
-- Fixed app build manifest collection to let integrations contribute browser-only build plugins without rewriting server static-page modules.
-- Fixed Node-side page-module transpilation to target ES2022 so decorator-based server imports preserve modern ESM semantics during development and MDX loading.
-- Fixed the public `EcoPageFile` type to include explicit `componentGraphContext` exports used by marker-graph page loading.
-- Fixed cross-integration shell authoring to expose a shared public `EcoChildren` type instead of forcing local boundary-cast patterns in mixed JSX demos.
-- Fixed object-form `dependencies.scripts` entries with `content` (no `src`) to emit as blocking inline script tags instead of being bundled into hashed external files.
-- Fixed the shared foreign-JSX override build plugin to preserve JSX versus TSX loader behavior and relative-import resolution in host-owned browser bundles.
-- Fixed deferred child serialization to preserve JSX node-like payloads without leaking `nodeType` digits into mixed-integration SSR output.
-- Fixed deferred template-child serialization to preserve quoted Ecopages JSX attribute values when mixed-integration boundaries pass JSX output through foreign shells.
-- Fixed fallback component references to prefer injected `__eco` metadata and share process-wide runtime ids across duplicate module instances without eager stack-based hint registration.
+- 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.
 
 ### Documentation
 
@@ -48,12 +27,12 @@ All notable changes to `@ecopages/core` are documented here.
 
 ### Tests
 
-- Added regression coverage for Node fallback paths, shared runtime services, and cross-runtime invalidation behavior.
+- Added regression coverage for app-owned runtime services, Node fallback paths, and cross-runtime invalidation behavior.
 
 ---
 
 ## Migration Notes
 
-- `createApp` is now the recommended entrypoint. Import it from `@ecopages/core`.
+- `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.

package/README.md

@@ -134,7 +134,7 @@ export default config;
 Start the application using `createApp`. It will choose the Bun adapter when Bun is available and fall back to Node otherwise.
 
 ```typescript
-import { createApp } from '@ecopages/core';
+import { createApp } from '@ecopages/core/create-app';
 import appConfig from './eco.config';
 
 const app = await createApp({ appConfig });
@@ -198,7 +198,7 @@ Attach the handler in your `app.ts` entry:
 
 ```typescript
 // app.ts
-import { createApp } from '@ecopages/core';
+import { createApp } from '@ecopages/core/create-app';
 import { helloWorld } from './handlers/hello';
 import appConfig from './eco.config';
 
@@ -213,10 +213,11 @@ See the [official documentation](https://ecopages.app) for advanced usage, API h
 
 ## Import Structure
 
-Use the root package exports for standard authoring in Bun-native flows:
+Use the `create-app` subpath for runtime startup and the root package for standard authoring helpers:
 
 ```ts
-import { createApp, defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
+import { createApp } from '@ecopages/core/create-app';
+import { defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
 ```
 
 > [!NOTE]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.12",
+  "version": "0.2.0-alpha.13",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.12",
+    "@ecopages/file-system": "0.2.0-alpha.13",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.3",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",

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

@@ -251,7 +251,7 @@ class HmrManager {
    */
   async registerEntrypoint(entrypointPath) {
     return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
-      emit: async (normalizedEntrypoint, outputPath) => await this.emitStrictEntrypoint(normalizedEntrypoint, outputPath),
+      emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
       getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
         `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
       )
@@ -278,7 +278,7 @@ class HmrManager {
    * strategy processing without broadcasting, and then verifies that the owning
    * integration emitted the expected file.
    */
-  async emitStrictEntrypoint(entrypointPath, _outputPath) {
+  async emitStrictEntrypoint(entrypointPath) {
     await this.handleFileChange(entrypointPath, { broadcast: false });
   }
   /**

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

@@ -225,7 +225,7 @@ class NodeHmrManager {
    */
   async registerEntrypoint(entrypointPath) {
     return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
-      emit: async (normalizedEntrypoint, outputPath) => await this.emitStrictEntrypoint(normalizedEntrypoint, outputPath),
+      emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
       getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
         `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
       )
@@ -255,7 +255,7 @@ class NodeHmrManager {
    * 3. Let the strategy chain try to emit the entrypoint without broadcasting.
    * 4. Fail if the owning integration did not emit the expected output.
    */
-  async emitStrictEntrypoint(entrypointPath, _outputPath) {
+  async emitStrictEntrypoint(entrypointPath) {
     await this.handleFileChange(entrypointPath, { broadcast: false });
   }
   /**

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

@@ -132,7 +132,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      * underlying socket closes early — into a 499 response so it does not
      * incorrectly surface as a 500 in application logs.
      */
-    handleRequest(_request: Request): Promise<Response>;
+    handleRequest(request: Request): Promise<Response>;
     /**
      * Called once the HTTP server is bound and listening.
      *
@@ -149,7 +149,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
      * immediate socket destroy to prevent unhandled upgrade leaks.
      */
-    completeInitialization(_server: NodeServerInstance): Promise<void>;
+    completeInitialization(server: NodeServerInstance): Promise<void>;
 }
 /**
  * Factory function that creates and fully initialises a `NodeServerAdapter`.

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

@@ -269,12 +269,12 @@ class NodeServerAdapter extends SharedServerAdapter {
    * underlying socket closes early — into a 499 response so it does not
    * incorrectly surface as a 500 in application logs.
    */
-  async handleRequest(_request) {
+  async handleRequest(request) {
     if (!this.initialized) {
       throw new Error("Node server adapter is not initialized. Call createAdapter() first.");
     }
     try {
-      return await this.handleSharedRequest(_request, {
+      return await this.handleSharedRequest(request, {
         apiHandlers: this.apiHandlers,
         errorHandler: this.errorHandler,
         serverInstance: this.serverInstance,
@@ -303,8 +303,8 @@ class NodeServerAdapter extends SharedServerAdapter {
    * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
    * immediate socket destroy to prevent unhandled upgrade leaks.
    */
-  async completeInitialization(_server) {
-    this.serverInstance = _server;
+  async completeInitialization(server) {
+    this.serverInstance = server;
     if (this.options?.watch) {
       const { NodeHmrManager } = await import("./node-hmr-manager.js");
       const { WebSocketServer } = await import("ws");
@@ -313,7 +313,7 @@ class NodeServerAdapter extends SharedServerAdapter {
       this.hmrManager = new NodeHmrManager({ appConfig: this.appConfig, bridge: this.bridge });
       this.hmrManager.setEnabled(true);
       await this.hmrManager.buildRuntime();
-      _server.on("upgrade", (req, socket, head) => {
+      server.on("upgrade", (req, socket, head) => {
         const url = new URL(req.url ?? "/", this.runtimeOrigin);
         if (url.pathname === "/_hmr") {
           wss.handleUpgrade(req, socket, head, (ws) => {

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

@@ -130,9 +130,10 @@ export declare function createBuildAdapter(options?: {
 export declare const defaultBunBuildAdapter: BuildAdapter;
 export declare const defaultViteHostBuildAdapter: BuildAdapter;
 /**
- * @deprecated Prefer app-owned build state via `getAppBuildAdapter()`.
- * This Bun-native fallback remains only for compatibility with older helpers
- * and tests that do not yet thread app runtime state explicitly.
+ * Bun-native fallback export for callsites that still resolve build state
+ * globally.
+ *
+ * New app-aware code should prefer `getAppBuildAdapter()`.
  */
 export declare const defaultBuildAdapter: BuildAdapter;
 export declare function getDefaultBuildAdapter(ownership?: BuildOwnership): BuildAdapter;
@@ -224,9 +225,9 @@ export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildE
  */
 export declare function build(options: BuildOptions, executor?: BuildExecutor): Promise<BuildResult>;
 /**
- * @deprecated Prefer `getAppTranspileOptions()` for finalized app/runtime work.
- * This helper exists only for compatibility with Bun-native callsites that do
- * not yet have app context available.
+ * Bun-native fallback helper for callsites without app runtime context.
+ *
+ * New app-aware code should prefer `getAppTranspileOptions()`.
  */
 export declare function getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 export declare function getAppTranspileOptions(appConfig: EcoPagesAppConfig, profile: BuildTranspileProfile): BuildTranspileOptions;

package/src/build/build-adapter.js

@@ -227,9 +227,7 @@ class BunBuildAdapter {
       return void 0;
     }
     const basenamePattern = path.basename(outputPath);
-    const matcher = new RegExp(
-      `^${this.escapeRegExp(basenamePattern).replace(/\\\[hash\\\]/g, "(.+)")}$`
-    );
+    const matcher = new RegExp(`^${this.escapeRegExp(basenamePattern).replace(/\\\[hash\\\]/g, "(.+)")}$`);
     const matches = fs.readdirSync(directory).filter((candidate) => matcher.test(candidate)).sort();
     if (matches.length === 0) {
       return void 0;
@@ -259,9 +257,7 @@ class BunBuildAdapter {
         return path.join(outdir, resolvedPath);
       }
       const concreteRelativePath = path.relative(outdir, concreteOutputPath).split(path.sep).join("/");
-      const matcher = new RegExp(
-        `^${this.escapeRegExp(resolvedPath).replace(/\\\[hash\\\]/g, "(.+)")}$`
-      );
+      const matcher = new RegExp(`^${this.escapeRegExp(resolvedPath).replace(/\\\[hash\\\]/g, "(.+)")}$`);
       const match = concreteRelativePath.match(matcher);
       if (!match?.[1]) {
         return concreteOutputPath;
@@ -293,7 +289,10 @@ class BunBuildAdapter {
           continue;
         }
         normalizedOutputs[index] = {
-          path: this.relocateOutputFile(concreteOutputPath ?? normalizedOutputs[index].path, expectedOutputPath)
+          path: this.relocateOutputFile(
+            concreteOutputPath ?? normalizedOutputs[index].path,
+            expectedOutputPath
+          )
         };
       }
       return {

package/src/eco/eco.js

@@ -1,18 +1,27 @@
-import { finalizeComponentRender, tryRenderDeferredBoundary } from "./component-render-context.js";
+import {
+  finalizeComponentRender,
+  interceptComponentBoundary
+} from "../route-renderer/orchestration/component-render-context.js";
+import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
 function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;
   const comp = ((props) => {
     const componentProps = props ?? {};
-    const deferredRender = tryRenderDeferredBoundary({
+    const renderInline = () => finalizeComponentRender(comp, options.render(props));
+    const boundaryRender = interceptComponentBoundary({
       component: comp,
       props: componentProps,
       targetIntegration: integrationName
     });
-    if (deferredRender !== void 0) {
-      return deferredRender;
+    if (isThenable(boundaryRender)) {
+      return boundaryRender.then(
+        (resolvedBoundaryRender) => resolvedBoundaryRender !== void 0 ? resolvedBoundaryRender : renderInline()
+      );
     }
-    const content = options.render(props);
-    return finalizeComponentRender(comp, content);
+    if (boundaryRender !== void 0) {
+      return boundaryRender;
+    }
+    return renderInline();
   });
   comp.config = {
     __eco: options.__eco,

package/src/eco/eco.utils.d.ts

@@ -1 +1 @@
-export { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from '../route-renderer/orchestration/render-output.utils.js';
+export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/render-output.utils.js';

package/src/eco/eco.utils.js

@@ -1,4 +1,8 @@
-import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "../route-renderer/orchestration/render-output.utils.js";
+import {
+  addTriggerAttribute,
+  isThenable,
+  wrapWithScriptsInjector
+} from "../route-renderer/orchestration/render-output.utils.js";
 export {
   addTriggerAttribute,
   isThenable,

package/src/hmr/hmr-strategy.d.ts

@@ -77,8 +77,8 @@ export interface HmrAction {
  * whether they match the changed file path.
  *
  * @remarks
-     * Strategies are expected to be stateless and idempotent. The same file change
-     * should produce the same result when processed by the same strategy.
+ * Strategies are expected to be stateless and idempotent. The same file change
+ * should produce the same result when processed by the same strategy.
  *
  * @example
  * ```typescript

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

@@ -2,7 +2,7 @@
  * This module contains the ghtml renderer
  * @module
  */
-import type { EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.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.
@@ -10,6 +10,11 @@ import { IntegrationRenderer, type RenderToResponseContext } from '../../route-r
  */
 export declare class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    protected createComponentBoundaryRuntime(options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): import("../../index.browser.js").ComponentBoundaryRuntime;
     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

@@ -4,6 +4,18 @@ import {
 import { GHTML_PLUGIN_NAME } from "./ghtml.plugin.js";
 class GhtmlRenderer extends IntegrationRenderer {
   name = GHTML_PLUGIN_NAME;
+  async renderComponent(input) {
+    return this.renderStringComponentBoundaryWithQueuedForeignBoundaries(
+      input,
+      input.component
+    );
+  }
+  createComponentBoundaryRuntime(options) {
+    return this.createQueuedBoundaryRuntime({
+      boundaryInput: options.boundaryInput,
+      rendererCache: options.rendererCache
+    });
+  }
   async render({
     params,
     query,
@@ -16,42 +28,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/plugins/integration-plugin.d.ts

@@ -1,7 +1,7 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import type { EcoPagesAppConfig, IHmrManager } from '../types/internal-types.js';
 import type { HmrStrategy } from '../hmr/hmr-strategy.js';
-import type { EcoComponent, EcoPagesElement } from '../types/public-types.js';
+import type { EcoPagesElement } from '../types/public-types.js';
 import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
 import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
 import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
@@ -56,17 +56,6 @@ export interface IntegrationPluginConfig {
      */
     jsxImportSource?: string;
 }
-/**
- * Metadata used by integration-owned boundary policy.
- *
- * This payload describes the currently active integration pass together with the
- * target component boundary being entered.
- */
-export type ComponentBoundaryPolicyInput = {
-    currentIntegration: string;
-    targetIntegration?: string;
-    component: EcoComponent;
-};
 type RendererClass<C> = new (options: {
     appConfig: EcoPagesAppConfig;
     assetProcessingService: AssetProcessingService;
@@ -187,18 +176,6 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     initializeRenderer(options?: {
         rendererModules?: unknown;
     }): IntegrationRenderer<C>;
-    /**
-     * Declares whether a component boundary targeting this integration should be
-     * deferred through the marker pipeline.
-     *
-     * The default implementation never defers. Integrations that require deferred
-     * subtree rendering can override this method and return `true` when their
-     * boundary must be resolved during the marker graph stage.
-     *
-     * @param input Boundary metadata for the current render pass.
-     * @returns `true` when the boundary should be deferred; otherwise `false`.
-     */
-    shouldDeferComponentBoundary(_input: ComponentBoundaryPolicyInput): boolean;
     /**
      * Prepares build-facing contributions before the app build manifest is sealed.
      *

package/src/plugins/integration-plugin.js

@@ -140,20 +140,6 @@ class IntegrationPlugin {
     }
     return renderer;
   }
-  /**
-   * Declares whether a component boundary targeting this integration should be
-   * deferred through the marker pipeline.
-   *
-   * The default implementation never defers. Integrations that require deferred
-   * subtree rendering can override this method and return `true` when their
-   * boundary must be resolved during the marker graph stage.
-   *
-   * @param input Boundary metadata for the current render pass.
-   * @returns `true` when the boundary should be deferred; otherwise `false`.
-   */
-  shouldDeferComponentBoundary(_input) {
-    return false;
-  }
   /**
    * Prepares build-facing contributions before the app build manifest is sealed.
    *