@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.1

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

@@ -0,0 +1,17 @@
+export 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 component identity${parentHint}. Plain functions and untyped components are not valid dependency entries.`;
+}
+/**
+ * Thrown when `dependencies.components` contains a plain function or component
+ * without plugin-bound component identity attribution.
+ */
+export 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;
+    }
+}

package/src/global/app-logger.js

@@ -1,6 +1,3 @@
-import { Logger } from "@ecopages/logger";
-const debug = process.env.ECOPAGES_LOGGER_DEBUG === "true";
-const appLogger = new Logger("[@ecopages/core]", { debug });
-export {
-  appLogger
-};
+import { Logger } from '@ecopages/logger';
+const debug = process.env.ECOPAGES_LOGGER_DEBUG === 'true';
+export const appLogger = new Logger('[@ecopages/core]', { debug });

package/src/hmr/README.md

@@ -24,3 +24,24 @@ It is responsible for:
 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.
+
+## Registered entrypoints and dev transform
+
+`SharedHmrManager` in `adapters/shared/hmr/` centralizes file-change handling via `handleFileChange()`. Server invalidation, integration hooks, rebuild, and client broadcast run in one sequence.
+
+Dev client modules are served on demand through `DevTransformServer` (`src/dev/`). `DevTransformEntrypointRegistry` tracks registered entrypoints for HMR invalidation. Registration returns a stable dev-transform URL immediately; the first request (or cache miss) runs Rolldown on demand.
+
+`BrowserBundleService` is the sole browser-plugin resolver for HMR builds. HMR managers route `hmr-runtime` and `hmr-entrypoint` rebuilds through the `browser-hmr` executor profile.
+
+Hosts call `prepareHmrFileChange()` before HMR dispatch (`hmr/hmr-file-change-prep.ts`) so page browser graph sessions invalidate consistently with file changes.
+
+## Client events
+
+| Event           | Client behavior                                                                                                                                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `update`        | Cache-bust and re-import the changed module URL (or reload the active page module)                                                                                                                         |
+| `css-update`    | Refresh matching stylesheet `link` hrefs                                                                                                                                                                   |
+| `layout-update` | Soft current-page reload with layout cache cleared (`persistLayouts` remounts the updated layout without a full document reload). Falls back to `location.reload()` only if no navigation owner handles it |
+| `reload`        | Full `location.reload()`                                                                                                                                                                                   |
+
+Dev-transform local imports are rewritten with a content-hash query (`?v=…`) so transitive layout/component modules get a new ESM module-map key after invalidation. Soft `layout-update` then picks up the new layout while shared outer layout persistence still applies across normal SPA navigations.

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

@@ -1,117 +1,126 @@
-import { getEcoNavigationRuntime } from "../../router/client/navigation-coordinator.js";
-(function() {
-  const WS_URL = "ws://" + location.host + "/_hmr";
-  let socket;
-  let reconnectAttempts = 0;
-  function connect() {
-    socket = new WebSocket(WS_URL);
-    socket.addEventListener("open", () => {
-      console.log("[ecopages] HMR Connected");
-      reconnectAttempts = 0;
-    });
-    socket.addEventListener("message", async (event) => {
-      try {
-        const payload = JSON.parse(event.data);
-        handleMessage(payload);
-      } catch (e) {
-        console.error("[ecopages] Invalid HMR message:", e);
-      }
-    });
-    socket.addEventListener("close", () => {
-      if (reconnectAttempts < 10) {
-        setTimeout(connect, 1e3 * 2 ** reconnectAttempts);
-        reconnectAttempts++;
-      }
-    });
-  }
-  async function handleMessage(payload) {
-    const navigationRuntime = getEcoNavigationRuntime(window);
-    switch (payload.type) {
-      case "reload":
-        await waitForNavigationToSettle(navigationRuntime);
-        location.reload();
-        break;
-      case "layout-update": {
-        await waitForNavigationToSettle(navigationRuntime);
-        if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
-        } else {
-          location.reload();
-        }
-        break;
-      }
-      case "error":
-        console.error("[ecopages] HMR Error:", payload.message);
-        break;
-      case "update":
-        if (payload.path) {
-          await applyUpdate(payload.path, payload.timestamp);
-        }
-        break;
-      case "css-update":
-        if (payload.path) {
-          refreshStylesheet(payload.path);
-        }
-        break;
+/**
+ * Ecopages HMR Runtime
+ * Injected into the browser to handle Hot Module Replacement updates.
+ */
+import { getEcoNavigationRuntime } from '../../router/client/navigation-coordinator.js';
+import { applyModuleUpdate, resolveActiveModuleUrl } from './module-update.js';
+(function () {
+    const WS_URL = 'ws://' + location.host + '/_hmr';
+    let socket;
+    let reconnectAttempts = 0;
+    function connect() {
+        socket = new WebSocket(WS_URL);
+        socket.addEventListener('open', () => {
+            console.log('[ecopages] HMR Connected');
+            window.__ECO_HMR_CONNECTED__ = true;
+            reconnectAttempts = 0;
+        });
+        socket.addEventListener('message', async (event) => {
+            try {
+                const payload = JSON.parse(event.data);
+                await handleMessage(payload);
+            }
+            catch (e) {
+                console.error('[ecopages] Invalid HMR message:', e);
+            }
+        });
+        socket.addEventListener('close', () => {
+            window.__ECO_HMR_CONNECTED__ = false;
+            if (reconnectAttempts < 10) {
+                setTimeout(connect, 1000 * 2 ** reconnectAttempts);
+                reconnectAttempts++;
+            }
+        });
     }
-  }
-  async function applyUpdate(path, timestamp) {
-    try {
-      const url = path + "?t=" + (timestamp || Date.now());
-      const handlers = window.__ECO_PAGES__?.hmrHandlers;
-      const navigationRuntime = getEcoNavigationRuntime(window);
-      await waitForNavigationToSettle(navigationRuntime);
-      if (handlers?.[path]) {
-        await handlers[path](url);
-        return;
-      }
-      await import(url);
-      if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
-      }
-    } catch (e) {
-      console.error("[ecopages] Failed to apply HMR update:", e);
+    async function handleMessage(payload) {
+        const navigationRuntime = getEcoNavigationRuntime(window);
+        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(),
+                })) {
+                    break;
+                }
+                if (window.__ECOPAGES_HOST_OWNS_RELOAD__) {
+                    break;
+                }
+                location.reload();
+                break;
+            }
+            case 'error':
+                console.error('[ecopages] HMR Error:', payload.message);
+                break;
+            case 'update':
+                if (payload.path) {
+                    await applyUpdate(payload.path, payload.timestamp);
+                }
+                break;
+            case 'css-update':
+                if (payload.path) {
+                    refreshStylesheet(payload.path);
+                }
+                break;
+        }
     }
-  }
-  function getActiveHmrModuleUrl() {
-    const pageModule = window.__ECO_PAGES__?.page?.module;
-    if (pageModule && pageModule.includes("/assets/_hmr/")) {
-      return pageModule.split("?")[0];
+    async function applyUpdate(path, timestamp) {
+        const navigationRuntime = getEcoNavigationRuntime(window);
+        await applyModuleUpdate(path, {
+            getHandlers: () => window.__ECO_PAGES__?.hmrHandlers,
+            getActivePageModule: () => window.__ECO_PAGES__?.page?.module,
+            reloadCurrentPage: async (request) => Boolean(await navigationRuntime.reloadCurrentPage(request)),
+            importModule: (url) => import(url),
+            waitForSettled: async () => waitForNavigationToSettle(navigationRuntime),
+        }, timestamp);
     }
-    const handlerPaths = Object.keys(window.__ECO_PAGES__?.hmrHandlers ?? {});
-    return handlerPaths[handlerPaths.length - 1];
-  }
-  async function waitForNavigationToSettle(navigationRuntime) {
-    if (!navigationRuntime.hasPendingNavigationTransaction()) {
-      return;
+    function getActiveHmrModuleUrl() {
+        return resolveActiveModuleUrl(window.__ECO_PAGES__?.hmrHandlers ?? {}, window.__ECO_PAGES__?.page?.module);
     }
-    await new Promise((resolve) => {
-      const startedAt = performance.now();
-      const timeoutMs = 2e3;
-      const poll = () => {
+    async function waitForNavigationToSettle(navigationRuntime) {
         if (!navigationRuntime.hasPendingNavigationTransaction()) {
-          resolve();
-          return;
+            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"]');
-    links.forEach((link) => {
-      const href = link.href;
-      if (href.includes(filename) || href.includes(path.replace(/^.*\/src\//, "/assets/"))) {
-        const url = new URL(href, location.origin);
-        url.searchParams.set("t", Date.now().toString());
-        link.href = url.toString();
-        console.log("[ecopages] CSS updated:", filename);
-      }
-    });
-  }
-  connect();
+        await new Promise((resolve) => {
+            const startedAt = performance.now();
+            const timeoutMs = 5_000;
+            const poll = () => {
+                if (!navigationRuntime.hasPendingNavigationTransaction()) {
+                    resolve();
+                    return;
+                }
+                if (performance.now() - startedAt >= timeoutMs) {
+                    resolve();
+                    return;
+                }
+                requestAnimationFrame(poll);
+            };
+            requestAnimationFrame(poll);
+        });
+    }
+    /**
+     * Hot-reload CSS by updating stylesheet link href with cache-busting query param.
+     * This causes the browser to re-fetch the stylesheet without a full page reload.
+     */
+    function refreshStylesheet(path) {
+        const filename = path.split('/').pop() || '';
+        const links = document.querySelectorAll('link[rel="stylesheet"]');
+        links.forEach((link) => {
+            const href = link.href;
+            if (href.includes(filename) || href.includes(path.replace(/^.*\/src\//, '/assets/'))) {
+                const url = new URL(href, location.origin);
+                url.searchParams.set('t', Date.now().toString());
+                link.href = url.toString();
+                console.log('[ecopages] CSS updated:', filename);
+            }
+        });
+    }
+    connect();
 })();

package/src/hmr/client/module-update.d.ts

@@ -0,0 +1,13 @@
+export type HmrModuleHandlers = Record<string, (url: string) => Promise<void> | void>;
+export type ApplyModuleUpdateContext = {
+    getHandlers: () => HmrModuleHandlers | undefined;
+    getActivePageModule?: () => string | undefined;
+    reloadCurrentPage: (request: {
+        clearCache: boolean;
+        moduleUrl: string;
+    }) => Promise<boolean>;
+    importModule: (url: string) => Promise<unknown>;
+    waitForSettled: () => Promise<void>;
+};
+export declare function resolveActiveModuleUrl(handlers: HmrModuleHandlers, pageModule?: string): string | undefined;
+export declare function applyModuleUpdate(path: string, context: ApplyModuleUpdateContext, timestamp?: number): Promise<void>;

package/src/hmr/client/module-update.js

@@ -0,0 +1,39 @@
+import { isDevTransformModuleUrl, stripModuleUrlQuery, withModuleCacheBust } from '../hmr-asset-paths.js';
+export function resolveActiveModuleUrl(handlers, pageModule) {
+    if (pageModule) {
+        const basePath = stripModuleUrlQuery(pageModule);
+        if (isDevTransformModuleUrl(basePath)) {
+            return basePath;
+        }
+    }
+    const handlerPaths = Object.keys(handlers);
+    for (let index = handlerPaths.length - 1; index >= 0; index -= 1) {
+        const handlerPath = handlerPaths[index];
+        if (isDevTransformModuleUrl(handlerPath)) {
+            return handlerPath;
+        }
+    }
+    return handlerPaths[handlerPaths.length - 1];
+}
+export async function applyModuleUpdate(path, context, timestamp) {
+    const basePath = stripModuleUrlQuery(path);
+    const url = withModuleCacheBust(basePath, timestamp);
+    const handlers = context.getHandlers();
+    await context.waitForSettled();
+    const handler = handlers?.[basePath];
+    if (handler) {
+        await handler(url);
+        return;
+    }
+    if (isDevTransformModuleUrl(basePath)) {
+        const activePageModule = context.getActivePageModule?.();
+        const isActivePageModule = activePageModule !== undefined && stripModuleUrlQuery(activePageModule) === basePath;
+        if (isActivePageModule) {
+            await context.reloadCurrentPage({ clearCache: false, moduleUrl: url });
+            return;
+        }
+        await context.importModule(url);
+        return;
+    }
+    console.warn(`[ecopages] No HMR handler for module update: ${basePath}`);
+}

package/src/hmr/hmr-asset-paths.d.ts

@@ -0,0 +1,14 @@
+export declare const DEV_TRANSFORM_URL_PREFIX = "/assets/__eco_dev__";
+export declare const VENDOR_URL_PREFIX = "/assets/vendors";
+/**
+ * Strips cache-busting query parameters from a browser module URL.
+ */
+export declare function stripModuleUrlQuery(moduleUrl: string): string;
+/**
+ * Returns true when a module URL is served by the dev transform server.
+ */
+export declare function isDevTransformModuleUrl(moduleUrl: string): boolean;
+/**
+ * Appends a cache-busting query parameter for hot module imports.
+ */
+export declare function withModuleCacheBust(moduleUrl: string, timestamp?: number): string;

package/src/hmr/hmr-asset-paths.js

@@ -0,0 +1,22 @@
+import { RESOLVED_ASSETS_DIR } from '../config/constants.js';
+export const DEV_TRANSFORM_URL_PREFIX = `/${RESOLVED_ASSETS_DIR}/__eco_dev__`;
+export const VENDOR_URL_PREFIX = `/${RESOLVED_ASSETS_DIR}/vendors`;
+/**
+ * Strips cache-busting query parameters from a browser module URL.
+ */
+export function stripModuleUrlQuery(moduleUrl) {
+    return moduleUrl.split('?')[0] ?? moduleUrl;
+}
+/**
+ * Returns true when a module URL is served by the dev transform server.
+ */
+export function isDevTransformModuleUrl(moduleUrl) {
+    return stripModuleUrlQuery(moduleUrl).startsWith(`${DEV_TRANSFORM_URL_PREFIX}/`);
+}
+/**
+ * Appends a cache-busting query parameter for hot module imports.
+ */
+export function withModuleCacheBust(moduleUrl, timestamp) {
+    const basePath = stripModuleUrlQuery(moduleUrl);
+    return `${basePath}?t=${timestamp ?? Date.now()}`;
+}

package/src/hmr/hmr-entrypoint-output.d.ts

@@ -0,0 +1,21 @@
+export type HmrEntrypointRole = 'page' | 'script';
+export interface ResolvedHmrEntrypoint {
+    sourcePath: string;
+    /**
+     * Emitted artifact path for disk-based HMR, or the resolved source path for
+     * dev-transform entrypoints where modules are served on demand.
+     */
+    outputPath: string;
+    outputUrl: string;
+    role: HmrEntrypointRole;
+}
+export declare function isRegisteredDevTransformEntrypoint(registered: ReadonlyMap<string, ResolvedHmrEntrypoint>, filePath: string): boolean;
+export declare function isRegisteredScriptEntrypoint(registered: ReadonlyMap<string, ResolvedHmrEntrypoint>, filePath: string): boolean;
+export declare function encodeHmrDynamicSegments(filepath: string): string;
+export declare function decodeHmrDynamicSegments(filepath: string): string;
+/**
+ * @remarks
+ * Runtime rebuilds must delete the previous artifact so the bundler does not
+ * reuse a stale bundle when the source file changed.
+ */
+export declare function removeStaleHmrEntrypointOutput(outputPath: string, scope: string): void;

package/src/hmr/hmr-entrypoint-output.js

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { appLogger } from '../global/app-logger.js';
+function resolveRegisteredEntrypoint(registered, filePath) {
+    return registered.get(path.resolve(filePath));
+}
+export function isRegisteredDevTransformEntrypoint(registered, filePath) {
+    return resolveRegisteredEntrypoint(registered, filePath) !== undefined;
+}
+export function isRegisteredScriptEntrypoint(registered, filePath) {
+    return resolveRegisteredEntrypoint(registered, filePath)?.role === 'script';
+}
+export function encodeHmrDynamicSegments(filepath) {
+    return filepath.replace(/\[([^\]]+)\]/g, '_$1_');
+}
+export function decodeHmrDynamicSegments(filepath) {
+    return filepath.replace(/_([^_/\\]+)_/g, '[$1]');
+}
+/**
+ * @remarks
+ * Runtime rebuilds must delete the previous artifact so the bundler does not
+ * reuse a stale bundle when the source file changed.
+ */
+export function removeStaleHmrEntrypointOutput(outputPath, scope) {
+    if (!fileSystem.exists(outputPath)) {
+        return;
+    }
+    try {
+        fileSystem.remove(outputPath);
+    }
+    catch (error) {
+        appLogger.warn(`[${scope}] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/src/hmr/hmr-file-change-prep.d.ts

