@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.10

package/src/eco/eco.js

@@ -1,5 +1,6 @@
 import { createNodeId, createPropsRef, createSlotRef, getComponentRenderContext } from "./component-render-context.js";
-import { createComponentMarker, parseComponentMarkers } from "../route-renderer/component-marker.js";
+import { createComponentMarker, parseComponentMarkers } from "../route-renderer/component-graph/component-marker.js";
+import { getComponentReference } from "../route-renderer/component-graph/component-reference.js";
 import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./eco.utils.js";
 function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;
@@ -13,12 +14,7 @@ function createComponentFactory(options) {
     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 componentRef = getComponentReference(comp);
       const componentProps = props ?? {};
       renderContext.propsByRef[propsRef] = componentProps;
       let slotRef;
@@ -66,20 +62,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 +102,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, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, Middleware, RequestLocals, RequestPageContext } from '../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.
@@ -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/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 })) {
         } else {
           location.reload();
         }
@@ -55,20 +57,41 @@
   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);
     }
   }
+  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"]');

package/src/hmr/hmr.postcss.test.e2e.d.ts

@@ -0,0 +1 @@
+export {};

package/src/hmr/hmr.postcss.test.e2e.js

@@ -0,0 +1,31 @@
+import { test, expect } from "@playwright/test";
+import { readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+const FIXTURE_DIR = resolve(process.cwd(), "packages/core/__fixtures__/app");
+const TEST_CSS_FILE = resolve(FIXTURE_DIR, "src/pages/postcss-hmr.css");
+test.describe("HMR E2E PostCSS", () => {
+  test("should hot-update processor-owned CSS without a full page reload", async ({ page }) => {
+    const originalCss = readFileSync(TEST_CSS_FILE, "utf-8");
+    const title = page.locator(".postcss-title").first();
+    try {
+      await page.goto("/postcss-hmr", { waitUntil: "networkidle" });
+      await expect(title).toBeVisible();
+      const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
+      expect(initialColor).toBeTruthy();
+      await page.evaluate(() => {
+        window.__postcssReloadProbe = "before-change";
+      });
+      const modifiedCss = originalCss.replace(".postcss-title {", ".postcss-title {\n	color: rgb(255, 0, 0);");
+      await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+      await expect.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 1e4 }).toBe("rgb(255, 0, 0)");
+      await expect(
+        page.evaluate(
+          () => window.__postcssReloadProbe ?? null
+        )
+      ).resolves.toBe("before-change");
+    } finally {
+      await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+    }
+  });
+});

package/src/hmr/hmr.test.e2e.js

@@ -4,47 +4,40 @@ import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 const FIXTURE_DIR = resolve(process.cwd(), "packages/core/__fixtures__/app");
 const TEST_CSS_FILE = resolve(FIXTURE_DIR, "src/pages/index.css");
