@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.33

package/src/route-renderer/page-loading/page-module-loader.js

@@ -1,127 +1,133 @@
-import { invariant } from "../../utils/invariant.js";
-import { getAppModuleLoader } from "../../services/module-loading/app-server-module-transpiler.service.js";
-import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
-class PageModuleLoaderService {
-  appModuleLoader;
-  appConfig;
-  runtimeOrigin;
-  /**
-   * Creates the page-module loader for one app/runtime instance.
-   *
-   * @param appConfig Finalized app config that owns build and invalidation state.
-   * @param runtimeOrigin Runtime origin exposed to page data hooks.
-   */
-  constructor(appConfig, runtimeOrigin) {
-    this.appConfig = appConfig;
-    this.runtimeOrigin = runtimeOrigin;
-    this.appModuleLoader = getAppModuleLoader(appConfig);
-  }
-  /**
-   * Imports one page module through the shared server-side module loading path.
-   *
-   * @remarks
-   * The underlying transpiler keeps Bun and Node aligned on one framework-owned
-   * loading contract even though the runtime-specific execution transport differs.
-   */
-  async importPageFile(file, options) {
-    try {
-      return await this.appModuleLoader.importModule({
-        filePath: file,
-        rootDir: this.appConfig.rootDir,
-        outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
-        bypassCache: options?.bypassCache,
-        cacheScope: options?.cacheScope,
-        transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
-        noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`
-      });
-    } catch (error) {
-      invariant(false, `Error importing page file: ${error}`);
+import { invariant } from '../../utils/invariant.js';
+import { getAppModuleLoader } from '../../services/module-loading/app-server-module-transpiler.service.js';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.js';
+/**
+ * Loads route page modules and normalizes their data hooks for rendering.
+ *
+ * @remarks
+ * This service keeps the render pipeline from depending directly on raw module
+ * imports. It owns the shared server-module transpiler setup, the precedence
+ * rules between component statics and module exports, and the normalization of
+ * page props and metadata into one renderer-facing shape.
+ */
+export class PageModuleLoaderService {
+    appModuleLoader;
+    appConfig;
+    runtimeOrigin;
+    /**
+     * Creates the page-module loader for one app/runtime instance.
+     *
+     * @param appConfig Finalized app config that owns build and invalidation state.
+     * @param runtimeOrigin Runtime origin exposed to page data hooks.
+     */
+    constructor(appConfig, runtimeOrigin) {
+        this.appConfig = appConfig;
+        this.runtimeOrigin = runtimeOrigin;
+        this.appModuleLoader = getAppModuleLoader(appConfig);
     }
-  }
-  /**
-   * Executes the page's static-props hook with Ecopages runtime context.
-   *
-   * @remarks
-   * Pages without a static-props hook still return a normalized empty props
-   * object so downstream render preparation does not branch on hook presence.
-   */
-  async getStaticPropsForPage(options) {
-    const { getStaticProps, params } = options;
-    return getStaticProps ? await getStaticProps({
-      pathname: { params: params ?? {} },
-      appConfig: this.appConfig,
-      runtimeOrigin: this.runtimeOrigin
-    }).then((data) => data).catch((err) => {
-      throw new Error(`Error fetching static props: ${err.message}`);
-    }) : {
-      props: {},
-      metadata: void 0
-    };
-  }
-  /**
-   * Builds the final page metadata object for one render request.
-   *
-   * @remarks
-   * App-level default metadata forms the baseline, then page-level metadata is
-   * overlaid so route-specific fields win without dropping global defaults.
-   */
-  async getMetadataPropsForPage(options) {
-    const { getMetadata, context } = options;
-    let metadata = this.appConfig.defaultMetadata;
-    if (getMetadata) {
-      const dynamicMetadata = await getMetadata({
-        params: context.params,
-        query: context.query,
-        props: context.props,
-        appConfig: this.appConfig
-      });
-      metadata = { ...metadata, ...dynamicMetadata };
+    /**
+     * Imports one page module through the shared server-side module loading path.
+     *
+     * @remarks
+     * The underlying transpiler keeps Bun and Node aligned on one framework-owned
+     * loading contract even though the runtime-specific execution transport differs.
+     */
+    async importPageFile(file, options) {
+        try {
+            return await this.appModuleLoader.importModule({
+                filePath: file,
+                rootDir: this.appConfig.rootDir,
+                outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
+                bypassCache: options?.bypassCache,
+                cacheScope: options?.cacheScope,
+                transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
+                noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`,
+            });
+        }
+        catch (error) {
+            invariant(false, `Error importing page file: ${error}`);
+        }
+    }
+    /**
+     * Executes the page's static-props hook with Ecopages runtime context.
+     *
+     * @remarks
+     * Pages without a static-props hook still return a normalized empty props
+     * object so downstream render preparation does not branch on hook presence.
+     */
+    async getStaticPropsForPage(options) {
+        const { getStaticProps, params } = options;
+        return getStaticProps
+            ? await getStaticProps({
+                pathname: { params: params ?? {} },
+                appConfig: this.appConfig,
+                runtimeOrigin: this.runtimeOrigin,
+            })
+                .then((data) => data)
+                .catch((err) => {
+                throw new Error(`Error fetching static props: ${err.message}`);
+            })
+            : {
+                props: {},
+                metadata: undefined,
+            };
+    }
+    /**
+     * Builds the final page metadata object for one render request.
+     *
+     * @remarks
+     * App-level default metadata forms the baseline, then page-level metadata is
+     * overlaid so route-specific fields win without dropping global defaults.
+     */
+    async getMetadataPropsForPage(options) {
+        const { getMetadata, context } = options;
+        let metadata = this.appConfig.defaultMetadata;
+        if (getMetadata) {
+            const dynamicMetadata = await getMetadata({
+                params: context.params,
+                query: context.query,
+                props: context.props,
+                appConfig: this.appConfig,
+            });
+            metadata = { ...metadata, ...dynamicMetadata };
+        }
+        return metadata;
+    }
+    /**
+     * Loads a page module and normalizes integration-facing exports.
+     * When both component static methods and module exports exist, component statics win.
+     */
+    async resolvePageModule(options) {
+        const module = await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file);
+        const { default: Page, getStaticProps: moduleGetStaticProps, getMetadata: moduleGetMetadata, ...integrationSpecificProps } = module;
+        return {
+            Page,
+            getStaticProps: Page.staticProps ?? moduleGetStaticProps,
+            getMetadata: Page.metadata ?? moduleGetMetadata,
+            integrationSpecificProps,
+        };
+    }
+    /**
+     * Resolves the page data needed by the render pipeline.
+     *
+     * @remarks
+     * Static props are resolved first because page metadata may depend on those
+     * props. This preserves the same ordering whether data hooks are declared as
+     * component statics or module exports.
+     */
+    async resolvePageData(options) {
+        const { props } = await this.getStaticPropsForPage({
+            getStaticProps: options.pageModule.getStaticProps,
+            params: options.routeOptions.params,
+        });
+        const metadata = await this.getMetadataPropsForPage({
+            getMetadata: options.pageModule.getMetadata,
+            context: {
+                props,
+                params: options.routeOptions.params ?? {},
+                query: options.routeOptions.query ?? {},
+            },
+        });
+        return { props, metadata };
     }
