@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.20

package/src/static-site-generator/static-site-generator.js

@@ -1,8 +1,14 @@
 import path from "node:path";
+import { availableParallelism } from "node:os";
 import { appLogger } from "../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
-import { PathUtils } from "../utils/path-utils.module.js";
 import { prepareExplicitStaticRender } from "../adapters/shared/explicit-static-render-preparation.js";
+import { createRouteModuleStaticRenderCacheContext } from "./static-build-invalidation.js";
+import {
+  getServerModuleBuildCacheOutdir,
+  getSharedRouteModuleBuildCache
+} from "../services/module-loading/route-module-build-cache-registry.js";
+import { ensurePagesUnifiedGraphBuilt, shouldBuildPagesUnifiedGraph } from "../build/pages-unified-graph-build.js";
 const STATIC_SITE_GENERATOR_ERRORS = {
   ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy",
   unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
@@ -10,50 +16,51 @@ const STATIC_SITE_GENERATOR_ERRORS = {
   noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`,
   dynamicRouteRequiresStaticPaths: (routePath) => `Dynamic route ${routePath} requires staticPaths to be defined on the view.`
 };
+function resolveStaticPageConcurrency() {
+  return Math.max(1, availableParallelism() - 1);
+}
+async function runWithConcurrency(items, concurrency, worker) {
+  if (items.length === 0) {
+    return;
+  }
+  const limit = Math.max(1, concurrency);
+  let nextIndex = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex++;
+      await worker(items[currentIndex]);
+    }
+  });
+  await Promise.all(runners);
+}
 class StaticSiteGenerator {
   appConfig;
+  routeModuleBuildCacheOverride;
+  staticRenderCacheContext;
+  forceFullStaticGeneration = false;
   /**
    * Creates the static-site generator for one app config.
    */
-  constructor({ appConfig }) {
+  constructor({
+    appConfig,
+    routeModuleBuildCache
+  }) {
     this.appConfig = appConfig;
+    this.routeModuleBuildCacheOverride = routeModuleBuildCache;
+    this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(appConfig);
+  }
+  getRouteModuleBuildCache() {
+    return this.routeModuleBuildCacheOverride ?? getSharedRouteModuleBuildCache(getServerModuleBuildCacheOutdir(this.appConfig), this.appConfig);
   }
   getExportDir() {
     return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
   }
-  /**
-   * Logs the standardized warning emitted when a dynamic-cache page is skipped.
-   */
-  warnDynamicPageSkipped(filePath) {
-    appLogger.warn(
-      "Pages with cache: 'dynamic' are not supported in static generation or preview, so they will be skipped\n",
-      `\u27A4 ${filePath}`
-    );
-  }
-  /**
-   * Determines whether one filesystem-discovered page should be excluded from
-   * static generation.
-   */
   async shouldSkipStaticPageFile(filePath, routeRendererFactory) {
-    const module = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath, {
-      cacheScope: "static-page-probe"
-    });
-    if (module.default?.cache !== "dynamic") {
-      return false;
-    }
-    this.warnDynamicPageSkipped(filePath);
-    return true;
+    const module = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath);
+    return module.default?.cache === "dynamic";
   }
-  /**
-   * Determines whether one explicit static route view should be excluded from
-   * static generation.
-   */
-  shouldSkipStaticView(routePath, view) {
-    if (view.cache !== "dynamic") {
-      return false;
-    }
-    this.warnDynamicPageSkipped(routePath);
-    return true;
+  shouldSkipStaticView(_routePath, view) {
+    return view.cache === "dynamic";
   }
   /**
    * Writes the robots.txt file declared by the app config.
@@ -100,29 +107,56 @@ class StaticSiteGenerator {
     fileSystem.write(outputPath, contents);
     return outputPath;
   }
-  getStaticBuildStrategy(filePath) {
-    const ext = PathUtils.getEcoTemplateExtension(filePath);
-    const integration = this.appConfig.integrations.find((plugin) => plugin.extensions.includes(ext));
-    return integration?.staticBuildStep || "render";
+  async writeStaticPageArtifact(options) {
+    options.activeStaticPathnames?.add(options.pathname);
+    const directories = options.directories ?? this.getDirectories([options.pathname]);
+    const renderedOutputPath = this.getOutputPath(options.pathname, directories);
+    const routeModuleBuildCache = this.getRouteModuleBuildCache();
+    if (options.reuseRenderedOutput !== false && options.sourceFile && routeModuleBuildCache.canReuseStaticRender({
+      sourceFile: options.sourceFile,
+      pathname: options.pathname,
+      renderedOutputPath,
+      context: this.staticRenderCacheContext,
+      force: this.forceFullStaticGeneration
+    })) {
+      appLogger.debug(`Skipped unchanged static page: ${options.debugLabel ?? options.pathname}`);
+      return;
+    }
+    const contents = await options.createContents();
+    if (contents === null) {
+      return;
+    }
+    const outputPath = this.writeStaticOutput(options.pathname, contents, directories);
+    if (options.sourceFile) {
+      routeModuleBuildCache.recordStaticRender({
+        filePath: options.sourceFile,
+        pathname: options.pathname,
+        sourceHash: fileSystem.hash(options.sourceFile),
+        renderedOutputPath: outputPath,
+        context: this.staticRenderCacheContext
+      });
+    }
   }
-  async createFilesystemStaticContents(route, baseUrl, routeRendererFactory) {
+  pruneStaleStaticOutputs(activeStaticPathnames) {
+    const removedOutputPaths = this.getRouteModuleBuildCache().pruneStaleRenderedOutputs(activeStaticPathnames);
+    for (const outputPath of removedOutputPaths) {
+      const resolvedOutputPath = path.isAbsolute(outputPath) ? outputPath : path.resolve(outputPath);
+      if (fileSystem.exists(resolvedOutputPath)) {
+        fileSystem.remove(resolvedOutputPath);
+        appLogger.debug(`Removed stale static output: ${resolvedOutputPath}`);
+      }
+    }
+  }
+  async createFilesystemStaticContents(route, _baseUrl, routeRendererFactory, skipped) {
     const {
       templateRoute: { filePath },
       params
     } = route;
-    if (this.getStaticBuildStrategy(filePath) === "fetch") {
-      const fetchUrl = this.resolveStaticFetchUrl(route.requestUrl, baseUrl);
-      const response = await fetch(fetchUrl);
-      if (!response.ok) {
-        appLogger.error(`Failed to fetch ${fetchUrl}. Status: ${response.status}`);
-        return null;
-      }
-      return response.text();
-    }
     if (!routeRendererFactory) {
       throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
     }
     if (await this.shouldSkipStaticPageFile(filePath, routeRendererFactory)) {
+      skipped?.push(filePath);
       return null;
     }
     const renderer = routeRendererFactory.getPageRenderer(filePath);
@@ -143,42 +177,51 @@ class StaticSiteGenerator {
    * Generates static output for all filesystem-discovered routes.
    *
    * @remarks
-   * Routes whose integrations opt into fetch-based static builds are rendered by
-   * issuing a request against the running server origin. Render-strategy routes
-   * go through the normal route renderer directly.
+   * Routes are rendered through the normal route renderer directly.
    */
-  async generateStaticPages(router, baseUrl, routeRendererFactory) {
-    const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+  async generateStaticPages(router, baseUrl, routeRendererFactory, skipped, activeStaticPathnames, preloadedRoutes) {
+    const routes = preloadedRoutes ?? await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
     appLogger.debug(
       "Static Pages",
       routes.map((route) => route.requestUrl)
     );
     const directories = this.getDirectories(routes.map((route) => route.requestUrl));
-    for (const route of routes) {
+    await runWithConcurrency(routes, resolveStaticPageConcurrency(), async (route) => {
       try {
-        const contents = await this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory);
-        if (contents === null) {
-          continue;
-        }
-        this.writeStaticOutput(route.pathname, contents, directories);
+        await this.writeStaticPageArtifact({
+          pathname: route.pathname,
+          sourceFile: route.templateRoute.filePath,
+          directories,
+          debugLabel: route.requestUrl,
+          activeStaticPathnames,
+          createContents: () => this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory, skipped)
+        });
       } catch (error) {
         appLogger.error(
           `Error generating static page for ${route.requestUrl}:`,
           error instanceof Error ? error : String(error)
         );
       }
-    }
+    });
   }
-  resolveStaticFetchUrl(route, baseUrl) {
-    if (!route.startsWith("http://") && !route.startsWith("https://")) {
-      return `${baseUrl}${route}`;
+  createStaticExportContext(input) {
+    return {
+      appConfig: this.appConfig,
+      router: input.router,
+      baseUrl: input.baseUrl,
+      routeRendererFactory: input.routeRendererFactory,
+      staticRoutes: input.staticRoutes,
+      force: input.force,
+      preserveExportDirectory: input.preserveExportDirectory
+    };
+  }
+  async invokeStaticExportHook(hook, context) {
+    for (const integration of this.appConfig.integrations) {
+      const handler = integration[hook];
+      if (typeof handler === "function") {
+        await handler.call(integration, context);
+      }
     }
-    const targetUrl = new URL(route);
-    const buildUrl = new URL(baseUrl);
-    buildUrl.pathname = targetUrl.pathname;
-    buildUrl.search = targetUrl.search;
-    buildUrl.hash = targetUrl.hash;
-    return buildUrl.href;
   }
   /**
    * Executes the full static-generation workflow for one app run.
@@ -187,19 +230,71 @@ class StaticSiteGenerator {
     router,
     baseUrl,
     routeRendererFactory,
-    staticRoutes
+    staticRoutes,
+    force = false,
+    preserveExportDirectory = false
   }) {
-    this.generateRobotsTxt();
-    await this.generateStaticPages(router, baseUrl, routeRendererFactory);
-    if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
-      await this.generateExplicitStaticPages(staticRoutes, routeRendererFactory);
+    const skippedDynamicPages = [];
+    const activeStaticPathnames = /* @__PURE__ */ new Set();
+    this.forceFullStaticGeneration = force;
+    this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(this.appConfig);
+    if (!force) {
+      this.getRouteModuleBuildCache().ensureIncrementalStaticGenerationContext(this.staticRenderCacheContext);
+    }
+    const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+    if (shouldBuildPagesUnifiedGraph()) {
+      await ensurePagesUnifiedGraphBuilt({
+        appConfig: this.appConfig,
+        entryPaths: routes.map((route) => route.templateRoute.filePath),
+        outdir: getServerModuleBuildCacheOutdir(this.appConfig),
+        force
+      });
+    }
+    const staticExportContext = this.createStaticExportContext({
+      router,
+      baseUrl,
+      routeRendererFactory,
+      staticRoutes,
+      force,
+      preserveExportDirectory
+    });
+    await this.invokeStaticExportHook("beforeStaticExport", staticExportContext);
+    try {
+      this.generateRobotsTxt();
+      await this.generateStaticPages(
+        router,
+        baseUrl,
+        routeRendererFactory,
+        skippedDynamicPages,
+        activeStaticPathnames,
+        routes
+      );
+      if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
+        await this.generateExplicitStaticPages(
+          staticRoutes,
+          routeRendererFactory,
+          skippedDynamicPages,
+          activeStaticPathnames
+        );
+      }
+      if (preserveExportDirectory) {
+        this.pruneStaleStaticOutputs(activeStaticPathnames);
+      }
+    } finally {
+      await this.invokeStaticExportHook("afterStaticExport", staticExportContext);
+    }
+    if (skippedDynamicPages.length > 0) {
+      appLogger.debug(
+        `Skipped ${skippedDynamicPages.length} page(s) with cache: 'dynamic' (not supported in static generation)`,
+        skippedDynamicPages
+      );
     }
   }
   /**
    * Generates static pages from explicit static routes registered via app.static().
    * These routes use eco.page views via loader functions for HMR support.
    */
-  async generateExplicitStaticPages(staticRoutes, routeRendererFactory) {
+  async generateExplicitStaticPages(staticRoutes, routeRendererFactory, skipped, activeStaticPathnames) {
     appLogger.debug(
       "Generating explicit static routes",
       staticRoutes.map((r) => r.path)
@@ -209,9 +304,10 @@ class StaticSiteGenerator {
         const mod = await route.loader();
         const view = mod.default;
         if (this.shouldSkipStaticView(route.path, view)) {
+          skipped?.push(route.path);
           continue;
         }
-        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory);
+        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory, activeStaticPathnames);
       } catch (error) {
         appLogger.error(
           `Error generating explicit static page for ${route.path}:`,
@@ -220,18 +316,25 @@ class StaticSiteGenerator {
       }
     }
   }
-  async generateExplicitStaticRoute(routePath, view, routeRendererFactory) {
+  resolveExplicitViewSourceFile(view) {
+    const sourceFile = view.config?.__eco?.file;
+    if (!sourceFile) {
+      return void 0;
+    }
+    return path.isAbsolute(sourceFile) ? sourceFile : path.join(this.appConfig.rootDir, sourceFile);
+  }
+  async generateExplicitStaticRoute(routePath, view, routeRendererFactory, activeStaticPathnames) {
     const { renderer, routeEntries } = await this.planExplicitStaticRoute(routePath, view, routeRendererFactory);
+    const sourceFile = this.resolveExplicitViewSourceFile(view);
     for (const { pathname, params } of routeEntries) {
-      const contents = await this.createExplicitStaticContents(
-        routePath,
-        view,
-        params,
-        routeRendererFactory,
-        renderer
-      );
-      const outputPath = this.writeStaticOutput(pathname, contents);
-      appLogger.debug(`Generated static page: ${pathname} -> ${outputPath}`);
+      await this.writeStaticPageArtifact({
+        pathname,
+        sourceFile,
+        debugLabel: pathname,
+        activeStaticPathnames,
+        createContents: () => this.createExplicitStaticContents(routePath, view, params, routeRendererFactory, renderer)
+      });
+      appLogger.debug(`Generated static page: ${pathname}`);
     }
   }
   async planExplicitStaticRoute(routePath, view, routeRendererFactory) {

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

@@ -1,6 +1,7 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import type { AppBuildManifest } from '../build/build-manifest.js';
-import type { BuildAdapter, BuildExecutor, BuildOwnership } from '../build/build-adapter.js';
+import type { BuildAdapter, BuildOwnership } from '../build/build-adapter.js';
+import type { BuildRuntime } from '../build/build-runtime.js';
 import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';
 import type { EcoSourceTransform } from '../plugins/source-transform.js';
@@ -13,6 +14,9 @@ import type { SourceModuleLoader } from '../services/module-loading/module-loadi
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
 import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.js';
 import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
+import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
+/** Integration hook for registered `dependencies.scripts` entrypoint changes in dev. */
+export type RegisteredScriptEntrypointChangeHandler = (filePath: string) => void | Promise<void>;
 export interface RobotsPreference {
     /**
      * The user agent
@@ -149,13 +153,23 @@ export type EcoPagesAppConfig = {
         buildOwnership?: BuildOwnership;
         buildAdapter?: BuildAdapter;
         buildManifest?: AppBuildManifest;
-        buildExecutor?: BuildExecutor;
         devGraphService?: DevGraphService;
         entrypointDependencyGraph?: EntrypointDependencyGraph;
         hostModuleLoader?: SourceModuleLoader;
         rendererModuleContext?: unknown;
         serverInvalidationState?: ServerInvalidationState;
         serverModuleTranspiler?: ServerModuleTranspiler;
+        routeModuleBuildCaches?: Map<string, RouteModuleBuildCache>;
+        /** Profile-based build runtime installed by {@link installBuildRuntime}. */
+        buildRuntime?: BuildRuntime;
+        /** Set after {@link setupAppRuntimePlugins} runs processor/integration setup once per process. */
+        runtimeAssetsPrepared?: boolean;
+        /** When `'host'`, the embedded dev server owns browser dev-client bootstrap. */
+        devClientOwner?: 'core' | 'host';
+        /** Integration hooks run when a registered `dependencies.scripts` entrypoint changes. */
+        registeredScriptEntrypointChangeHandlers?: RegisteredScriptEntrypointChangeHandler[];
+        /** @deprecated Prefer {@link devClientOwner}: `'host'`. */
+        delegateBrowserReloadToHost?: boolean;
     };
     /**
      * Experimental features.
@@ -222,11 +236,4 @@ export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown
         server: unknown;
     }>;
 }
-export interface ProcessorPlugin {
-    name: string;
-    description?: string;
-    setup(): Promise<void>;
-    process<T = unknown>(input: T): Promise<T>;
-    teardown?(): Promise<void>;
-}
 export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.js';

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

@@ -14,6 +14,82 @@ import type { EntrypointDependencyGraph } from '../services/runtime-state/entryp
 export type { EcoPagesAppConfig } from './internal-types.js';
 export type { EcoPageComponent } from '../eco/eco.types.js';
 export type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+/**
+ * Runtime-agnostic incoming WebSocket frame.
+ *
+ * Both Bun and Node `ws` deliver text and binary frames; this discriminated
+ * union lets handlers deal with both without runtime-specific casts.
+ */
+export type IncomingWebSocketMessage = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'binary';
+    readonly data: Uint8Array;
+};
+/**
+ * Runtime-agnostic outgoing WebSocket payload.
+ *
+ * Strings are sent as text frames. Anything binary-shaped is sent as binary
+ * frames. `Blob` is included for cross-runtime parity and is normalized to a
+ * binary frame by each adapter.
+ */
+export type OutgoingWebSocketMessage = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+/**
+ * Close event delivered to `onClose` after a connection terminates.
+ */
+export interface WebSocketCloseInfo {
+    readonly code: number;
+    readonly reason: string;
+    readonly wasClean: boolean;
+}
+/**
+ * Input passed to a WebSocket handler's `context()` factory.
+ *
+ * Adapters call `context()` exactly once per accepted upgrade. The returned
+ * value becomes `socket.context` and is shared by all lifecycle hooks.
+ */
+export interface WebSocketContextFactoryInput<TParams extends Record<string, string> = Record<string, string>> {
+    readonly request: Request;
+    readonly kind: string;
+    readonly params: TParams;
+    readonly search: Readonly<Record<string, string>>;
+    readonly locals?: RequestLocals;
+}
+/**
+ * Runtime-agnostic WebSocket socket view exposed to handlers.
+ *
+ * Framework-owned fields:
+ * - `kind`: the registered route pattern (e.g. '/ws/chat/:roomId')
+ * - `params`: dynamic segments captured at match time
+ * - `search`: query string, always string-typed
+ *
+ * App-owned field:
+ * - `context`: returned by the handler's `context()` factory
+ */
+export interface EcopagesSocket<TContext = unknown, TParams extends Record<string, string> = Record<string, string>> {
+    readonly kind: string;
+    readonly params: TParams;
+    readonly search: Readonly<Record<string, string>>;
+    readonly context: TContext;
+    send(message: OutgoingWebSocketMessage): void;
+    sendStream(stream: ReadableStream<Uint8Array>): Promise<void>;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Connection-lifecycle handler object.
+ *
+ * All hooks are optional. `context()` is the one-time initializer that
+ * produces the per-connection state shared by the lifecycle hooks. Returning
+ * a rejected promise from `context()` aborts the upgrade.
+ */
+export interface EcopagesWebSocketHandler<TContext = unknown, TParams extends Record<string, string> = Record<string, string>> {
+    context?(input: WebSocketContextFactoryInput<TParams>): TContext | Promise<TContext>;
+    onConnect?(socket: EcopagesSocket<TContext, TParams>): void | Promise<void>;
+    onMessage?(socket: EcopagesSocket<TContext, TParams>, message: IncomingWebSocketMessage): void | Promise<void>;
+    onClose?(socket: EcopagesSocket<TContext, TParams>, event: WebSocketCloseInfo): void | Promise<void>;
+    onError?(socket: EcopagesSocket<TContext, TParams>, error: unknown): void | Promise<void>;
+}
 import type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput } from '../services/validation/standard-schema.types.js';
 export type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, ForeignChildRuntime, };
 export type InteractionEventsString = ScriptsInjectorInteractionEventsString;
@@ -201,6 +277,10 @@ export interface IHmrManager {
      * Enables or disables HMR.
      */
     setEnabled(enabled: boolean): void;
+    /**
+     * Stops active HMR watchers and releases dev-time resources.
+     */
+    stop(): void;
     /**
      * Returns whether HMR is enabled.
      */
@@ -213,6 +293,13 @@ export interface IHmrManager {
      * Gets the output URL for a registered entrypoint.
      */
     getOutputUrl(entrypointPath: string): string | undefined;
+    /**
+     * Returns an existing emitted HMR script artifact without registering it.
+     */
+    getResolvedScriptOutput?(entrypointPath: string): {
+        outputUrl: string;
+        outputPath: string;
+    } | undefined;
     /**
      * Gets the map of watched files.
      */
@@ -247,8 +334,21 @@ export type EcoComponentDependencies = {
      * to express explicit module imports for client bundles.
      */
     modules?: string[];
-    components?: EcoComponent[];
+    /**
+     * Child components whose assets and foreign-child graph are collected transitively.
+     * Each entry must be an `eco.component()`, `eco.layout()`, or `eco.html()` result
+     * with plugin-injected `config.__eco` metadata.
+     */
+    components?: EcoDeclaredComponent[];
 };
+/**
+ * Component returned from `eco.component()`, `eco.layout()`, or `eco.html()`.
+ *
+ * @remarks
+ * Used for `dependencies.components` and eco factory return types. Plugin-injected
+ * `config.__eco` is enforced at runtime via `isEcoDeclaredComponent()`, not by this alias.
+ */
+export type EcoDeclaredComponent<P = any, R = any> = EcoComponent<P, R>;
 export type EcoPagesElement = string | Promise<string>;
 /**
  * Serializable child payloads accepted by cross-integration deferred rendering.
@@ -314,11 +414,13 @@ export type EcoComponentConfig = {
      * );
      *
      * // Page using the layout
-     * const MyPage = () => <h1>Hello</h1>;
-     * MyPage.config = { layout: Layout };
+     * const MyPage = eco.page({ layout: Layout, render: () => <h1>Hello</h1> });
      * ```
      */
-    layout?: EcoPageLayoutComponent<any>;
+    /** Normalized outer→inner layout stack from `eco.page({ layout: [...] })`. */
+    layouts?: EcoDeclaredComponent[];
+    /** Layout entries retained for per-tier prop factories. */
+    layoutEntries?: EcoPageLayoutEntry[];
     dependencies?: EcoComponentDependencies;
     /**
      * Internal: Resolved lazy scripts grouped by trigger.
@@ -442,6 +544,36 @@ export interface HtmlTemplateProps<T = EcoPagesElement> extends PageHeadProps<T>
     headContent?: T;
     pageProps: Record<string, unknown>;
 }
+/**
+ * Request-scoped context available to layout prop factories on `eco.page`.
+ */
+export type LayoutPropsContext = {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    locals?: RequestLocals;
+};
+/**
+ * One layout tier in a page layout stack (outer→inner).
+ */
+export type EcoPageLayoutEntry<E = EcoPagesElement> = {
+    component: EcoDeclaredComponent<any, E>;
+    props?: (context: LayoutPropsContext) => Record<string, unknown>;
+};
+/**
+ * Layout declaration accepted by `eco.page()`.
+ *
+ * @remarks
+ * Array order is outer→inner, matching Next.js App Router segment nesting.
+ */
+export type EcoPageLayoutSpec<E = EcoPagesElement> = EcoDeclaredComponent<any, E> | EcoPageLayoutEntry<E>;
+/**
+ * One or more layout tiers for `eco.page({ layout })`.
+ *
+ * @remarks
+ * When an array, order is **outer → inner** (outermost layout wraps all inner tiers).
+ * Normalized at factory time to `config.layouts` and `config.layoutEntries`.
+ */
+export type EcoPageLayouts<E = EcoPagesElement> = EcoPageLayoutSpec<E> | EcoPageLayoutSpec<E>[];
 /**
  * Layout components accepted by pages.
  *
@@ -659,7 +791,9 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     metadata: PageMetadataProps;
     HtmlTemplate: EcoHtmlComponent<C>;
     Page: EcoComponent<PageProps, C>;
+    Layouts?: EcoDeclaredComponent[];
     Layout?: EcoPageLayoutComponent<any>;
+    layoutEntries?: EcoPageLayoutEntry[];
     dependencies?: EcoComponentDependencies;
     resolvedDependencies: ProcessedAsset[];
     pagePackage?: PagePackageResult;
@@ -667,7 +801,6 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     pageProps?: Record<string, unknown>;
     cacheStrategy?: CacheStrategy;
     pageLocals?: RequestLocals;
-    ownershipPlan?: OwnershipPlan;
 };
 /**
  * Structured page asset package produced after dependency resolution.
@@ -746,27 +879,6 @@ export interface OwnershipValidationError {
     integrationName?: string;
 }
 export type OwnershipPlanNodeSource = 'route' | 'page' | 'layout' | 'html-template' | 'dependency';
-export interface IntegrationOwnership {
-    integrationName: string;
-    componentId: string;
-    componentFile?: string;
-    isPageEntry: boolean;
-    isForeignToParent: boolean;
-}
-export interface OwnershipPlanNode {
-    id: string;
-    source: OwnershipPlanNodeSource;
-    ownership: IntegrationOwnership;
-    children: OwnershipPlanNode[];
-    declaredDependenciesValid: boolean;
-}
-export interface OwnershipPlan {
-    root: OwnershipPlanNode;
-    rendererNames: string[];
-    foreignEdgeCount: number;
-    hasValidationErrors: boolean;
-    validationErrors: OwnershipValidationError[];
-}
 export type ForeignSubtreeAttachmentPolicy = {
     kind: 'none';
 } | {

package/src/utils/parse-cli-args.d.ts

@@ -13,6 +13,8 @@ export type ReturnParseCliArgs = {
     build: boolean;
     start: boolean;
     dev: boolean;
+    force: boolean;
+    serveOnly: boolean;
     port?: number;
     hostname?: string;
     reactFastRefresh?: boolean;