-const BUILT_CSS_FILE = resolve(FIXTURE_DIR, ".eco/assets/pages/index.css");
-const TEST_URL = "http://localhost:3002";
 test.describe("HMR E2E", () => {
   test("should load page with .main-title element", async ({ page }) => {
-    await page.goto(TEST_URL, { waitUntil: "networkidle" });
+    await page.goto("/", { waitUntil: "networkidle" });
     const title = page.locator(".main-title").first();
     await expect(title).toBeVisible();
   });
   test("should connect to HMR WebSocket", async ({ page }) => {
-    await page.goto(TEST_URL);
-    const connected = await page.evaluate(async () => {
-      return new Promise((resolve2) => {
-        const ws = new WebSocket("ws://localhost:3002/_hmr");
-        ws.onopen = () => {
-          ws.close();
-          resolve2(true);
-        };
-        ws.onerror = () => resolve2(false);
-        setTimeout(() => resolve2(false), 5e3);
-      });
+    const socketPromise = page.waitForEvent("websocket", {
+      predicate: (socket2) => socket2.url().endsWith("/_hmr"),
+      timeout: 1e4
     });
-    expect(connected).toBe(true);
+    await page.goto("/", { waitUntil: "networkidle" });
+    const socket = await socketPromise;
+    expect(socket.url()).toMatch(/\/_hmr$/);
   });
-  test("should reload page when CSS file changes", async ({ page }) => {
+  test("should fall back to a full page reload when raw CSS file changes", async ({ page }) => {
     const originalCss = readFileSync(TEST_CSS_FILE, "utf-8");
-    await page.goto(TEST_URL, { waitUntil: "networkidle" });
-    const initialColor = await page.evaluate(() => {
-      const el = document.querySelector(".main-title");
-      return el ? getComputedStyle(el).color : null;
-    });
-    expect(initialColor).toBeTruthy();
-    const modifiedCss = originalCss.replace(".main-title {", ".main-title {\n	color: rgb(255, 0, 0);");
-    const loadPromise = page.waitForEvent("load", { timeout: 1e4 });
-    await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
-    await writeFile(BUILT_CSS_FILE, modifiedCss, { flush: true });
-    await loadPromise;
-    const updatedColor = await page.evaluate(() => {
-      const el = document.querySelector(".main-title");
-      return el ? getComputedStyle(el).color : null;
-    });
-    expect(updatedColor).toBe("rgb(255, 0, 0)");
-    await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+    const title = page.locator(".main-title").first();
+    try {
+      await page.goto("/", { waitUntil: "networkidle" });
+      await expect(title).toBeVisible();
+      const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
+      expect(initialColor).toBeTruthy();
+      const modifiedCss = originalCss.replace(".main-title {", ".main-title {\n	color: rgb(255, 0, 0);");
+      const reloadPromise = page.waitForEvent("framenavigated", {
+        predicate: (frame) => frame === page.mainFrame(),
+        timeout: 1e4
+      });
+      await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+      await reloadPromise;
+      await page.waitForLoadState("networkidle");
+      await expect.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 1e4 }).toBe("rgb(255, 0, 0)");
+    } finally {
+      await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+    }
   });
 });

package/src/hmr/strategies/js-hmr-strategy.d.ts

@@ -2,12 +2,15 @@
  * JavaScript HMR Strategy
  *
  * Handles hot module replacement for JavaScript and TypeScript entrypoints.
- * Bundles files, replaces bare specifiers, and injects HMR boilerplate.
+ * Bundles files, inspects the emitted output, and decides whether the browser
+ * can hot-accept the change or must reload.
  *
  * @module
  */
 import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { BrowserBundleExecutor } from '../../services/assets/browser-bundle.service.js';
+import type { EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
 /**
  * Context interface providing access to HmrManager state.
  * Required for JsHmrStrategy to access registered entrypoints and configuration.
@@ -21,23 +24,7 @@ export interface JsHmrContext {
      * Map of bare specifiers to vendor URLs for import resolution.
      */
     getSpecifierMap(): Map<string, string>;
-    /**
-     * Returns entrypoints impacted by a changed dependency path.
-     *
-     * @remarks
-     * This hook is currently provided by the Node HMR manager where dependency
-     * graph metadata is extracted from the Node/esbuild build adapter.
-     */
-    getDependencyEntrypoints?(filePath: string): Set<string>;
-    /**
-     * Stores latest dependency set for an entrypoint.
-     *
-     * @remarks
-     * This hook is currently used only by the Node HMR manager to maintain a
-     * reverse invalidation index. Runtimes that do not provide it keep rebuild-all
-     * fallback semantics.
-     */
-    setEntrypointDependencies?(entrypointPath: string, dependencies: string[]): void;
+    getEntrypointDependencyGraph(): EntrypointDependencyGraph;
     /**
      * Directory where HMR bundles are written.
      */
@@ -50,23 +37,47 @@ export interface JsHmrContext {
      * Absolute path to the source directory.
      */
     getSrcDir(): string;
+    /**
+     * Absolute path to the pages directory.
+     */
+    getPagesDir(): string;
+    /**
+     * Absolute path to the layouts directory.
+     */
+    getLayoutsDir(): string;
+    /**
+     * All configured route-template extensions across integrations.
+     */
+    getTemplateExtensions(): string[];
+    /**
+     * Browser bundler used to rebuild changed entrypoints.
+     */
+    getBrowserBundleService(): BrowserBundleExecutor;
+    /**
+     * Returns whether a watched entrypoint should be rebuilt by the generic JS strategy.
+     *
+     * @remarks
+     * Integrations with higher-priority HMR strategies can use this to keep the
+     * generic JS strategy from overwriting their emitted entrypoints when a shared
+     * dependency changes.
+     */
+    shouldProcessEntrypoint?(entrypointPath: string): boolean;
 }
 /**
  * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
  *
- * This strategy rebuilds all registered entrypoints when any file changes,
- * as we don't currently track dependencies. This is safe but inefficient.
- *
  * The processing steps are:
  * 1. Check if any entrypoints are registered
- * 2. Rebuild all entrypoints (the changed file could be a dependency)
- * 3. Replace bare specifiers with vendor URLs
+ * 2. Rebuild impacted entrypoints, or all watched entrypoints when no runtime
+ *    dependency graph is available
+ * 3. Emit rebuilt entrypoint bundles for browser delivery
  * 4. Inject generic HMR boilerplate
  * 5. Broadcast update events for each rebuilt entrypoint
  *
  * @remarks
- * Future enhancement: Track dependencies using Bun's transpiler API to only
- * rebuild affected entrypoints instead of all of them.
+ * Node can provide dependency-graph metadata, so this strategy can rebuild only
+ * the entrypoints impacted by a changed dependency. Runtimes that do not expose
+ * that metadata intentionally keep the rebuild-all fallback.
  *
  * @see https://bun.sh/docs/runtime/transpiler
  *
@@ -83,8 +94,8 @@ export interface JsHmrContext {
  * ```
  */
 export declare class JsHmrStrategy extends HmrStrategy {
-    private context;
     readonly type = HmrStrategyType.SCRIPT;
+    private context;
     constructor(context: JsHmrContext);
     /**
      * Determines if the file is a JS/TS file that could affect registered entrypoints.
@@ -105,32 +116,24 @@ export declare class JsHmrStrategy extends HmrStrategy {
      * @remarks
      * If runtime-specific dependency graph hooks are unavailable, this strategy
      * falls back to rebuilding all watched entrypoints.
+     * When multiple entrypoints are impacted they are bundled in a single esbuild
+     * invocation to share AST parsing and chunk deduplication.
      * @returns Action to broadcast update events
      */
     process(filePath: string): Promise<HmrAction>;
     /**
-     * Bundles a single entrypoint and processes the output.
-     *
-     * @param entrypointPath - Absolute path to the source file
-     * @param outputUrl - URL path for the bundled file
-     * @returns True if bundling was successful
+     * Bundles one or more entrypoints in a single esbuild invocation.
+     * Uses the source directory as the output base so that the directory structure
+     * is preserved under the HMR dist folder.
      */
-    private bundleEntrypoint;
+    private bundleEntrypoints;
     /**
-     * Processes bundled output by replacing specifiers and injecting HMR code.
+     * Processes bundled output and determines whether the browser can hot-accept
+     * the update or must fall back to a full reload.
      *
      * @param filepath - Path to the bundled output file
      * @param url - URL path for the bundled file
      * @returns True if processing was successful and update should be broadcast
      */
     private processOutput;
-    /**
-     * Replaces bare specifiers with vendor URLs.
-     *
-     * Handles both static imports and dynamic imports.
-     *
-     * @param code - The bundled code to transform
-     * @returns The transformed code with vendor URLs
-     */
-    private replaceBareSpecifiers;
 }