-    return metadata;
-  }
-  /**
-   * Loads a page module and normalizes integration-facing exports.
-   * When both component static methods and module exports exist, component statics win.
-   */
-  async resolvePageModule(options) {
-    const module = await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file);
-    const {
-      default: Page,
-      getStaticProps: moduleGetStaticProps,
-      getMetadata: moduleGetMetadata,
-      ...integrationSpecificProps
-    } = module;
-    return {
-      Page,
-      getStaticProps: Page.staticProps ?? moduleGetStaticProps,
-      getMetadata: Page.metadata ?? moduleGetMetadata,
-      integrationSpecificProps
-    };
-  }
-  /**
-   * Resolves the page data needed by the render pipeline.
-   *
-   * @remarks
-   * Static props are resolved first because page metadata may depend on those
-   * props. This preserves the same ordering whether data hooks are declared as
-   * component statics or module exports.
-   */
-  async resolvePageData(options) {
-    const { props } = await this.getStaticPropsForPage({
-      getStaticProps: options.pageModule.getStaticProps,
-      params: options.routeOptions.params
-    });
-    const metadata = await this.getMetadataPropsForPage({
-      getMetadata: options.pageModule.getMetadata,
-      context: {
-        props,
-        params: options.routeOptions.params ?? {},
-        query: options.routeOptions.query ?? {}
-      }
-    });
-    return { props, metadata };
-  }
 }
