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

package/src/config/config-builder.js

@@ -1,17 +1,51 @@
 import path from "node:path";
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../constants.js";
-import { GHTML_PLUGIN_NAME, ghtmlPlugin } from "../integrations/ghtml/ghtml.plugin.js";
+import {
+  DEFAULT_ECOPAGES_DIST_DIR,
+  DEFAULT_ECOPAGES_HOSTNAME,
+  DEFAULT_ECOPAGES_PORT,
+  DEFAULT_ECOPAGES_WORK_DIR
+} from "../config/constants.js";
+import {
+  collectConfiguredAppBuildManifestContributions,
+  createBuildAdapter,
+  getAppServerBuildPlugins,
+  setAppBuildAdapter,
+  setAppBuildExecutor,
+  updateAppBuildManifest
+} from "../build/build-adapter.js";
+import { createAppBuildExecutor } from "../build/dev-build-coordinator.js";
+import { GHTML_PLUGIN_NAME } from "../integrations/ghtml/ghtml.constants.js";
+import { ghtmlPlugin } from "../integrations/ghtml/ghtml.plugin.js";
 import { createEcoComponentMetaPlugin } from "../plugins/eco-component-meta-plugin.js";
+import { createEcoComponentMetaTransform } from "../plugins/eco-component-meta-plugin.js";
+import {
+  NoopEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+} from "../services/runtime-state/entrypoint-dependency-graph.service.js";
+import {
+  InMemoryRuntimeSpecifierRegistry,
+  setAppRuntimeSpecifierRegistry
+} from "../services/runtime-state/runtime-specifier-registry.service.js";
+import {
+  CounterServerInvalidationState,
+  setAppServerInvalidationState
+} from "../services/runtime-state/server-invalidation-state.service.js";
 import { invariant } from "../utils/invariant.js";
 import { appLogger } from "../global/app-logger.js";
