@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

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;

package/src/eco/eco.browser.js

@@ -0,0 +1,83 @@
+function createComponentFactory(options) {
+  const component2 = ((props) => options.render(props));
+  component2.config = {
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: options.dependencies
+  };
+  return component2;
+}
+function component(options) {
+  return createComponentFactory(options);
+}
+function html(options) {
+  return createComponentFactory(options);
+}
+function layout(options) {
+  return createComponentFactory(options);
+}
+function page(options) {
+  const {
+    layout: pageLayout,
+    dependencies,
+    render,
+    staticPaths: staticPaths2,
+    staticProps: staticProps2,
+    metadata: metadata2,
+    cache,
+    requires,
+    middleware
+  } = options;
+  const pageComponent = createComponentFactory({
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: pageLayout ? {
+      ...dependencies,
+      components: [...dependencies?.components ?? [], pageLayout]
+    } : dependencies,
+    render
+  });
+  if (pageLayout && pageComponent.config) {
+    pageComponent.config.layout = pageLayout;
+  }
+  if (staticPaths2) {
+    pageComponent.staticPaths = staticPaths2;
+  }
+  if (staticProps2) {
+    pageComponent.staticProps = staticProps2;
+  }
+  if (metadata2) {
+    pageComponent.metadata = metadata2;
+  }
+  if (cache) {
+    pageComponent.cache = cache;
+  }
+  if (requires) {
+    pageComponent.requires = requires;
+  }
+  if (middleware) {
+    pageComponent.middleware = middleware;
+  }
+  return pageComponent;
+}
+function metadata(fn) {
+  return fn;
+}
+function staticPaths(fn) {
+  return fn;
+}
+function staticProps(fn) {
+  return fn;
+}
+const eco = {
+  component,
+  html,
+  layout,
+  page,
+  metadata,
+  staticPaths,
+  staticProps
+};
+export {
+  eco
+};

package/src/eco/eco.js