@@ -0,0 +1,10 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import { type AffectedGraphIdentity } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
+export type HmrFileChangePreparation = {
+    affectedGraphIdentities: AffectedGraphIdentity[];
+    invalidatedGraphCount: number;
+};
+/**
+ * Invalidates affected Page Browser Graph records before HMR strategy dispatch.
+ */
+export declare function prepareHmrFileChange(appConfig: EcoPagesAppConfig, filePath: string): HmrFileChangePreparation;

package/src/hmr/hmr-file-change-prep.js

@@ -0,0 +1,14 @@
+import path from 'node:path';
+import { getAffectedPageBrowserGraphIdentities, invalidatePageBrowserGraphSession, } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
+/**
+ * Invalidates affected Page Browser Graph records before HMR strategy dispatch.
+ */
+export function prepareHmrFileChange(appConfig, filePath) {
+    const resolvedFilePath = path.resolve(filePath);
+    const affectedGraphIdentities = getAffectedPageBrowserGraphIdentities(appConfig, resolvedFilePath);
+    const invalidatedGraphCount = invalidatePageBrowserGraphSession(appConfig, resolvedFilePath);
+    return {
+        affectedGraphIdentities,
+        invalidatedGraphCount,
+    };
+}

package/src/hmr/hmr-registered-entrypoints-context.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedHmrEntrypoint } from './hmr-entrypoint-output.js';
+/**
+ * Read-only access to dev-transform entrypoints registered for HMR.
+ */
+export interface HmrRegisteredEntrypointsContext {
+    getRegisteredEntrypoints(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
+}

package/src/hmr/hmr-registered-entrypoints-context.js

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

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

@@ -0,0 +1,10 @@
+/** On-disk work directory segment under {@link RESOLVED_ASSETS_DIR} for the bundled HMR client runtime. */
+export declare const HMR_RUNTIME_WORK_DIR_SEGMENT = "hmr-runtime";
+/** Browser URL for the bundled HMR client runtime script. */
+export declare const HMR_RUNTIME_SCRIPT_URL = "/_hmr_runtime.js";
+/** WebSocket path used by the HMR client runtime for dev server events. */
+export declare const HMR_WEBSOCKET_PATH = "/_hmr";
+/**
+ * Absolute work-directory path for HMR runtime artifacts under an app work dir.
+ */
+export declare function resolveHmrRuntimeWorkDir(workDir: string): string;

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

@@ -0,0 +1,13 @@
+import { RESOLVED_ASSETS_DIR } from '../config/constants.js';
+/** On-disk work directory segment under {@link RESOLVED_ASSETS_DIR} for the bundled HMR client runtime. */
+export const HMR_RUNTIME_WORK_DIR_SEGMENT = 'hmr-runtime';
+/** Browser URL for the bundled HMR client runtime script. */
+export const HMR_RUNTIME_SCRIPT_URL = '/_hmr_runtime.js';
+/** WebSocket path used by the HMR client runtime for dev server events. */
+export const HMR_WEBSOCKET_PATH = '/_hmr';
+/**
+ * Absolute work-directory path for HMR runtime artifacts under an app work dir.
+ */
+export function resolveHmrRuntimeWorkDir(workDir) {
+    return `${workDir}/${RESOLVED_ASSETS_DIR}/${HMR_RUNTIME_WORK_DIR_SEGMENT}`;
+}

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

@@ -133,6 +133,15 @@ export declare abstract class HmrStrategy {
      * ```
      */
     abstract matches(filePath: string): boolean;
+    /**
+     * Returns whether this strategy supplies dev-transform plugins for a source module.
+     *
+     * @remarks
+     * Used by {@link DevTransformBundler} to select integration-owned plugins for any
+     * module in the per-file ESM graph (pages and imported children). File-change
+     * dispatch continues to use {@link matches}.
+     */
+    ownsDevTransformEntrypoint(_sourcePath: string): boolean;
     /**
      * Processes a file change and returns the action to take.
      *