-export {
-  PageModuleLoaderService
-};

package/src/route-renderer/route-renderer.js

@@ -1,80 +1,78 @@
-import { invariant } from "../utils/invariant.js";
-import { PathUtils } from "../utils/path-utils.module.js";
-class RouteRendererFactory {
-  appConfig;
-  runtimeOrigin;
-  rendererModules;
-  rendererCache = /* @__PURE__ */ new Map();
-  /**
-   * Creates the route-renderer factory for one app/runtime instance.
-   */
-  constructor({
-    appConfig,
-    rendererModules,
-    runtimeOrigin
-  }) {
-    this.appConfig = appConfig;
-    this.rendererModules = rendererModules;
-    this.runtimeOrigin = runtimeOrigin;
-  }
-  /**
-   * Returns a route renderer for the supplied route file.
-   */
-  getPageRenderer(filePath) {
-    const integrationRenderer = this.getRouteRendererEngine(filePath);
-    invariant(!!integrationRenderer, `No integration renderer found for file: ${filePath}`);
-    return integrationRenderer;
-  }
-  /**
-   * Returns a renderer for an explicit view integration.
-   */
-  getExplicitViewRenderer(integrationName) {
-    const integrationPlugin = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
-    if (!integrationPlugin) {
-      return null;
+import { invariant } from '../utils/invariant.js';
+import { PathUtils } from '../utils/path-utils.module.js';
+/**
+ * Selects and caches integration renderers for route files and explicit views.
+ *
+ * @remarks
+ * The factory owns the policy that maps a route file or explicit integration
+ * name to one initialized integration renderer. Renderer instances are cached by
+ * integration name so repeated requests do not rebuild renderer state.
+ */
+export class RouteRendererFactory {
+    appConfig;
+    runtimeOrigin;
+    rendererModules;
+    rendererCache = new Map();
+    /**
+     * Creates the route-renderer factory for one app/runtime instance.
+     */
+    constructor({ appConfig, rendererModules, runtimeOrigin, }) {
+        this.appConfig = appConfig;
+        this.rendererModules = rendererModules;
+        this.runtimeOrigin = runtimeOrigin;
     }
-    const cached = this.rendererCache.get(integrationName);
-    if (cached) {
-      return cached;
+    /**
+     * Returns a route renderer for the supplied route file.
+     */
+    getPageRenderer(filePath) {
+        const integrationRenderer = this.getRouteRendererEngine(filePath);
+        invariant(!!integrationRenderer, `No integration renderer found for file: ${filePath}`);
+        return integrationRenderer;
     }
-    const renderer = integrationPlugin.initializeRenderer({
-      rendererModules: this.rendererModules
-    });
-    this.rendererCache.set(integrationName, renderer);
-    return renderer;
-  }
-  /**
-   * Resolves the integration plugin that owns a given route file.
-   */
-  getIntegrationPlugin(filePath) {
-    const templateExtension = PathUtils.getEcoTemplateExtension(filePath);
-    const isIntegrationPlugin = (plugin) => {
-      return plugin.extensions.some((extension) => templateExtension === extension);
-    };
-    const integrationPlugin = this.appConfig.integrations.find(isIntegrationPlugin);
-    invariant(
-      !!integrationPlugin,
-      `No integration plugin found for template extension: ${templateExtension}, file: ${filePath}`
-    );
-    return integrationPlugin;
-  }
-  /**
-   * Returns the cached renderer engine for the file's owning integration,
-   * creating it on first use.
-   */
-  getRouteRendererEngine(filePath) {
-    const integrationPlugin = this.getIntegrationPlugin(filePath);
-    const cached = this.rendererCache.get(integrationPlugin.name);
-    if (cached) {
-      return cached;
+    /**
+     * Returns a renderer for an explicit view integration.
+     */
+    getExplicitViewRenderer(integrationName) {
+        const integrationPlugin = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
+        if (!integrationPlugin) {
+            return null;
+        }
+        const cached = this.rendererCache.get(integrationName);
+        if (cached) {
+            return cached;
+        }
+        const renderer = integrationPlugin.initializeRenderer({
+            rendererModules: this.rendererModules,
+        });
+        this.rendererCache.set(integrationName, renderer);
+        return renderer;
+    }
+    /**
+     * Resolves the integration plugin that owns a given route file.
+     */
+    getIntegrationPlugin(filePath) {
+        const templateExtension = PathUtils.getEcoTemplateExtension(filePath);
+        const isIntegrationPlugin = (plugin) => {
+            return plugin.extensions.some((extension) => templateExtension === extension);
+        };
+        const integrationPlugin = this.appConfig.integrations.find(isIntegrationPlugin);
+        invariant(!!integrationPlugin, `No integration plugin found for template extension: ${templateExtension}, file: ${filePath}`);
+        return integrationPlugin;
+    }
+    /**
+     * Returns the cached renderer engine for the file's owning integration,
+     * creating it on first use.
+     */
+    getRouteRendererEngine(filePath) {
+        const integrationPlugin = this.getIntegrationPlugin(filePath);
+        const cached = this.rendererCache.get(integrationPlugin.name);
+        if (cached) {
+            return cached;
+        }
+        const renderer = integrationPlugin.initializeRenderer({
+            rendererModules: this.rendererModules,
+        });
+        this.rendererCache.set(integrationPlugin.name, renderer);
+        return renderer;
     }
-    const renderer = integrationPlugin.initializeRenderer({
-      rendererModules: this.rendererModules
-    });
-    this.rendererCache.set(integrationPlugin.name, renderer);
-    return renderer;
-  }
 }
-export {
-  RouteRendererFactory
-};

package/src/router/README.md

@@ -22,6 +22,7 @@ router/
 │   └── route-registry.ts        # Owns template routes, request matching, static expansion, and reload
 └── client/                      # Browser-side navigation coordination
     ├── navigation-coordinator.ts # Singleton runtime coordinator
+    ├── navigation-lifecycle.ts   # Shared document lifecycle events
     └── link-intent.ts           # Shared anchor detection and intent recovery helpers
 ```
 
@@ -79,6 +80,28 @@ The coordinator is framework-agnostic. Browser runtimes (e.g. `browser-router`,
 - **Reload** — `reloadCurrentPage` delegates to whichever runtime currently owns the document.
 - **Events** — `subscribe` lets runtimes react to `owner-change` and `registration-change` events.
 
+### Navigation Lifecycle (`navigation-lifecycle.ts`)
+
+Shared document lifecycle events emitted by browser runtimes after a client navigation commits.
+
+Access it with:
+
+```ts
+import {
+	completeNavigationLifecycle,
+	dispatchBeforeSwap,
+	type EcoNavigationEvent,
+} from '@ecopages/core/router/navigation-lifecycle';
+```
+
+`browser-router` and `react-router` call these helpers around their own commit implementations. Use `completeNavigationLifecycle` for the paired post-commit signals. Listeners use the DOM contract:
+
+- `eco:before-swap` — pre-commit hook with `newDocument` and `reload()`
+- `eco:after-swap` — post-commit signal after the runtime has applied the new page
+- `eco:page-load` — scheduled on the next animation frame after `eco:after-swap`
+
+This is separate from coordinator `subscribe()` events, which track runtime ownership rather than page lifecycle.
+
 ### Link Intent (`link-intent.ts`)
 
 Shared helpers for locating anchors and recovering stale navigation intent.

package/src/router/client/link-intent.js

@@ -1,44 +1,60 @@
-import { hasKnownStaticExtension } from "../../utils/static-file-extensions.js";
-function getAnchorFromNavigationEvent(event, linkSelector) {
-  const eventTarget = event.target;
-  if (eventTarget instanceof HTMLAnchorElement && eventTarget.matches(linkSelector)) {
-    return eventTarget;
-  }
-  if (eventTarget instanceof Element) {
-    const closestAnchor = eventTarget.closest(linkSelector);
-    if (closestAnchor instanceof HTMLAnchorElement) {
-      return closestAnchor;
+import { hasKnownStaticExtension } from '../../utils/static-file-extensions.js';
+/**
+ * Finds the nearest matching anchor within an event's composed path.
+ *
+ * This works across Shadow DOM boundaries, which is required for delegated
+ * navigation handling when links are rendered inside custom elements.
+ *
+ * @param event - Pointer or mouse event being inspected.
+ * @param linkSelector - Selector that identifies navigable anchors.
+ * @returns The matched anchor element, or `null` when no matching anchor exists.
+ */
+export function getAnchorFromNavigationEvent(event, linkSelector) {
+    const eventTarget = event.target;
+    if (eventTarget instanceof HTMLAnchorElement && eventTarget.matches(linkSelector)) {
+        return eventTarget;
     }
-  }
-  if (eventTarget instanceof Text) {
-    const parentAnchor = eventTarget.parentElement?.closest(linkSelector);
-    if (parentAnchor instanceof HTMLAnchorElement) {
-      return parentAnchor;
+    if (eventTarget instanceof Element) {
+        const closestAnchor = eventTarget.closest(linkSelector);
+        if (closestAnchor instanceof HTMLAnchorElement) {
+            return closestAnchor;
+        }
     }
-  }
-  return event.composedPath().find(
-    (target) => target instanceof HTMLAnchorElement && target.matches(linkSelector)
-  );
+    if (eventTarget instanceof Text) {
+        const parentAnchor = eventTarget.parentElement?.closest(linkSelector);
+        if (parentAnchor instanceof HTMLAnchorElement) {
+            return parentAnchor;
+        }
+    }
+    return event
+        .composedPath()
+        .find((target) => target instanceof HTMLAnchorElement && target.matches(linkSelector));
 }
-function isStaticAssetHref(href) {
-  try {
-    const url = new URL(href, "http://localhost");
-    return hasKnownStaticExtension(url.pathname);
-  } catch {
-    return false;
-  }
+/**
+ * Returns whether an href targets a static asset that should use a full document load.
+ */
+export function isStaticAssetHref(href) {
+    try {
+        const url = new URL(href, 'http://localhost');
+        return hasKnownStaticExtension(url.pathname);
+    }
+    catch {
+        return false;
+    }
 }
-function recoverPendingNavigationHref(intent, hasInFlightNavigation, now, maxAgeMs = 1e3) {
-  if (!intent || !hasInFlightNavigation) {
-    return null;
-  }
-  if (now - intent.timestamp > maxAgeMs) {
-    return null;
-  }
-  return intent.href;
+/**
+ * Resolves a previously captured intent while a navigation is still in flight.
+ *
+ * @remarks
+ * Pending intents expire quickly because they bridge pointer or hover capture
+ * and the later click when the DOM changes during a rapid navigation sequence.
+ */
+export function recoverPendingNavigationHref(intent, hasInFlightNavigation, now, maxAgeMs = 1000) {
+    if (!intent || !hasInFlightNavigation) {
+        return null;
+    }
+    if (now - intent.timestamp > maxAgeMs) {
+        return null;
+    }
+    return intent.href;
 }
-export {
-  getAnchorFromNavigationEvent,
-  isStaticAssetHref,
-  recoverPendingNavigationHref
-};