+import { fileSystem } from "@ecopages/file-system";
 const CONFIG_BUILDER_ERRORS = {
   DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique",
   DUPLICATE_INTEGRATION_EXTENSIONS: "Integrations extensions must be unique",
   MIXED_JSX_ENGINES: "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) => `Processor with name "${name}" already exists`,
-  duplicateLoaderName: (name) => `Loader with name "${name}" already exists`
+  duplicateLoaderName: (name) => `Loader with name "${name}" already exists`,
+  duplicateSemanticTemplate: (kind, matches) => `Multiple ${kind} templates found: ${matches.join(", ")}`,
+  incompatibleRuntimeCapability: (kind, name, runtime, reason) => `Cannot enable ${kind} "${name}" on ${runtime}: ${reason}`,
+  unsupportedRuntimeVersion: (kind, name, runtime, current, min) => `Cannot enable ${kind} "${name}" on ${runtime} ${current}: requires runtime version ${min} or newer`,
+  invalidRuntimeVersion: (kind, name, version) => `Cannot validate ${kind} "${name}" runtimeCapability.minRuntimeVersion "${version}" because it is not a dot-separated numeric version`
 };
 class ConfigBuilder {
+  buildOwnership = "bun-native";
   config = {
     baseUrl: "",
     rootDir: ".",
@@ -21,12 +55,6 @@ 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: {
         "*": []
@@ -34,7 +62,7 @@ class ConfigBuilder {
     },
     integrations: [],
     integrationsDependencies: [],
-    distDir: ".eco",
+    distDir: DEFAULT_ECOPAGES_DIST_DIR,
     defaultMetadata: {
       title: "Ecopages",
       description: "This is a static site generated with Ecopages"
@@ -45,6 +73,7 @@ class ConfigBuilder {
       config: "",
       componentsDir: "",
       distDir: "",
+      workDir: "",
       includesDir: "",
       layoutsDir: "",
       pagesDir: "",
@@ -55,7 +84,9 @@ class ConfigBuilder {
       error404TemplatePath: ""
     },
     processors: /* @__PURE__ */ new Map(),
-    loaders: /* @__PURE__ */ new Map()
+    loaders: /* @__PURE__ */ new Map(),
+    sourceTransforms: /* @__PURE__ */ new Map(),
+    workDir: DEFAULT_ECOPAGES_WORK_DIR
   };
   /**
    * Sets the base URL for the application.
@@ -79,6 +110,18 @@ class ConfigBuilder {
     this.config.rootDir = rootDir;
     return this;
   }
+  /**
+   * Sets which runtime path owns build execution for the finalized app config.
+   *
+   * @remarks
+   * Bun-native remains the default. Vite-host ownership should be selected only
+   * for host-driven compatibility flows where core must not silently fall back to
+   * Bun build execution.
+   */
+  setBuildOwnership(buildOwnership) {
+    this.buildOwnership = buildOwnership;
+    return this;
+  }
   /**
    * Sets the source directory relative to the root directory.
    * This directory contains all the source files for the application.
@@ -145,27 +188,6 @@ class ConfigBuilder {
     this.config.publicDir = publicDir;
     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) {
-    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) {
-    this.config.error404Template = error404Template;
-    return this;
-  }
   /**
    * Sets the robots.txt configuration.
    * This determines which paths are allowed/disallowed for search engines.
@@ -191,13 +213,28 @@ 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) {
     this.config.distDir = distDir;
     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) {
+    this.config.workDir = workDir;
+    return this;
+  }
   /**
    * Sets the default metadata for pages.
    * This is used when a page doesn't specify its own metadata.
@@ -264,6 +301,17 @@ class ConfigBuilder {
     }
     return this;
   }
+  /**
+   * Sets the source transforms to use for transform-first bundlers such as Vite.
+   * This replaces any existing source transforms.
+   */
+  setSourceTransforms(sourceTransforms) {
+    this.config.sourceTransforms.clear();
+    for (const sourceTransform of sourceTransforms) {
+      this.addSourceTransform(sourceTransform.name, sourceTransform);
+    }
+    return this;
+  }
   /**
    * Adds a loader to the application.
    *
@@ -279,6 +327,18 @@ class ConfigBuilder {
     this.config.loaders.set(name, loader);
     return this;
   }
+  /**
+   * Adds a source transform to the application.
+   *
+   * @throws Error if a source transform with the same name already exists.
+   */
+  addSourceTransform(name, sourceTransform) {
+    if (this.config.sourceTransforms.has(name)) {
+      throw new Error(CONFIG_BUILDER_ERRORS.duplicateLoaderName(name));
+    }
+    this.config.sourceTransforms.set(name, sourceTransform);
+    return this;
+  }
   /**
    * Sets the cache configuration for ISR and page caching.
    *
@@ -294,35 +354,44 @@ class ConfigBuilder {
     return this;
   }
   createAbsolutePaths(config) {
-    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,
       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;
   }
+  resolveSemanticTemplatePath({ dirPath, basename }) {
+    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]}`);
+  }
   createIntegrationTemplatesExt(integrations) {
     const integrationName = integrations.map((integration) => integration.name);
     const uniqueName = new Set(integrationName);
@@ -345,11 +414,138 @@ class ConfigBuilder {
       processor.setContext(this.config);
     }
   }
+  validateRuntimeCapabilities() {
+    const runtimeEnvironment = this.detectRuntimeEnvironment();
+    const contributors = [
+      ...this.config.integrations.map((integration) => ({
+        kind: "integration",
+        name: integration.name,
+        runtimeCapability: integration.runtimeCapability
+      })),
+      ...Array.from(this.config.processors.values(), (processor) => ({
+        kind: "processor",
+        name: processor.name,
+        runtimeCapability: processor.runtimeCapability
+      }))
+    ];
+    for (const contributor of contributors) {
+      this.validateRuntimeCapability(contributor, runtimeEnvironment);
+    }
+  }
+  validateRuntimeCapability(contributor, environment) {
+    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
+      )
+    );
+  }
+  detectRuntimeEnvironment() {
+    const bunVersion = this.getBunVersion();
+    if (bunVersion) {
+      return {
+        runtime: "bun",
+        version: bunVersion,
+        supportedTags: /* @__PURE__ */ new Set([
+          "bun-only",
+          "node-compatible",
+          "requires-native-bun-api",
+          "requires-node-builtins"
+        ])
+      };
+    }
+    return {
+      runtime: "node",
+      version: process.versions.node,
+      supportedTags: /* @__PURE__ */ new Set(["node-compatible", "requires-node-builtins"])
+    };
+  }
+  getBunVersion() {
+    const bun = globalThis;
+    return typeof bun.Bun?.version === "string" ? bun.Bun.version : void 0;
+  }
+  describeUnsupportedRuntimeTag(tag) {
+    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";
+    }
+  }
+  parseVersion(version) {
+    const normalized = version.trim().replace(/^v/i, "");
+    if (!/^\d+(?:\.\d+)*$/.test(normalized)) {
+      return void 0;
+    }
+    return normalized.split(".").map((segment) => Number(segment));
+  }
+  compareVersions(left, right) {
+    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.
    */
   async initializeDefaultLoaders() {
+    const componentMetaTransform = createEcoComponentMetaTransform({ config: this.config });
+    if (!this.config.sourceTransforms.has(componentMetaTransform.name)) {
+      this.config.sourceTransforms.set(componentMetaTransform.name, componentMetaTransform);
+    }
     const componentMetaPlugin = createEcoComponentMetaPlugin({ config: this.config });
     if (!this.config.loaders.has(componentMetaPlugin.name)) {
       this.config.loaders.set(componentMetaPlugin.name, componentMetaPlugin);
@@ -379,10 +575,25 @@ class ConfigBuilder {
     if (!this.config.integrations.some((integration) => integration.name === GHTML_PLUGIN_NAME)) {
       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({ ownership: this.buildOwnership });
+    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)
+      })
+    );
     return this.config;
   }
 }