@@ -1,60 +1,27 @@
-import { createNodeId, createPropsRef, createSlotRef, getComponentRenderContext } from "./component-render-context.js";
-import { createComponentMarker, parseComponentMarkers } from "../route-renderer/component-marker.js";
-import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./eco.utils.js";
+import {
+  finalizeComponentRender,
+  interceptForeignChild
+} from "../route-renderer/orchestration/component-render-context.js";
+import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
 function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;
   const comp = ((props) => {
-    const renderContext = getComponentRenderContext();
-    const shouldEmitMarker = renderContext !== void 0 && renderContext.boundaryContext.decideBoundaryRender({
-      currentIntegration: renderContext.currentIntegration,
-      targetIntegration: integrationName,
-      component: comp
-    }) === "defer";
-    if (shouldEmitMarker && renderContext) {
-      const nodeId = createNodeId(renderContext);
-      const propsRef = createPropsRef(renderContext);
-      const componentRef = comp.config?.__eco?.id ?? comp.config?.__eco?.file;
-      if (!componentRef) {
-        throw new Error(
-          "[ecopages] Missing component reference metadata for cross-integration marker emission."
-        );
-      }
-      const componentProps = props ?? {};
-      renderContext.propsByRef[propsRef] = componentProps;
-      let slotRef;
-      const children = componentProps.children;
-      if (typeof children === "string" && children.includes("<eco-marker")) {
-        const childMarkers = parseComponentMarkers(children);
-        if (childMarkers.length > 0) {
-          slotRef = createSlotRef(renderContext);
-          renderContext.slotChildrenByRef[slotRef] = childMarkers.map((marker) => marker.nodeId);
-        }
-      }
-      return createComponentMarker({
-        nodeId,
-        integration: integrationName,
-        componentRef,
-        propsRef,
-        slotRef
-      });
+    const componentProps = props ?? {};
+    const renderInline = () => finalizeComponentRender(comp, options.render(props));
+    const foreignChildRender = interceptForeignChild({
+      component: comp,
+      props: componentProps,
+      targetIntegration: integrationName
+    });
+    if (isThenable(foreignChildRender)) {
+      return foreignChildRender.then(
+        (resolvedForeignChildRender) => resolvedForeignChildRender !== void 0 ? resolvedForeignChildRender : renderInline()
+      );
     }
-    const content = options.render(props);
-    const lazyTriggers = comp.config?._resolvedLazyTriggers;
-    if (lazyTriggers && lazyTriggers.length > 0) {
-      const triggerId = lazyTriggers[0].triggerId;
-      if (isThenable(content)) {
-        return content.then((resolvedContent) => addTriggerAttribute(resolvedContent, triggerId));
-      }
-      return addTriggerAttribute(content, triggerId);
+    if (foreignChildRender !== void 0) {
+      return foreignChildRender;
     }
-    const lazyGroups = comp.config?._resolvedLazyScripts;
-    if (lazyGroups && lazyGroups.length > 0) {
-      if (isThenable(content)) {
-        return content.then((resolvedContent) => wrapWithScriptsInjector(resolvedContent, lazyGroups));
-      }
-      return wrapWithScriptsInjector(content, lazyGroups);
-    }
-    return content;
+    return renderInline();
   });
   comp.config = {
     __eco: options.__eco,
@@ -66,20 +33,26 @@ function createComponentFactory(options) {
 function component(options) {
   return createComponentFactory(options);
 }
+function html(options) {
+  return createComponentFactory(options);
+}
+function layout(options) {
+  return createComponentFactory(options);
+}
 function page(options) {
-  const { layout, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
+  const { layout: layout2, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
   const componentOptions = {
     __eco: options.__eco,
     integration: options.integration,
-    dependencies: layout ? {
+    dependencies: layout2 ? {
       ...dependencies,
-      components: [...dependencies?.components || [], layout]
+      components: [...dependencies?.components || [], layout2]
     } : dependencies,
     render
   };
   const pageComponent = createComponentFactory(componentOptions);
-  if (layout && pageComponent.config) {
-    pageComponent.config.layout = layout;
+  if (layout2 && pageComponent.config) {
+    pageComponent.config.layout = layout2;
   }
   if (staticPaths2) pageComponent.staticPaths = staticPaths2;
   if (staticProps2) pageComponent.staticProps = staticProps2;
@@ -100,6 +73,8 @@ function staticProps(fn) {
 }
 const eco = {
   component,
+  html,
+  layout,
   page,
   metadata,
   staticPaths,

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

@@ -2,7 +2,7 @@
  * Type definitions for the eco namespace API
  * @module
  */
-import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoInjectedMeta, EcoPagesElement, GetMetadata, GetStaticPaths, GetStaticProps, Middleware, RequestLocals, RequestPageContext } from '../public-types.js';
+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 { CacheStrategy } from '../services/cache/cache.types.js';
 type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K> & {
     [P in K]-?: Exclude<RequestLocals[P], null | undefined>;
@@ -26,6 +26,8 @@ export interface ComponentOptions<P, E = EcoPagesElement> {
     dependencies?: EcoComponentDependencies;
     render: (props: P) => E | Promise<E>;
 }
+export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
 /**
  * Base options shared by all page variants
  */
@@ -34,9 +36,7 @@ export interface PageOptionsBase<T, E = EcoPagesElement> {
     __eco?: EcoInjectedMeta;
     integration?: string;
     dependencies?: EcoComponentDependencies;
-    layout?: EcoComponent<{
-        children: E;
-    } & Partial<RequestPageContext>>;
+    layout?: EcoPageLayoutComponent<E>;
     /**
      * Define static paths for dynamic routes (e.g., [slug].tsx).
      * Returns all possible paths that should be pre-rendered at build time.
@@ -86,7 +86,7 @@ interface PageOptionsWithMiddleware<T, E = EcoPagesElement> extends PageOptionsB
      * Request-time middleware for file-based routes.
      * Runs before rendering and can short-circuit by returning a Response.
      */
-    middleware: Middleware[];
+    middleware: FileRouteMiddleware[];
 }
 /**
  * Options for creating a page with eco.page()
@@ -127,7 +127,7 @@ export type EcoPageComponent<T> = EcoComponent<PagePropsFor<T> & Partial<Request
     metadata?: GetMetadata<T>;
     cache?: CacheStrategy;
     requires?: PageRequires;
-    middleware?: Middleware[];
+    middleware?: FileRouteMiddleware[];
 };
 /**
  * The eco namespace interface
@@ -139,6 +139,14 @@ export interface Eco {
      * @template E - Element/return type (EcoPagesElement for Kita, ReactNode for React)
      */
     component: <P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>) => EcoComponent<P, E>;
+    /**
+     * Create a document shell component for the HTML wrapper.
+     */
+    html: <E = EcoPagesElement>(options: HtmlOptions<E>) => EcoHtmlComponent<E>;
+    /**
+     * Create a route layout component.
+     */
+    layout: <E = EcoPagesElement>(options: LayoutOptions<E>) => EcoLayoutComponent<E>;
     /**
      * Create a page component with type-safe props from getStaticProps.
      * Returns an EcoPageComponent with attached staticPaths, staticProps, and metadata.

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

@@ -1,40 +1 @@
-import type { EcoComponent } from '../public-types.js';
-/**
- * Returns `true` when `value` is a thenable (Promise-like) object.
- *
- * Used to transparently handle both synchronous and asynchronous component
- * render results without requiring every caller to branch on `instanceof Promise`.
- *
- * @typeParam T Expected resolved type of the thenable.
- */
-export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;
-/**
- * Injects `data-eco-trigger` into the first real HTML element opening tag of
- * a component's rendered output string.
- *
- * The scan skips over leading whitespace, HTML comments (`<!-- -->`), CDATA
- * sections, and doctype declarations so that the attribute is always placed on
- * the first actual element — not spurious markup that can precede it.
- *
- * The insertion point is the end of the element's tag name, before any existing
- * attributes or the closing `>`, which produces output like:
- *
- * ```html
- * <my-element data-eco-trigger="eco-trigger-abc123" class="foo">…</my-element>
- * ```
- *
- * When no eligible opening tag is found the original string is returned
- * unchanged so callers never receive a broken fragment.
- *
- * @param content Rendered HTML string (or any value coercible to string).
- * @param triggerId Stable trigger identifier produced by `buildResolvedLazyTriggers`.
- */
-export declare function addTriggerAttribute(content: unknown, triggerId: string): string;
-/**
- * Wraps rendered component output in a `<scripts-injector>` element that
- * carries an inline injector map for the legacy (non-global-injector) path.
- *
- * @param content Rendered component HTML.
- * @param lazyGroups Resolved lazy script groups attached to the component config.
- */
-export declare function wrapWithScriptsInjector(content: unknown, lazyGroups: NonNullable<EcoComponent['config']>['_resolvedLazyScripts']): string;
+export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/render-output.utils.js';

package/src/eco/eco.utils.js

@@ -1,38 +1,8 @@
-import { buildInjectorMapScript } from "./lazy-injector-map.js";
-function isThenable(value) {
-  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
-}
-function addTriggerAttribute(content, triggerId) {
-  const str = String(content);
-  let i = 0;
-  while (i < str.length) {
-    if (str[i] !== "<") {
-      i++;
-      continue;
-    }
-    const next = str[i + 1];
-    if (next === "!" || next === "?") {
-      const end = str.indexOf(">", i);
-      if (end === -1) break;
-      i = end + 1;
-      continue;
-    }
-    if (next && /[a-zA-Z]/.test(next)) {
-      const tagSlice = str.slice(i + 1);
-      const nameEnd = tagSlice.search(/[\s/>]/);
-      if (nameEnd === -1) break;
-      const insertAt = i + 1 + nameEnd;
-      return `${str.slice(0, insertAt)} data-eco-trigger="${triggerId}"${str.slice(insertAt)}`;
-    }
-    break;
-  }
-  return str;
-}
-function wrapWithScriptsInjector(content, lazyGroups) {
-  const wrappedContent = String(content);
-  const injectorMapScript = buildInjectorMapScript(lazyGroups ?? []);
-  return `<scripts-injector><script type="ecopages/injector-map">${injectorMapScript}<\/script>${wrappedContent}<\/scripts-injector>`;
-}
+import {
+  addTriggerAttribute,
+  isThenable,
+  wrapWithScriptsInjector
+} from "../route-renderer/orchestration/render-output.utils.js";
 export {
   addTriggerAttribute,
   isThenable,

package/src/eco/global-injector-map.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedLazyTrigger } from '../public-types.js';
+import type { ResolvedLazyTrigger } from '../types/public-types.js';
 /**
  * Serializes resolved lazy triggers into a JSON string safe for embedding
  * inside an inline `<script type="ecopages/global-injector-map">` tag.
@@ -10,7 +10,7 @@ import type { ResolvedLazyTrigger } from '../public-types.js';
  */
 export declare function buildGlobalInjectorMapScript(triggers: ResolvedLazyTrigger[]): string;
 /**
- * Builds the inline module script that boots the global lazy injector on the client.
+ * Builds the module source that boots the global lazy injector on the client.
  * Emitted once per page alongside the `ecopages/global-injector-map` script block.
  */
-export declare function buildGlobalInjectorBootstrapContent(globalInjectorModuleUrl: string): string;
+export declare function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier: string): string;

package/src/eco/global-injector-map.js

@@ -37,8 +37,8 @@ function buildGlobalInjectorMapScript(triggers) {
   const map = buildGlobalInjectorMap(triggers);
   return JSON.stringify(map).replace(/<\/script/gi, "<\\/script");
 }
-function buildGlobalInjectorBootstrapContent(globalInjectorModuleUrl) {
-  return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleUrl)};
+function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier) {
+  return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleSpecifier)};
 
 function pruneStaleTriggerMaps() {
 	const mapScripts = Array.from(document.querySelectorAll('script[type="ecopages/global-injector-map"]'));

package/src/eco/lazy-injector-map.d.ts

@@ -1,8 +1,8 @@
-import type { ResolvedLazyScriptGroup } from '../public-types.js';
+import type { ResolvedLazyScriptGroup } from '../types/public-types.js';
 /**
  * Creates a safe JSON payload string for `<script type="ecopages/injector-map">`.
  *
  * @param lazyGroups Lazy script groups resolved during dependency processing.
  * @returns Escaped JSON string safe for inline script embedding.
  */
-export declare function buildInjectorMapScript(lazyGroups: ResolvedLazyScriptGroup[]): string;
+export declare function buildInjectorMapScript(lazyGroups: readonly ResolvedLazyScriptGroup[]): string;

package/src/errors/index.d.ts

@@ -1,2 +1,3 @@
 export { HttpError } from './http-error.js';
 export type { HttpErrorDetails, HttpErrorJson } from './http-error.js';
+export { LocalsAccessError } from './locals-access-error.js';

package/src/errors/index.js

@@ -1,4 +1,6 @@
 import { HttpError } from "./http-error.js";
+import { LocalsAccessError } from "./locals-access-error.js";
 export {
-  HttpError
+  HttpError,
+  LocalsAccessError
 };

package/src/hmr/README.md

@@ -0,0 +1,26 @@
+# HMR Layer
+
+This directory contains the framework-owned hot-update strategy contracts used by runtime adapters and integrations.
+
+## Purpose
+
+The HMR layer separates change classification from update execution.
+
+It is responsible for:
+
+- defining the shared HMR manager and strategy contracts
+- letting integrations contribute framework-specific update strategies
+- keeping adapter transports independent from update policy
+
+## How It Fits
+
+1. `ProjectWatcher` observes file changes.
+2. `DevelopmentInvalidationService` classifies the change.
+3. The active HMR manager selects a strategy.
+4. The strategy coordinates browser rebuilds, metadata reloads, and client broadcasts.
+
+## Design Rule
+
+Generic invalidation policy belongs in core services.
+Framework-specific update behavior belongs in HMR strategies.
+Runtime-specific WebSocket or event-stream transport belongs in adapters.

package/src/hmr/client/hmr-runtime.d.ts

@@ -2,9 +2,4 @@
  * Ecopages HMR Runtime
  * Injected into the browser to handle Hot Module Replacement updates.
  */
-interface HMRPayload {
-    type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
-    path?: string;
-    message?: string;
-    timestamp?: number;
-}
+export {};

package/src/hmr/client/hmr-runtime.js

@@ -1,3 +1,4 @@
+import { getEcoNavigationRuntime } from "../../router/client/navigation-coordinator.js";
 (function() {
   const WS_URL = "ws://" + location.host + "/_hmr";
   let socket;
@@ -24,14 +25,15 @@
     });
   }
   async function handleMessage(payload) {
+    const navigationRuntime = getEcoNavigationRuntime(window);
     switch (payload.type) {
       case "reload":
+        await waitForNavigationToSettle(navigationRuntime);
         location.reload();
         break;
       case "layout-update": {
-        const reloadFn = window.__ecopages_reload_current_page__;
-        if (typeof reloadFn === "function") {
-          await reloadFn({ clearCache: true });
+        await waitForNavigationToSettle(navigationRuntime);
+        if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
         } else {
           location.reload();
         }
@@ -55,20 +57,49 @@
   async function applyUpdate(path, timestamp) {
     try {
       const url = path + "?t=" + (timestamp || Date.now());
-      const handlers = window.__ecopages_hmr_handlers__;
+      const handlers = window.__ECO_PAGES__?.hmrHandlers;
+      const navigationRuntime = getEcoNavigationRuntime(window);
+      await waitForNavigationToSettle(navigationRuntime);
       if (handlers?.[path]) {
         await handlers[path](url);
         return;
       }
       await import(url);
-      const reloadFn = window.__ecopages_reload_current_page__;
-      if (typeof reloadFn === "function") {
-        await reloadFn({ clearCache: false });
+      if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
       }
     } catch (e) {
       console.error("[ecopages] Failed to apply HMR update:", e);
     }
   }
+  function getActiveHmrModuleUrl() {
+    const pageModule = window.__ECO_PAGES__?.page?.module;
+    if (pageModule && pageModule.includes("/assets/_hmr/")) {
+      return pageModule.split("?")[0];
+    }
+    const handlerPaths = Object.keys(window.__ECO_PAGES__?.hmrHandlers ?? {});
+    return handlerPaths[handlerPaths.length - 1];
+  }
+  async function waitForNavigationToSettle(navigationRuntime) {
+    if (!navigationRuntime.hasPendingNavigationTransaction()) {
+      return;
+    }
+    await new Promise((resolve) => {
+      const startedAt = performance.now();
+      const timeoutMs = 2e3;
+      const poll = () => {
+        if (!navigationRuntime.hasPendingNavigationTransaction()) {
+          resolve();
+          return;
+        }
+        if (performance.now() - startedAt >= timeoutMs) {
+          resolve();
+          return;
+        }
+        requestAnimationFrame(poll);
+      };
+      requestAnimationFrame(poll);
+    });
+  }
   function refreshStylesheet(path) {
     const filename = path.split("/").pop() || "";
     const links = document.querySelectorAll('link[rel="stylesheet"]');