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

package/src/client/scroll.js

@@ -0,0 +1,25 @@
+function manageWindowScroll(newUrl, previousUrl, options) {
+  const { scrollBehavior, smoothScroll } = options;
+  if (newUrl.hash) {
+    const target = document.getElementById(newUrl.hash.slice(1));
+    target?.scrollIntoView({ behavior: smoothScroll ? "smooth" : "instant" });
+    return;
+  }
+  const behavior = smoothScroll ? "smooth" : "instant";
+  switch (scrollBehavior) {
+    case "preserve":
+      break;
+    case "auto":
+      if (newUrl.pathname !== previousUrl.pathname) {
+        window.scrollTo({ top: 0, left: 0, behavior });
+      }
+      break;
+    case "top":
+    default:
+      window.scrollTo({ top: 0, left: 0, behavior });
+      break;
+  }
+}
+export {
+  manageWindowScroll
+};

package/src/client/scroll.test.browser.js

@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { manageWindowScroll } from "./scroll.js";
+const options = { scrollBehavior: "top", smoothScroll: false };
+describe("manageWindowScroll", () => {
+  afterEach(() => {
+    history.replaceState({}, "", "/");
+    document.body.replaceChildren();
+    vi.restoreAllMocks();
+  });
+  it("scrolls to top by default", () => {
+    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {
+    });
+    manageWindowScroll(new URL("/next", window.location.origin), new URL("/prev", window.location.origin), options);
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, left: 0, behavior: "instant" });
+  });
+  it("preserves scroll when scrollBehavior is preserve", () => {
+    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {
+    });
+    manageWindowScroll(new URL("/next", window.location.origin), new URL("/prev", window.location.origin), {
+      ...options,
+      scrollBehavior: "preserve"
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it("scrolls to hash target by element id", () => {
+    const section = document.createElement("section");
+    section.id = "section";
+    section.scrollIntoView = vi.fn();
+    document.body.append(section);
+    manageWindowScroll(
+      new URL("/page#section", window.location.origin),
+      new URL("/page", window.location.origin),
+      options
+    );
+    expect(section.scrollIntoView).toHaveBeenCalledWith({ behavior: "instant" });
+  });
+});

package/src/client/view-transitions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * View Transition API helpers for `data-view-transition` markup.
+ * @module
+ */
+/**
+ * Assigns `view-transition-name` from `data-view-transition` and injects morph styles.
+ *
+ * @remarks
+ * Elements without `data-view-transition-animate="fade"` get a geometric morph:
+ * the old snapshot is hidden so cross-fade ghosting does not appear.
+ */
+export declare function applyViewTransitionNames(): void;
+/**
+ * Clears inline transition names and dynamic morph styles after a transition ends.
+ */
+export declare function clearViewTransitionNames(): void;

package/src/client/view-transitions.js

@@ -0,0 +1,63 @@
+const VIEW_TRANSITION_ATTR = "data-view-transition";
+const VIEW_TRANSITION_ANIMATE_ATTR = "data-view-transition-animate";
+const VIEW_TRANSITION_DURATION_ATTR = "data-view-transition-duration";
+const DYNAMIC_STYLES_ID = "eco-vt-dynamic-styles";
+function applyViewTransitionNames() {
+  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+  const morphNames = [];
+  const customDurations = [];
+  elements.forEach((el) => {
+    const name = el.getAttribute(VIEW_TRANSITION_ATTR);
+    if (!name) {
+      return;
+    }
+    el.style.viewTransitionName = name;
+    const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
+    if (animate !== "fade") {
+      morphNames.push(name);
+    }
+    const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
+    if (duration) {
+      customDurations.push({ name, duration });
+    }
+  });
+  if (morphNames.length > 0 || customDurations.length > 0) {
+    injectDynamicStyles(morphNames, customDurations);
+  }
+}
+function clearViewTransitionNames() {
+  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+  elements.forEach((el) => {
+    el.style.viewTransitionName = "";
+  });
+  const styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+  if (styleEl) {
+    styleEl.textContent = "";
+  }
+}
+function injectDynamicStyles(morphNames, customDurations) {
+  let styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+  if (!styleEl) {
+    styleEl = document.createElement("style");
+    styleEl.id = DYNAMIC_STYLES_ID;
+    styleEl.setAttribute("data-eco-persist", "");
+    document.head.append(styleEl);
+  }
+  const morphCss = morphNames.map(
+    (name) => `
+		::view-transition-old(${name}) { display: none !important; }
+		::view-transition-new(${name}) { animation: none !important; opacity: 1 !important; }
+	`
+  ).join("\n");
+  const durationCss = customDurations.map(
+    ({ name, duration }) => `
+		::view-transition-group(${name}) { animation-duration: ${duration} !important; }
+	`
+  ).join("\n");
+  styleEl.textContent = `${morphCss}
+${durationCss}`;
+}
+export {
+  applyViewTransitionNames,
+  clearViewTransitionNames
+};

package/src/config/config-builder.d.ts

@@ -70,12 +70,7 @@ export declare class ConfigBuilder {
      *
      * - `'rolldown'` (default): Ecopages runs builds through
      *   {@link RolldownBuildAdapter}, creating a new `rolldown()` instance
-     *   per build. Best for one-shot production builds and benchmarks.
-     * - `'rolldown-dev'`: Ecopages runs builds through
-     *   {@link RolldownDevBuildAdapter}, which wraps Rolldown's experimental
-     *   `DevEngine` and reuses the cached module graph, resolver, and
-     *   transform cache across rebuilds. Best for HMR and watch mode where
-     *   the same entrypoints are rebuilt repeatedly.
+     *   per build.
      * - `'vite-host'`: a host runtime owns the build. Ecopages exposes a
      *   {@link ViteHostBuildAdapter} boundary marker that throws on direct
      *   use. Select this only for host-driven compatibility flows where
@@ -250,7 +245,17 @@ export declare class ConfigBuilder {
     private compareVersions;
     /**
      * 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.
+     *
+     * @remarks
+     * `eco-component-meta` is registered twice on purpose:
+     *
+     * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
+     *   runs these after first-wins `onLoad` plugins rewrite module source.
+     * - `loaders` keeps the same transform available to server-oriented builds
+     *   that still use competing `onLoad` handlers directly.
+     *
+     * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
+     * when the transform name is already present in `sourceTransforms`.
      */
     private initializeDefaultLoaders;
     private reviewBaseUrl;

package/src/config/config-builder.js

@@ -9,7 +9,6 @@ import {
   collectConfiguredAppBuildManifestContributions,
   createBuildAdapter,
   setAppBuildAdapter,
-  setAppBuildExecutor,
   updateAppBuildManifest
 } from "../build/build-adapter.js";
 import { GHTML_PLUGIN_NAME } from "../integrations/ghtml/ghtml.constants.js";
@@ -112,12 +111,7 @@ class ConfigBuilder {
    *
    * - `'rolldown'` (default): Ecopages runs builds through
    *   {@link RolldownBuildAdapter}, creating a new `rolldown()` instance
-   *   per build. Best for one-shot production builds and benchmarks.
-   * - `'rolldown-dev'`: Ecopages runs builds through
-   *   {@link RolldownDevBuildAdapter}, which wraps Rolldown's experimental
-   *   `DevEngine` and reuses the cached module graph, resolver, and
-   *   transform cache across rebuilds. Best for HMR and watch mode where
-   *   the same entrypoints are rebuilt repeatedly.
+   *   per build.
    * - `'vite-host'`: a host runtime owns the build. Ecopages exposes a
    *   {@link ViteHostBuildAdapter} boundary marker that throws on direct
    *   use. Select this only for host-driven compatibility flows where
@@ -547,7 +541,17 @@ class ConfigBuilder {
   }
   /**
    * 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.
+   *
+   * @remarks
+   * `eco-component-meta` is registered twice on purpose:
+   *
+   * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
+   *   runs these after first-wins `onLoad` plugins rewrite module source.
+   * - `loaders` keeps the same transform available to server-oriented builds
+   *   that still use competing `onLoad` handlers directly.
+   *
+   * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
+   * when the transform name is already present in `sourceTransforms`.
    */
   async initializeDefaultLoaders() {
     const componentMetaTransform = createEcoComponentMetaTransform({ config: this.config });
@@ -593,7 +597,6 @@ class ConfigBuilder {
     updateAppBuildManifest(this.config, await collectConfiguredAppBuildManifestContributions(this.config));
     setAppServerInvalidationState(this.config, new CounterServerInvalidationState());
     setAppEntrypointDependencyGraph(this.config, new NoopEntrypointDependencyGraph());
-    setAppBuildExecutor(this.config, buildAdapter);
     return this.config;
   }
 }

package/src/dev/client-bridge-registry.d.ts

@@ -0,0 +1,5 @@
+import type { EcoPagesAppConfig } from '../types/public-types.js';
+import type { IClientBridge } from '../types/public-types.js';
+export declare function setAppDevClientBridge(appConfig: EcoPagesAppConfig, bridge: IClientBridge): void;
+export declare function getAppDevClientBridge(appConfig: EcoPagesAppConfig): IClientBridge | undefined;
+export declare function clearAppDevClientBridge(appConfig: EcoPagesAppConfig): void;

package/src/dev/client-bridge-registry.js

@@ -0,0 +1,15 @@
+const appDevClientBridges = /* @__PURE__ */ new WeakMap();
+function setAppDevClientBridge(appConfig, bridge) {
+  appDevClientBridges.set(appConfig, bridge);
+}
+function getAppDevClientBridge(appConfig) {
+  return appDevClientBridges.get(appConfig);
+}
+function clearAppDevClientBridge(appConfig) {
+  appDevClientBridges.delete(appConfig);
+}
+export {
+  clearAppDevClientBridge,
+  getAppDevClientBridge,
+  setAppDevClientBridge
+};

package/src/dev/dev-client-ownership.d.ts

@@ -0,0 +1,7 @@
+import type { ApplicationRuntimeOptions } from '../adapters/abstract/application-adapter.js';
+/**
+ * Returns whether the host dev server owns all browser dev-client bootstrap.
+ *
+ * When true, core must not inject the HMR runtime or signal full-page reloads.
+ */
+export declare function hostOwnsDevClient(runtime?: ApplicationRuntimeOptions): boolean;

package/src/dev/dev-client-ownership.js

@@ -0,0 +1,6 @@
+function hostOwnsDevClient(runtime) {
+  return runtime?.devClientOwner === "host" || runtime?.delegateBrowserReloadToHost === true;
+}
+export {
+  hostOwnsDevClient
+};

package/src/dev/hmr-manager-registry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Per-app registry for the shared HMR manager used by host-owned dev clients.
+ */
+import type { EcoPagesAppConfig } from '../types/public-types.js';
+import type { IHmrManager } from '../types/public-types.js';
+export declare function setAppHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
+export declare function getAppHmrManager(appConfig: EcoPagesAppConfig): IHmrManager | undefined;
+export declare function clearAppHmrManager(appConfig: EcoPagesAppConfig): void;

package/src/dev/hmr-manager-registry.js

@@ -0,0 +1,15 @@
+const appHmrManagers = /* @__PURE__ */ new WeakMap();
+function setAppHmrManager(appConfig, hmrManager) {
+  appHmrManagers.set(appConfig, hmrManager);
+}
+function getAppHmrManager(appConfig) {
+  return appHmrManagers.get(appConfig);
+}
+function clearAppHmrManager(appConfig) {
+  appHmrManagers.delete(appConfig);
+}
+export {
+  clearAppHmrManager,
+  getAppHmrManager,
+  setAppHmrManager
+};

package/src/dev/host-runtime.d.ts

@@ -1,10 +1,13 @@
 import type { EcoPagesAppConfig } from '../types/public-types.js';
 import { type DevelopmentInvalidationPlan } from '../services/invalidation/development-invalidation.service.js';
+import type { ClientBridgeEvent } from '../types/public-types.js';
 export type HostRuntimeModuleLoader = (id: string) => Promise<unknown>;
 export interface DevelopmentHostRuntime {
     registerHostModuleLoader(loader: HostRuntimeModuleLoader): void;
     planFileChange(filePath: string): DevelopmentInvalidationPlan;
     invalidateServerModules(changedFiles?: string[]): void;
     resetRuntimeState(changedFiles?: string[]): void;
+    broadcastClientEvent(event: ClientBridgeEvent): void;
+    isServerRenderedTemplatePlan(plan: DevelopmentInvalidationPlan): boolean;
 }
 export declare function createDevelopmentHostRuntime(appConfig: EcoPagesAppConfig): DevelopmentHostRuntime;

package/src/dev/host-runtime.js

@@ -1,6 +1,7 @@
 import {
   DevelopmentInvalidationService
 } from "../services/invalidation/development-invalidation.service.js";
+import { getAppDevClientBridge } from "./client-bridge-registry.js";
 import { setHostModuleLoader } from "../services/module-loading/host-module-loader-registry.js";
 function createDevelopmentHostRuntime(appConfig) {
   const invalidationService = new DevelopmentInvalidationService(appConfig);
@@ -16,6 +17,12 @@ function createDevelopmentHostRuntime(appConfig) {
     },
     resetRuntimeState(changedFiles) {
       invalidationService.resetRuntimeState(changedFiles);
+    },
+    broadcastClientEvent(event) {
+      getAppDevClientBridge(appConfig)?.broadcast(event);
+    },
+    isServerRenderedTemplatePlan(plan) {
+      return plan.category === "include-source" || plan.category === "explicit-server-view";
     }
   };
 }

package/src/dev/runtime-server-started-message.d.ts

@@ -0,0 +1,2 @@
+export type EcopagesRuntimeLabel = 'Bun' | 'Node';
+export declare function formatRuntimeServerStartedMessage(runtime: EcopagesRuntimeLabel, origin: string): string;

package/src/dev/runtime-server-started-message.js

@@ -0,0 +1,6 @@
+function formatRuntimeServerStartedMessage(runtime, origin) {
+  return `${runtime} server running at ${origin.replace(/\/$/, "")}`;
+}
+export {
+  formatRuntimeServerStartedMessage
+};

package/src/eco/README.md

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

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

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

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

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

package/src/eco/eco.browser.js

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

package/src/eco/eco.js

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

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

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

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

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

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

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

package/src/errors/index.d.ts

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

package/src/errors/index.js

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

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

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

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

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

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

@@ -12,7 +12,7 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
     socket.addEventListener("message", async (event) => {
       try {
         const payload = JSON.parse(event.data);
-        handleMessage(payload);
+        await handleMessage(payload);
       } catch (e) {
         console.error("[ecopages] Invalid HMR message:", e);
       }
@@ -29,12 +29,15 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
     switch (payload.type) {
       case "reload":
         await waitForNavigationToSettle(navigationRuntime);
+        if (window.__ECOPAGES_HOST_OWNS_RELOAD__) {
+          break;
+        }
         location.reload();
         break;
       case "layout-update": {
         await waitForNavigationToSettle(navigationRuntime);
         if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
-        } else {
+        } else if (!window.__ECOPAGES_HOST_OWNS_RELOAD__) {
           location.reload();
         }
         break;