@ecopages/core 0.2.0-beta.12 → 0.2.0-beta.14

package/src/adapters/shared/fs-server-response-matcher.js

@@ -39,13 +39,13 @@ class FileSystemResponseMatcher {
   async handleNoMatch(requestUrl) {
     const isStaticFileRequest = ServerUtils.hasKnownExtension(requestUrl);
     if (!isStaticFileRequest) {
-      return this.renderCustomNotFoundResponse();
+      return this.renderCustomNotFoundResponseOrServerError(requestUrl);
     }
     const relativeUrl = requestUrl.startsWith("/") ? requestUrl.slice(1) : requestUrl;
     const filePath = path.join(this.assetPrefix, relativeUrl);
     const contentType = ServerUtils.getContentType(filePath);
     const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
-    return response ?? this.renderCustomNotFoundResponse();
+    return response ?? this.renderCustomNotFoundResponseOrServerError(requestUrl);
   }
   /**
    * Handles a matched file-system page route.
@@ -100,17 +100,13 @@ class FileSystemResponseMatcher {
         return error;
       }
       if (error instanceof LocalsAccessError) {
-        return new Response(error.message, {
-          status: 500,
-          headers: { "Content-Type": "text/plain; charset=utf-8" }
-        });
-      }
-      if (error instanceof Error) {
-        if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.requestedPathname}`);
-        }
+        return this.createInternalServerErrorResponse(error.message, match.requestedPathname, error);
       }
-      return this.renderCustomNotFoundResponse();
+      return this.createInternalServerErrorResponse(
+        error instanceof Error ? error.message : "Internal Server Error",
+        match.requestedPathname,
+        error
+      );
     }
   }
   /**
@@ -119,12 +115,9 @@ class FileSystemResponseMatcher {
    */
   async renderCustomNotFoundResponse() {
     const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+    let routeRenderer;
     try {
-      const routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
-      const result = await routeRenderer.execute({
-        file: error404TemplatePath
-      });
-      return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+      routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
     } catch {
       appLogger.debug(
         "Custom 404 template not found, falling back to default 404 response",
@@ -132,6 +125,35 @@ class FileSystemResponseMatcher {
       );
       return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
     }
+    const result = await routeRenderer.execute({
+      file: error404TemplatePath
+    });
+    return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+  }
+  async renderCustomNotFoundResponseOrServerError(pathname) {
+    try {
+      return await this.renderCustomNotFoundResponse();
+    } catch (error) {
+      if (error instanceof Response) {
+        return error;
+      }
+      return this.createInternalServerErrorResponse(
+        error instanceof Error ? error.message : "Internal Server Error",
+        pathname,
+        error
+      );
+    }
+  }
+  createInternalServerErrorResponse(message, pathname, error) {
+    if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
+      appLogger.error(`[FileSystemResponseMatcher] ${message} at ${pathname}`, error);
+    } else {
+      appLogger.error(`[FileSystemResponseMatcher] Render error at ${pathname}`, error);
+    }
+    return new Response("Internal Server Error", {
+      status: 500,
+      headers: { "Content-Type": "text/plain; charset=utf-8" }
+    });
   }
   async createExecutionPlan(match, request) {
     const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey({

package/src/dev/server-ready-message.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Optional helpers for apps that want a machine-readable "ready" log line
+ * (for example Playwright `webServer` stdout matching). Pass to `app.start(onAppStart)`.
+ */
+export declare const ECOPAGES_SERVER_READY_MARKER = "[@ecopages/ready]";
+export declare function formatServerReadyMessage(origin: string): string;

package/src/dev/server-ready-message.js

@@ -0,0 +1,8 @@
+const ECOPAGES_SERVER_READY_MARKER = "[@ecopages/ready]";
+function formatServerReadyMessage(origin) {
+  return `${ECOPAGES_SERVER_READY_MARKER} ${origin.replace(/\/$/, "")}`;
+}
+export {
+  ECOPAGES_SERVER_READY_MARKER,
+  formatServerReadyMessage
+};

package/src/eco/README.md

@@ -279,6 +279,17 @@ export default eco.page({
 });
 ```
 
+**Nested layouts (outer → inner):**
+
+```tsx
+export default eco.page({
+	layout: [MarketingShell, DocsShell],
+	render: () => <h1>Hello</h1>,
+});
+```
+
+A single layout remains equivalent to a one-element array. Normalization stores the stack on `config.layouts` and `config.layoutEntries` at factory time.
+
 ### `eco.component()`
 
 Define a reusable component with dependencies.

package/src/eco/eco-declared-component.d.ts

@@ -0,0 +1,14 @@
+import type { EcoDeclaredComponent } from '../types/public-types.js';
+export { getUndeclaredComponentDependencyMessage } from '../errors/undeclared-component-dependency-error.js';
+/**
+ * @remarks
+ * Declared components are produced by `eco.component()`, `eco.layout()`, and
+ * `eco.html()` after the component-meta plugin injects `config.__eco`.
+ */
+export declare function isEcoDeclaredComponent(component: unknown): component is EcoDeclaredComponent;
+/**
+ * @throws {UndeclaredComponentDependencyError} When the value lacks `config.__eco`.
+ */
+export declare function assertEcoDeclaredComponent(component: unknown, context?: {
+    parentComponentFile?: string;
+}): asserts component is EcoDeclaredComponent;

package/src/eco/eco-declared-component.js

@@ -0,0 +1,16 @@
+import { UndeclaredComponentDependencyError } from "../errors/undeclared-component-dependency-error.js";
+import { getUndeclaredComponentDependencyMessage } from "../errors/undeclared-component-dependency-error.js";
+function isEcoDeclaredComponent(component) {
+  return typeof component === "function" && typeof component.config?.__eco?.file === "string" && typeof component.config?.__eco?.integration === "string";
+}
+function assertEcoDeclaredComponent(component, context = {}) {
+  if (isEcoDeclaredComponent(component)) {
+    return;
+  }
+  throw new UndeclaredComponentDependencyError(context.parentComponentFile);
+}
+export {
+  assertEcoDeclaredComponent,
+  getUndeclaredComponentDependencyMessage,
+  isEcoDeclaredComponent
+};

package/src/eco/eco.browser.js

@@ -1,3 +1,4 @@
+import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from "./page-layout-normalization.js";
 function createComponentFactory(options) {
   const component2 = ((props) => options.render(props));
   component2.config = {
@@ -32,17 +33,15 @@ function page(options) {
     requires,
     middleware
   } = options;
+  const layoutEntries = normalizePageLayouts(pageLayout);
   const pageComponent = createComponentFactory({
     __eco: options.__eco,
     integration: options.integration,
-    dependencies: pageLayout ? {
-      ...dependencies,
-      components: [...dependencies?.components ?? [], pageLayout]
-    } : dependencies,
+    dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
     render
   });
-  if (pageLayout && pageComponent.config) {
-    pageComponent.config.layout = pageLayout;
+  if (pageComponent.config) {
+    applyPageLayoutConfig(pageComponent.config, layoutEntries);
   }
   if (staticPaths2) {
     pageComponent.staticPaths = staticPaths2;

package/src/eco/eco.js

@@ -4,6 +4,7 @@ import {
   interceptForeignChild
 } from "../route-renderer/orchestration/component-render-context.js";
 import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
+import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from "./page-layout-normalization.js";
 function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;
   const comp = ((props) => {
@@ -74,18 +75,16 @@ function layout(options) {
 }
 function page(options) {
   const { layout: layout2, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
+  const layoutEntries = normalizePageLayouts(layout2);
   const componentOptions = {
     __eco: options.__eco,
     integration: options.integration,
-    dependencies: layout2 ? {
-      ...dependencies,
-      components: [...dependencies?.components || [], layout2]
-    } : dependencies,
+    dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
     render
   };
   const pageComponent = createComponentFactory(componentOptions);
-  if (layout2 && pageComponent.config) {
-    pageComponent.config.layout = layout2;
+  if (pageComponent.config) {
+    applyPageLayoutConfig(pageComponent.config, layoutEntries);
   }
   if (staticPaths2) pageComponent.staticPaths = staticPaths2;
   if (staticProps2) pageComponent.staticProps = staticProps2;

package/src/eco/eco.types.d.ts

@@ -2,7 +2,7 @@
  * Type definitions for the eco namespace API
  * @module
  */
-import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayoutComponent, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
+import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayouts, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
 /**
  * Extracts the props type from one eco component.
@@ -81,7 +81,7 @@ export interface PageOptionsBase<T, E = EcoPagesElement> {
     __eco?: EcoInjectedMeta;
     integration?: string;
     dependencies?: EcoComponentDependencies;
-    layout?: EcoPageLayoutComponent<E>;
+    layout?: EcoPageLayouts<E>;
     /**
      * Define static paths for dynamic routes (e.g., [slug].tsx).
      * Returns all possible paths that should be pre-rendered at build time.

package/src/eco/page-layout-normalization.d.ts

@@ -0,0 +1,21 @@
+import type { EcoComponentConfig, EcoComponentDependencies, EcoPageLayoutEntry, EcoPageLayouts } from '../types/public-types.js';
+/**
+ * Normalizes `layout` page options to an outer→inner stack of layout entries.
+ */
+export declare function normalizePageLayouts<E>(layout?: EcoPageLayouts<E>): EcoPageLayoutEntry<E>[];
+/**
+ * Merges layout components into `dependencies.components` without duplicates.
+ */
+export declare function mergeLayoutDependencies(dependencies: EcoComponentDependencies | undefined, layoutEntries: EcoPageLayoutEntry[]): EcoComponentDependencies | undefined;
+/**
+ * Writes normalized layout metadata onto a page `config`.
+ */
+export declare function applyPageLayoutConfig(pageConfig: EcoComponentConfig, layoutEntries: EcoPageLayoutEntry[]): void;
+/**
+ * Migrates MDX-exported `config.layout` values onto normalized layout metadata.
+ *
+ * @remarks
+ * `eco.page({ layout })` already normalizes at factory time. MDX modules that
+ * export `config.layout` directly still need this import-time migration.
+ */
+export declare function ensurePageConfigLayouts(config: EcoComponentConfig | undefined): EcoComponentConfig | undefined;

package/src/eco/page-layout-normalization.js

@@ -0,0 +1,59 @@
+function isLayoutSpecObject(spec) {
+  return typeof spec === "object" && spec !== null && "component" in spec;
+}
+function normalizePageLayouts(layout) {
+  if (!layout) {
+    return [];
+  }
+  const specs = Array.isArray(layout) ? layout : [layout];
+  return specs.map((spec) => {
+    if (isLayoutSpecObject(spec)) {
+      return {
+        component: spec.component,
+        props: spec.props
+      };
+    }
+    return {
+      component: spec
+    };
+  });
+}
+function mergeLayoutDependencies(dependencies, layoutEntries) {
+  if (layoutEntries.length === 0) {
+    return dependencies;
+  }
+  const mergedComponents = [...dependencies?.components ?? []];
+  for (const entry of layoutEntries) {
+    if (!mergedComponents.includes(entry.component)) {
+      mergedComponents.push(entry.component);
+    }
+  }
+  return {
+    ...dependencies,
+    components: mergedComponents
+  };
+}
+function applyPageLayoutConfig(pageConfig, layoutEntries) {
+  if (layoutEntries.length === 0) {
+    return;
+  }
+  pageConfig.layouts = layoutEntries.map((entry) => entry.component);
+  pageConfig.layoutEntries = layoutEntries;
+}
+function ensurePageConfigLayouts(config) {
+  if (!config || config.layouts && config.layouts.length > 0) {
+    return config;
+  }
+  const legacyLayout = config.layout;
+  if (!legacyLayout) {
+    return config;
+  }
+  applyPageLayoutConfig(config, normalizePageLayouts(legacyLayout));
+  return config;
+}
+export {
+  applyPageLayoutConfig,
+  ensurePageConfigLayouts,
+  mergeLayoutDependencies,
+  normalizePageLayouts
+};

package/src/errors/index.d.ts

@@ -1,3 +1,4 @@
 export { HttpError } from './http-error.js';
 export type { HttpErrorDetails, HttpErrorJson } from './http-error.js';
 export { LocalsAccessError } from './locals-access-error.js';
+export { UndeclaredComponentDependencyError, getUndeclaredComponentDependencyMessage, } from './undeclared-component-dependency-error.js';

package/src/errors/index.js

@@ -1,6 +1,12 @@
 import { HttpError } from "./http-error.js";
 import { LocalsAccessError } from "./locals-access-error.js";
+import {
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
+} from "./undeclared-component-dependency-error.js";
 export {
   HttpError,
-  LocalsAccessError
+  LocalsAccessError,
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
 };

package/src/errors/undeclared-component-dependency-error.d.ts

@@ -0,0 +1,11 @@
+export declare function getUndeclaredComponentDependencyMessage(parentComponentFile?: string): string;
+/**
+ * Thrown when `dependencies.components` contains a plain function or component
+ * without plugin-injected `config.__eco` metadata.
+ */
+export declare class UndeclaredComponentDependencyError extends Error {
+    name: string;
+    /** Parent component file path when the invalid entry was declared. */
+    readonly parentComponentFile?: string;
+    constructor(parentComponentFile?: string);
+}

package/src/errors/undeclared-component-dependency-error.js

@@ -0,0 +1,17 @@
+function getUndeclaredComponentDependencyMessage(parentComponentFile) {
+  const parentHint = parentComponentFile ? ` (declared by ${parentComponentFile})` : "";
+  return `[ecopages] dependencies.components entries must be eco.component(), eco.layout(), or eco.html() components with __eco metadata${parentHint}. Plain functions and untyped components are not valid dependency entries.`;
+}
+class UndeclaredComponentDependencyError extends Error {
+  name = "UndeclaredComponentDependencyError";
+  /** Parent component file path when the invalid entry was declared. */
+  parentComponentFile;
+  constructor(parentComponentFile) {
+    super(getUndeclaredComponentDependencyMessage(parentComponentFile));
+    this.parentComponentFile = parentComponentFile;
+  }
+}
+export {
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
+};

package/src/route-renderer/orchestration/component-graph.js

@@ -25,8 +25,12 @@ function walkComponentGraph(input) {
         return;
       }
     }
-    if (input.visitLayout && ecoComponent.config?.layout?.config) {
-      visitConfig(ecoComponent.config.layout.config, integrationName);
+    if (input.visitLayout) {
+      for (const layout of ecoComponent.config?.layouts ?? []) {
+        if (layout?.config) {
+          visitConfig(layout.config, integrationName);
+        }
+      }
     }
     for (const child of ecoComponent.config?.dependencies?.components ?? []) {
       visitComponent(child, integrationName, "dependency");
@@ -40,8 +44,12 @@ function walkComponentGraph(input) {
     if (input.onConfig) {
       input.onConfig(config);
     }
-    if (input.visitLayout && config.layout?.config) {
-      visitConfig(config.layout.config, parentIntegrationName);
+    if (input.visitLayout) {
+      for (const layout of config.layouts ?? []) {
+        if (layout?.config) {
+          visitConfig(layout.config, parentIntegrationName);
+        }
+      }
     }
     for (const child of config.dependencies?.components ?? []) {
       visitComponent(child, parentIntegrationName, "dependency");

package/src/route-renderer/orchestration/document-shell-render.service.d.ts

@@ -1,13 +1,43 @@
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../types/public-types.js';
+import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../types/public-types.js';
 import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 export type DocumentShellLayoutInput = {
     component: EcoComponent;
     props?: Record<string, unknown>;
 };
+export type DocumentShellComposeChildrenContext = {
+    primaryComponent: EcoComponent;
+    primaryProps: Record<string, unknown>;
+    primaryRender?: ComponentRenderResult;
+    layouts: DocumentShellLayoutInput[];
+    rendererCache: BaseIntegrationContext['rendererCache'];
+    renderComponentWithForeignChildren: DocumentShellRenderDependencies['renderComponentWithForeignChildren'];
+};
+export type DocumentShellComposeChildrenResult = {
+    /** Serialized or element children passed to the HTML template shell. */
+    children: unknown;
+    layoutRenders: ComponentRenderResult[];
+    /**
+     * Primary/page render assets when the hook performs unified composition.
+     *
+     * @remarks
+     * Omit only when the default sequential string path runs (core renders primary first).
+     */
+    primaryRender?: ComponentRenderResult;
+};
+/**
+ * Optional hook that replaces default sequential string layout wrapping.
+ *
+ * @remarks
+ * When provided, core skips the initial primary render and expects the hook to return
+ * `children` for the HTML template. Supply `primaryRender` so dependency assets still merge.
+ */
+export type DocumentShellComposeChildrenHook = (context: DocumentShellComposeChildrenContext) => Promise<DocumentShellComposeChildrenResult>;
 export type DocumentShellComposeInput = {
     primaryComponent: EcoComponent;
     primaryProps: Record<string, unknown>;
     layout?: DocumentShellLayoutInput;
+    layouts?: DocumentShellLayoutInput[];
+    composeChildren?: DocumentShellComposeChildrenHook;
     htmlTemplate: EcoComponent;
     documentProps: Record<string, unknown>;
 };
@@ -17,6 +47,8 @@ export type DocumentShellPageRenderInput = {
         props: Record<string, unknown>;
     };
     layout?: DocumentShellLayoutInput;
+    layouts?: DocumentShellLayoutInput[];
+    composeChildren?: DocumentShellComposeChildrenHook;
     htmlTemplate: EcoComponent;
     metadata: PageMetadataProps;
     pageProps: Record<string, unknown>;
@@ -31,6 +63,10 @@ export type DocumentShellAttributeStamping = {
     applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
     applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
 };
+/**
+ * Default sequential string-child composition for document shell layers.
+ */
+export declare function composeSequentialLayoutChildren(context: DocumentShellComposeChildrenContext): Promise<DocumentShellComposeChildrenResult>;
 /**
  * Composes page or view content through optional layout and document shells.
  *

package/src/route-renderer/orchestration/document-shell-render.service.js

@@ -1,23 +1,86 @@
+function resolveDocumentShellLayouts(input) {
+  if (input.layouts && input.layouts.length > 0) {
+    return input.layouts;
+  }
+  return input.layout ? [input.layout] : [];
+}
+function resolveComponentIntegrationName(component) {
+  return component.config?.integration ?? component.config?.__eco?.integration ?? "ecopages";
+}
+async function composeSequentialLayoutChildren(context) {
+  if (!context.primaryRender) {
+    throw new Error("[ecopages] composeSequentialLayoutChildren requires primaryRender.");
+  }
+  let children = context.primaryRender.html;
+  const layoutRenders = [];
+  for (const layout of [...context.layouts].reverse()) {
+    const layoutRender = await context.renderComponentWithForeignChildren({
+      component: layout.component,
+      props: layout.props ?? {},
+      children,
+      integrationContext: { rendererCache: context.rendererCache }
+    });
+    layoutRenders.push(layoutRender);
+    children = layoutRender.html;
+  }
+  return {
+    children,
+    layoutRenders
+  };
+}
 async function composeDocumentShell(dependencies, input) {
   const rendererCache = /* @__PURE__ */ new Map();
-  const primaryRender = await dependencies.renderComponentWithForeignChildren({
-    component: input.primaryComponent,
-    props: input.primaryProps,
-    integrationContext: { rendererCache }
-  });
-  const layoutRender = input.layout ? await dependencies.renderComponentWithForeignChildren({
-    component: input.layout.component,
-    props: input.layout.props ?? {},
-    children: primaryRender.html,
-    integrationContext: { rendererCache }
-  }) : void 0;
+  const layouts = resolveDocumentShellLayouts(input);
+  const composeChildren = input.composeChildren ?? composeSequentialLayoutChildren;
+  const usesCustomComposeChildren = input.composeChildren !== void 0;
+  let primaryRender;
+  let children;
+  let layoutRenders;
+  if (usesCustomComposeChildren) {
+    const composed = await composeChildren({
+      primaryComponent: input.primaryComponent,
+      primaryProps: input.primaryProps,
+      layouts,
+      rendererCache,
+      renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren
+    });
+    children = composed.children;
+    layoutRenders = composed.layoutRenders;
+    primaryRender = composed.primaryRender ?? {
+      html: typeof composed.children === "string" ? composed.children : "",
+      assets: [],
+      canAttachAttributes: true,
+      rootTag: "main",
+      integrationName: resolveComponentIntegrationName(input.primaryComponent)
+    };
+  } else {
+    primaryRender = await dependencies.renderComponentWithForeignChildren({
+      component: input.primaryComponent,
+      props: input.primaryProps,
+      integrationContext: { rendererCache }
+    });
+    const composed = await composeChildren({
+      primaryComponent: input.primaryComponent,
+      primaryProps: input.primaryProps,
+      primaryRender,
+      layouts,
+      rendererCache,
+      renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren
+    });
+    children = composed.children;
+    layoutRenders = composed.layoutRenders;
+  }
   const documentRender = await dependencies.renderComponentWithForeignChildren({
     component: input.htmlTemplate,
     props: input.documentProps,
-    children: layoutRender?.html ?? primaryRender.html,
+    children,
     integrationContext: { rendererCache }
   });
-  dependencies.appendProcessedDependencies(primaryRender.assets, layoutRender?.assets, documentRender.assets);
+  dependencies.appendProcessedDependencies(
+    primaryRender.assets,
+    ...layoutRenders.map((layoutRender) => layoutRender.assets),
+    documentRender.assets
+  );
   return {
     documentHtml: documentRender.html
   };
@@ -37,6 +100,8 @@ async function renderPageDocumentShell(dependencies, input, docType) {
     primaryComponent: input.page.component,
     primaryProps: input.page.props,
     layout: input.layout,
+    layouts: input.layouts,
+    composeChildren: input.composeChildren,
     htmlTemplate: input.htmlTemplate,
     documentProps: {
       metadata: input.metadata,
@@ -50,5 +115,6 @@ async function renderPageDocumentShell(dependencies, input, docType) {
 export {
   applyDocumentShellAttributeStamping,
   composeDocumentShell,
+  composeSequentialLayoutChildren,
   renderPageDocumentShell
 };

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

@@ -23,6 +23,7 @@ import {
   composeDocumentShell,
   renderPageDocumentShell
 } from "./document-shell-render.service.js";
+import { resolveInnermostPageLayout, resolvePageLayoutComponents } from "./layout-shell-props.service.js";
 class IntegrationRenderer {
   appConfig;
   assetProcessingService;
@@ -594,7 +595,8 @@ class IntegrationRenderer {
     });
     const { Page, integrationSpecificProps } = pageModule;
     const HtmlTemplate = await this.getHtmlTemplate();
-    const Layout = Page.config?.layout;
+    const Layouts = resolvePageLayoutComponents(Page.config?.layouts);
+    const Layout = resolveInnermostPageLayout(Layouts);
     const { props, metadata } = await this.pageModuleLoaderService.resolvePageData({
       pageModule,
       routeOptions
@@ -602,7 +604,9 @@ class IntegrationRenderer {
     return {
       Page,
       HtmlTemplate,
+      Layouts,
       Layout,
+      layoutEntries: Page.config?.layoutEntries,
       props,
       metadata,
       integrationSpecificProps

package/src/route-renderer/orchestration/layout-shell-props.service.d.ts

@@ -0,0 +1,20 @@
+import type { EcoPageLayoutEntry, LayoutPropsContext } from '../../types/public-types.js';
+export type LayoutShellPropsContext = LayoutPropsContext & {
+    pageProps?: Record<string, unknown>;
+};
+/**
+ * Resolves the default shell props passed to a layout tier during route render.
+ */
+export declare function resolveLayoutShellProps(context: LayoutShellPropsContext): Record<string, unknown>;
+/**
+ * Resolves props for one layout entry, merging shell props with an optional factory.
+ */
+export declare function resolveLayoutEntryProps(entry: EcoPageLayoutEntry, context: LayoutShellPropsContext): Record<string, unknown>;
+/**
+ * Reads the normalized layout stack from a page component config.
+ */
+export declare function resolvePageLayoutComponents(layouts?: EcoPageLayoutEntry['component'][]): EcoPageLayoutEntry['component'][];
+/**
+ * Returns the innermost layout component from a normalized page layout stack.
+ */
+export declare function resolveInnermostPageLayout(layouts?: EcoPageLayoutEntry['component'][]): EcoPageLayoutEntry['component'] | undefined;

package/src/route-renderer/orchestration/layout-shell-props.service.js

@@ -0,0 +1,31 @@
+function resolveLayoutShellProps(context) {
+  return context.locals ? { locals: context.locals } : {};
+}
+function resolveLayoutEntryProps(entry, context) {
+  const shellProps = resolveLayoutShellProps(context);
+  if (!entry.props) {
+    return shellProps;
+  }
+  const layoutPropsContext = {
+    params: context.params,
+    query: context.query,
+    locals: context.locals
+  };
+  return {
+    ...shellProps,
+    ...entry.props(layoutPropsContext)
+  };
+}
+function resolvePageLayoutComponents(layouts) {
+  return layouts && layouts.length > 0 ? layouts : [];
+}
+function resolveInnermostPageLayout(layouts) {
+  const stack = resolvePageLayoutComponents(layouts);
+  return stack[stack.length - 1];
+}
+export {
+  resolveInnermostPageLayout,
+  resolveLayoutEntryProps,
+  resolveLayoutShellProps,
+  resolvePageLayoutComponents
+};