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

package/src/config/config-builder.ts

@@ -4,17 +4,49 @@
  */
 
 import path from 'node:path';
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../constants.ts';
+import {
+	DEFAULT_ECOPAGES_DIST_DIR,
+	DEFAULT_ECOPAGES_HOSTNAME,
+	DEFAULT_ECOPAGES_PORT,
+	DEFAULT_ECOPAGES_WORK_DIR,
+} from '../constants.ts';
+import {
+	collectConfiguredAppBuildManifestContributions,
+	createBuildAdapter,
+	getAppServerBuildPlugins,
+	setAppBuildAdapter,
+	setAppBuildExecutor,
+	updateAppBuildManifest,
+} from '../build/build-adapter.ts';
 import type { EcoBuildPlugin } from '../build/build-types.ts';
+import { createAppBuildExecutor } from '../build/dev-build-coordinator.ts';
 import { GHTML_PLUGIN_NAME, ghtmlPlugin } from '../integrations/ghtml/ghtml.plugin.ts';
-import type { EcoPagesAppConfig, IncludesTemplates, RobotsPreference } from '../internal-types.ts';
+import type { EcoPagesAppConfig, RobotsPreference } from '../internal-types.ts';
 import { createEcoComponentMetaPlugin } from '../plugins/eco-component-meta-plugin.ts';
 import type { IntegrationPlugin } from '../plugins/integration-plugin.ts';
 import type { Processor } from '../plugins/processor.ts';
+import type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from '../plugins/runtime-capability.ts';
 import type { PageMetadataProps } from '../public-types.ts';
 import type { CacheConfig } from '../services/cache/cache.types.ts';
+import {
+	NoopEntrypointDependencyGraph,
+	setAppEntrypointDependencyGraph,
+} from '../services/runtime-state/entrypoint-dependency-graph.service.ts';
+import {
+	createNodeRuntimeManifest,
+	setAppNodeRuntimeManifest,
+} from '../services/runtime-manifest/node-runtime-manifest.service.ts';
+import {
+	InMemoryRuntimeSpecifierRegistry,
+	setAppRuntimeSpecifierRegistry,
+} from '../services/runtime-state/runtime-specifier-registry.service.ts';
+import {
+	CounterServerInvalidationState,
+	setAppServerInvalidationState,
+} from '../services/runtime-state/server-invalidation-state.service.ts';
 import { invariant } from '../utils/invariant.ts';
 import { appLogger } from '../global/app-logger.ts';