package/src/{constants.d.ts → config/constants.d.ts}

@@ -30,3 +30,16 @@ export declare const GENERATED_BASE_PATHS: {
 };
 export declare const DEFAULT_ECOPAGES_PORT = 3000;
 export declare const DEFAULT_ECOPAGES_HOSTNAME = "localhost";
+/**
+ * Default directory used for deployable output.
+ */
+export declare 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 declare const DEFAULT_ECOPAGES_WORK_DIR = ".eco";

package/src/{constants.js → config/constants.js}

@@ -10,9 +10,13 @@ const GENERATED_BASE_PATHS = {
 };
 const DEFAULT_ECOPAGES_PORT = 3e3;
 const DEFAULT_ECOPAGES_HOSTNAME = "localhost";
+const DEFAULT_ECOPAGES_DIST_DIR = "dist";
+const DEFAULT_ECOPAGES_WORK_DIR = ".eco";
 export {
+  DEFAULT_ECOPAGES_DIST_DIR,
   DEFAULT_ECOPAGES_HOSTNAME,
   DEFAULT_ECOPAGES_PORT,
+  DEFAULT_ECOPAGES_WORK_DIR,
   GENERATED_BASE_PATHS,
   IS_BUN,
   RESOLVED_ASSETS_DIR,

package/src/declarations.d.ts

@@ -1,22 +1,27 @@
-import type { EcoPagesAppConfig } from './internal-types';
+import type { EcoPagesAppConfig } from './types/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/dev/sc-server.d.ts

@@ -1,5 +1,5 @@
 import type { Server } from 'bun';
-import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
 type StaticContentServerOptions = {
     port?: number;
 };

package/src/dev/sc-server.js

@@ -1,5 +1,5 @@
 import { extname, join } from "node:path";
-import { STATUS_MESSAGE } from "../constants.js";
+import { STATUS_MESSAGE } from "../config/constants.js";
 import { fileSystem } from "@ecopages/file-system";
 import { ServerUtils } from "../utils/server-utils.module.js";
 import { getRequiredBunRuntime } from "../utils/runtime.js";

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

package/src/eco/eco.browser.d.ts

@@ -0,0 +1,2 @@
+import type { Eco } from './eco.types.js';
+export declare const eco: Eco;