+import { fileSystem } from '@ecopages/file-system';
 
 export const CONFIG_BUILDER_ERRORS = {
 	DUPLICATE_INTEGRATION_NAMES: 'Integrations names must be unique',
@@ -23,8 +55,39 @@ export const CONFIG_BUILDER_ERRORS = {
 		'Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).',
 	duplicateProcessorName: (name: string) => `Processor with name "${name}" already exists`,
 	duplicateLoaderName: (name: string) => `Loader with name "${name}" already exists`,
+	duplicateSemanticTemplate: (kind: 'html' | '404', matches: string[]) =>
+		`Multiple ${kind} templates found: ${matches.join(', ')}`,
+	incompatibleRuntimeCapability: (
+		kind: 'integration' | 'processor',
+		name: string,
+		runtime: RuntimeKind,
+		reason: string,
+	) => `Cannot enable ${kind} "${name}" on ${runtime}: ${reason}`,
+	unsupportedRuntimeVersion: (
+		kind: 'integration' | 'processor',
+		name: string,
+		runtime: RuntimeKind,
+		current: string,
+		min: string,
+	) => `Cannot enable ${kind} "${name}" on ${runtime} ${current}: requires runtime version ${min} or newer`,
+	invalidRuntimeVersion: (kind: 'integration' | 'processor', name: string, version: string) =>
+		`Cannot validate ${kind} "${name}" runtimeCapability.minRuntimeVersion "${version}" because it is not a dot-separated numeric version`,
 } as const;
 
+type RuntimeKind = 'node' | 'bun';
+
+type RuntimeEnvironment = {
+	runtime: RuntimeKind;
+	version: string;
+	supportedTags: Set<RuntimeCapabilityTag>;
+};
+
+type RuntimeCapabilityOwner = {
+	kind: 'integration' | 'processor';
+	name: string;
+	runtimeCapability?: RuntimeCapabilityDeclaration;
+};
+
 /**
  * A builder class for creating and configuring EcoPages application configuration.
  * Provides a fluent interface for setting various configuration options and managing
@@ -65,12 +128,6 @@ export class ConfigBuilder {
 		componentsDir: 'components',
 		layoutsDir: 'layouts',
 		publicDir: 'public',
-		includesTemplates: {
-			head: 'head.ghtml.ts',
-			html: 'html.ghtml.ts',
-			seo: 'seo.ghtml.ts',
-		},
-		error404Template: '404.ghtml.ts',
 		robotsTxt: {
 			preferences: {
 				'*': [],
@@ -78,7 +135,7 @@ export class ConfigBuilder {
 		},
 		integrations: [],
 		integrationsDependencies: [],
-		distDir: '.eco',
+		distDir: DEFAULT_ECOPAGES_DIST_DIR,
 		defaultMetadata: {
 			title: 'Ecopages',
 			description: 'This is a static site generated with Ecopages',
@@ -89,6 +146,7 @@ export class ConfigBuilder {
 			config: '',
 			componentsDir: '',
 			distDir: '',
+			workDir: '',
 			includesDir: '',
 			layoutsDir: '',
 			pagesDir: '',
@@ -100,6 +158,7 @@ export class ConfigBuilder {
 		},
 		processors: new Map(),
 		loaders: new Map(),
+		workDir: DEFAULT_ECOPAGES_WORK_DIR,
 	};
 
 	/**
@@ -198,29 +257,6 @@ export class ConfigBuilder {
 		return this;
 	}
 
-	/**
-	 * Sets the templates used for includes.
-	 * These templates are used to build the HTML structure of pages.
-	 *
-	 * @param includesTemplates - An object containing the template file names
-	 * @returns The ConfigBuilder instance for method chaining
-	 */
-	setIncludesTemplates(includesTemplates: IncludesTemplates): this {
-		this.config.includesTemplates = includesTemplates;
-		return this;
-	}
-
-	/**
-	 * Sets the template file for the 404 error page.
-	 *
-	 * @param error404Template - The file name of the 404 error template (default: '404.ghtml.ts')
-	 * @returns The ConfigBuilder instance for method chaining
-	 */
-	setError404Template(error404Template: string): this {
-		this.config.error404Template = error404Template;
-		return this;
-	}
-
 	/**
 	 * Sets the robots.txt configuration.
 	 * This determines which paths are allowed/disallowed for search engines.
@@ -248,7 +284,7 @@ export class ConfigBuilder {
 	/**
 	 * Sets the output directory for the built application.
 	 *
-	 * @param distDir - The distribution directory name (default: '.eco')
+	 * @param distDir - The distribution directory name (default: 'dist')
 	 * @returns The ConfigBuilder instance for method chaining
 	 */
 	setDistDir(distDir: string): this {
@@ -256,6 +292,22 @@ export class ConfigBuilder {
 		return this;
 	}
 
+	/**
+	 * Sets the internal work directory for runtime-only artifacts.
+	 *
+	 * @remarks
+	 * Use this when deployable output should stay clean while Ecopages still
+	 * needs a separate workspace for server transpilation caches, runtime
+	 * manifests, and other internal build products.
+	 *
+	 * @param workDir - The internal work directory name
+	 * @returns The ConfigBuilder instance for method chaining
+	 */
+	setWorkDir(workDir: string): this {
+		this.config.workDir = workDir;
+		return this;
+	}
+
 	/**
 	 * Sets the default metadata for pages.
 	 * This is used when a page doesn't specify its own metadata.
@@ -360,40 +412,56 @@ export class ConfigBuilder {
 	}
 
 	private createAbsolutePaths(config: EcoPagesAppConfig): this {
-		const {
-			srcDir,
-			componentsDir,
-			includesDir,
-			layoutsDir,
-			pagesDir,
-			publicDir,
-			distDir,
-			includesTemplates,
-			error404Template,
-		} = config;
+		const { srcDir, componentsDir, includesDir, layoutsDir, pagesDir, publicDir, distDir, workDir } = config;
 
 		const projectDir = config.rootDir;
 
 		const absoluteSrcDir = path.resolve(projectDir, srcDir);
 		const absoluteDistDir = path.resolve(projectDir, distDir);
+		const absoluteWorkDir = path.resolve(projectDir, workDir);
+
+		const absoluteIncludesDir = path.join(absoluteSrcDir, includesDir);
+		const absolutePagesDir = path.join(absoluteSrcDir, pagesDir);
 
 		this.config.absolutePaths = {
 			config: path.join(projectDir, 'eco.config.ts'),
 			projectDir: projectDir,
 			srcDir: absoluteSrcDir,
 			distDir: absoluteDistDir,
+			workDir: absoluteWorkDir,
 			componentsDir: path.join(absoluteSrcDir, componentsDir),
-			includesDir: path.join(absoluteSrcDir, includesDir),
+			includesDir: absoluteIncludesDir,
 			layoutsDir: path.join(absoluteSrcDir, layoutsDir),
-			pagesDir: path.join(absoluteSrcDir, pagesDir),
+			pagesDir: absolutePagesDir,
 			publicDir: path.join(absoluteSrcDir, publicDir),
-			htmlTemplatePath: path.join(absoluteSrcDir, includesDir, includesTemplates.html),
-			error404TemplatePath: path.join(absoluteSrcDir, pagesDir, error404Template),
+			htmlTemplatePath: this.resolveSemanticTemplatePath({
+				dirPath: absoluteIncludesDir,
+				basename: 'html',
+			}),
+			error404TemplatePath: this.resolveSemanticTemplatePath({
+				dirPath: absolutePagesDir,
+				basename: '404',
+			}),
 		};
 
 		return this;
 	}
 
+	private resolveSemanticTemplatePath({ dirPath, basename }: { dirPath: string; basename: 'html' | '404' }): string {
+		const extensions = this.config.templatesExt.length > 0 ? this.config.templatesExt : ['.ghtml.ts'];
+		const matches = extensions
+			.map((extension) => path.join(dirPath, `${basename}${extension}`))
+			.filter((candidate) => fileSystem.exists(candidate));
+
+		invariant(matches.length <= 1, CONFIG_BUILDER_ERRORS.duplicateSemanticTemplate(basename, matches));
+
+		if (matches.length === 1) {
+			return matches[0]!;
+		}
+
+		return path.join(dirPath, `${basename}${extensions[0]}`);
+	}
+
 	private createIntegrationTemplatesExt(integrations: EcoPagesAppConfig['integrations']) {
 		const integrationName = integrations.map((integration) => integration.name);
 		const uniqueName = new Set(integrationName);
@@ -423,6 +491,154 @@ export class ConfigBuilder {
 		}
 	}
 
+	private validateRuntimeCapabilities(): void {
+		const runtimeEnvironment = this.detectRuntimeEnvironment();
+		const contributors: RuntimeCapabilityOwner[] = [
+			...this.config.integrations.map((integration) => ({
+				kind: 'integration' as const,
+				name: integration.name,
+				runtimeCapability: integration.runtimeCapability,
+			})),
+			...Array.from(this.config.processors.values(), (processor) => ({
+				kind: 'processor' as const,
+				name: processor.name,
+				runtimeCapability: processor.runtimeCapability,
+			})),
+		];
+
+		for (const contributor of contributors) {
+			this.validateRuntimeCapability(contributor, runtimeEnvironment);
+		}
+	}
+
+	private validateRuntimeCapability(contributor: RuntimeCapabilityOwner, environment: RuntimeEnvironment): void {
+		const declaration = contributor.runtimeCapability;
+		if (!declaration) {
+			return;
+		}
+
+		for (const tag of declaration.tags) {
+			if (environment.supportedTags.has(tag)) {
+				continue;
+			}
+
+			throw new Error(
+				CONFIG_BUILDER_ERRORS.incompatibleRuntimeCapability(
+					contributor.kind,
+					contributor.name,
+					environment.runtime,
+					this.describeUnsupportedRuntimeTag(tag),
+				),
+			);
+		}
+
+		if (!declaration.minRuntimeVersion) {
+			return;
+		}
+
+		const minVersion = this.parseVersion(declaration.minRuntimeVersion);
+		if (!minVersion) {
+			throw new Error(
+				CONFIG_BUILDER_ERRORS.invalidRuntimeVersion(
+					contributor.kind,
+					contributor.name,
+					declaration.minRuntimeVersion,
+				),
+			);
+		}
+
+		const currentVersion = this.parseVersion(environment.version);
+		if (!currentVersion) {
+			return;
+		}
+
+		if (this.compareVersions(currentVersion, minVersion) >= 0) {
+			return;
+		}
+
+		throw new Error(
+			CONFIG_BUILDER_ERRORS.unsupportedRuntimeVersion(
+				contributor.kind,
+				contributor.name,
+				environment.runtime,
+				environment.version,
+				declaration.minRuntimeVersion,
+			),
+		);
+	}
+
+	private detectRuntimeEnvironment(): RuntimeEnvironment {
+		const bunVersion = this.getBunVersion();
+		if (bunVersion) {
+			return {
+				runtime: 'bun',
+				version: bunVersion,
+				supportedTags: new Set<RuntimeCapabilityTag>([
+					'bun-only',
+					'node-compatible',
+					'requires-native-bun-api',
+					'requires-node-builtins',
+				]),
+			};
+		}
+
+		return {
+			runtime: 'node',
+			version: process.versions.node,
+			supportedTags: new Set<RuntimeCapabilityTag>(['node-compatible', 'requires-node-builtins']),
+		};
+	}
+
+	private getBunVersion(): string | undefined {
+		const bun = globalThis as typeof globalThis & {
+			Bun?: {
+				version?: string;
+			};
+		};
+
+		return typeof bun.Bun?.version === 'string' ? bun.Bun.version : undefined;
+	}
+
+	private describeUnsupportedRuntimeTag(tag: RuntimeCapabilityTag): string {
+		switch (tag) {
+			case 'bun-only':
+				return 'it is Bun-only';
+			case 'requires-native-bun-api':
+				return 'it requires the native Bun API';
+			case 'requires-node-builtins':
+				return 'it requires Node builtins';
+			case 'node-compatible':
+				return 'it requires a Node-compatible runtime';
+		}
+	}
+
+	private parseVersion(version: string): number[] | undefined {
+		const normalized = version.trim().replace(/^v/i, '');
+		if (!/^\d+(?:\.\d+)*$/.test(normalized)) {
+			return undefined;
+		}
+
+		return normalized.split('.').map((segment) => Number(segment));
+	}
+
+	private compareVersions(left: number[], right: number[]): number {
+		const maxLength = Math.max(left.length, right.length);
+		for (let index = 0; index < maxLength; index += 1) {
+			const leftValue = left[index] ?? 0;
+			const rightValue = right[index] ?? 0;
+
+			if (leftValue > rightValue) {
+				return 1;
+			}
+
+			if (leftValue < rightValue) {
+				return -1;
+			}
+		}
+
+		return 0;
+	}
+
 	/**
 	 * Initializes default loaders that are required for EcoPages to function.
 	 * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
@@ -463,11 +679,27 @@ export class ConfigBuilder {
 			this.config.integrations.push(ghtmlPlugin());
 		}
 
-		this.createAbsolutePaths(this.config);
 		this.createIntegrationTemplatesExt(this.config.integrations);
+		this.createAbsolutePaths(this.config);
 
 		await this.initializeDefaultLoaders();
 		this.initializeProcessors();
+		this.validateRuntimeCapabilities();
+		const buildAdapter = createBuildAdapter();
+		setAppBuildAdapter(this.config, buildAdapter);
+		updateAppBuildManifest(this.config, await collectConfiguredAppBuildManifestContributions(this.config));
+		setAppServerInvalidationState(this.config, new CounterServerInvalidationState());
+		setAppEntrypointDependencyGraph(this.config, new NoopEntrypointDependencyGraph());
+		setAppRuntimeSpecifierRegistry(this.config, new InMemoryRuntimeSpecifierRegistry());
+		setAppBuildExecutor(
+			this.config,
+			createAppBuildExecutor({
+				development: false,
+				adapter: buildAdapter,
+				getPlugins: () => getAppServerBuildPlugins(this.config),
+			}),
+		);
+		setAppNodeRuntimeManifest(this.config, createNodeRuntimeManifest(this.config));
 
 		return this.config;
 	}

package/src/constants.ts

@@ -37,3 +37,18 @@ export const GENERATED_BASE_PATHS = {
 export const DEFAULT_ECOPAGES_PORT = 3000;
 
 export const DEFAULT_ECOPAGES_HOSTNAME = 'localhost';
+
+/**
+ * Default directory used for deployable output.
+ */
+export const DEFAULT_ECOPAGES_DIST_DIR = 'dist';
+
+/**
+ * Default internal working directory used for runtime-only artifacts.
+ *
+ * @remarks
+ * This directory is a local tool workspace and is not intended for deployment.
+ * It owns transpiled server modules, runtime manifests, and processor caches
+ * so the export directory can remain a clean deployable tree.
+ */
+export const DEFAULT_ECOPAGES_WORK_DIR = '.eco';

package/src/declarations.d.ts

@@ -1,22 +1,27 @@
 import type { EcoPagesAppConfig } from './internal-types';
+import type { EcoNavigationRuntime } from './router/client/navigation-coordinator';
 
 type HMRHandler = (url: string) => Promise<void>;
-
-type ReloadPageFunction = (options: { clearCache: boolean }) => Promise<void>;
+type CleanupPageRootFunction = () => void;
+type EcoPageRoot = { render: (node: unknown) => void; unmount: () => void };
+type EcoPageData = {
+	module: string;
+	props: Record<string, unknown>;
+};
+type EcoPagesWindowRuntime = {
+	hmrHandlers?: Record<string, HMRHandler>;
+	navigation?: EcoNavigationRuntime;
+	react?: {
+		cleanupPageRoot?: CleanupPageRootFunction;
+		pageRoot?: EcoPageRoot | null;
+	};
+	page?: EcoPageData;
+};
 
 declare global {
-	var ecoConfig: EcoPagesAppConfig;
-
 	interface Window {
-		/** Registered HMR handlers for specific module paths */
-		__ecopages_hmr_handlers__?: Record<string, HMRHandler>;
-		/** Function to reload the current page, used for layout updates */
-		__ecopages_reload_current_page__?: ReloadPageFunction;
-		/** Page data registry - contains module path and props for current page */
-		__ECO_PAGE__?: {
-			module: string;
-			props: Record<string, unknown>;
-		};
+		/** Shared Ecopages browser runtime state */
+		__ECO_PAGES__?: EcoPagesWindowRuntime;
 	}
 }
 

package/src/eco/README.md

@@ -7,10 +7,12 @@ A unified API for defining components, pages, and page data in EcoPages.
 The `eco` namespace provides a consistent, type-safe interface for:
 
 1. **`eco.component()`** - Factory for defining reusable components with dependencies and optional lazy-loading
-2. **`eco.page()`** - Factory for defining page components with optional inline `staticPaths`, `staticProps`, and `metadata`
-3. **`eco.metadata()`** - Type-safe wrapper for page metadata (legacy pattern)
-4. **`eco.staticPaths()`** - Type-safe wrapper for dynamic route generation (legacy pattern)
-5. **`eco.staticProps()`** - Type-safe wrapper for static data fetching (legacy pattern)
+2. **`eco.html()`** - Semantic alias for the document shell component (the outermost HTML wrapper)
+3. **`eco.layout()`** - Semantic alias for route layout components (page-level wrappers)
+4. **`eco.page()`** - Factory for defining page components with optional inline `staticPaths`, `staticProps`, and `metadata`
+5. **`eco.metadata()`** - Type-safe wrapper for page metadata (legacy pattern)
+6. **`eco.staticPaths()`** - Type-safe wrapper for dynamic route generation (legacy pattern)
+7. **`eco.staticProps()`** - Type-safe wrapper for static data fetching (legacy pattern)
 
 ## Component Patterns
 
@@ -42,9 +44,9 @@ export function Card({ children, class: className }: CardProps) {
 
 > **Note:** If your component requires a dedicated CSS file, use `eco.component()` instead to manage the stylesheet dependency.
 
-### Plain React Components (With Bun)
+### Plain React Components
 
-When using Bun, React components with hooks and Tailwind CSS work out of the box without `eco.component()`. Bun auto-imports dependencies, so you can write standard React components:
+React components with hooks and Tailwind CSS work out of the box without `eco.component()`. Standard React components can be used directly:
 
 ```tsx
 import { useEffect, useState } from 'react';
@@ -99,7 +101,6 @@ export function ThemeToggle() {
 - React components with hooks (`useState`, `useEffect`, etc.)
 - Components styled with Tailwind CSS classes
 - Interactive UI that doesn't require external scripts or dedicated stylesheets
-- Bun handles all imports automatically
 
 > **Note:** Use `eco.component()` only when you need to manage external stylesheets, scripts, or lazy loading. For React components relying solely on hooks and Tailwind, plain functions are simpler and sufficient.
 
@@ -128,14 +129,14 @@ export const Counter = eco.component({
 
 ### Comparison
 
-| Aspect               | Simple JSX | Plain React (Bun) | `eco.component()` |
-| -------------------- | ---------- | ----------------- | ----------------- |
-| React hooks          | No         | Yes               | Yes               |
-| Scripts/Stylesheets  | No         | No                | Yes               |
-| Lazy loading         | No         | No                | Yes               |
-| Hydration strategies | No         | No                | Yes               |
-| Runtime cost         | Zero       | Minimal           | Minimal           |
-| Use case             | Static UI  | Interactive UI    | Advanced UI       |
+| Aspect               | Simple JSX | Plain React    | `eco.component()` |
+| -------------------- | ---------- | -------------- | ----------------- |
+| React hooks          | No         | Yes            | Yes               |
+| Scripts/Stylesheets  | No         | No             | Yes               |
+| Lazy loading         | No         | No             | Yes               |
+| Hydration strategies | No         | No             | Yes               |
+| Runtime cost         | Zero       | Minimal        | Minimal           |
+| Use case             | Static UI  | Interactive UI | Advanced UI       |
 
 All patterns can coexist in the same project. Use the right tool for the job.
 
@@ -231,6 +232,53 @@ Both patterns work and can be mixed - the renderer checks for attached propertie
 
 ## API Reference
 
+### `eco.html()`
+
+Creates the document shell component — the outermost HTML wrapper rendered once per page. Semantically equivalent to `eco.component()` but signals intent to tooling and readers that this component owns the full document structure (`<html>`, `<head>`, `<body>`).
+
+```tsx
+import { eco } from '@ecopages/core';
+
+export const Document = eco.html({
+	dependencies: {
+		stylesheets: ['./document.css'],
+	},
+	render: ({ children, metadata }) => (
+		<html lang="en">
+			<head>
+				<title>{metadata?.title ?? 'EcoPages'}</title>
+			</head>
+			<body>{children}</body>
+		</html>
+	),
+});
+```
+
+### `eco.layout()`
+
+Creates a route layout component — a wrapper rendered around page content. Semantically equivalent to `eco.component()` but clearly communicates that the component is intended to be used as a `layout` in `eco.page()`.
+
+```tsx
+import { eco } from '@ecopages/core';
+
+export const BaseLayout = eco.layout({
+	dependencies: {
+		stylesheets: ['./base-layout.css'],
+		scripts: ['./base-layout.script.ts'],
+	},
+	render: ({ children }) => <main>{children}</main>,
+});
+```
+
+Use `eco.layout()` components as the `layout` option in `eco.page()`:
+
+```tsx
+export default eco.page({
+	layout: BaseLayout,
+	render: () => <h1>Hello</h1>,
+});
+```
+
 ### `eco.component()`
 
 Define a reusable component with dependencies.
@@ -516,12 +564,18 @@ interface EcoComponentDependencies {
 	components?: EcoComponent[];
 }
 
+// Shared base option shape used by component(), html(), and layout()
 interface ComponentOptions<P, E = EcoPagesElement> {
 	componentDir?: string;
 	dependencies?: EcoComponentDependencies;
 	render: (props: P) => E;
 }
 
+// html() and layout() accept the same options as component() but return
+// narrower types to signal intent (EcoHtmlComponent / EcoLayoutComponent).
+type HtmlOptions<E = EcoPagesElement> = ComponentOptions<Record<string, unknown>, E>;
+type LayoutOptions<E = EcoPagesElement> = ComponentOptions<{ children: E }, E>;
+
 interface PageOptions<T, E = EcoPagesElement> {
 	componentDir?: string;
 	dependencies?: EcoComponentDependencies;
@@ -551,7 +605,7 @@ type PagePropsFor<T> =
 ```tsx
 import { eco } from '@ecopages/core';
 
-eco. // IDE shows: component, page, metadata, staticPaths, staticProps
+eco. // IDE shows: component, html, layout, page, metadata, staticPaths, staticProps
 ```
 
 ### 2. Type Safety