@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/route-renderer/route-renderer.d.ts

@@ -0,0 +1,61 @@
+import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { RouteRenderResult, RouteRendererOptions } from '../public-types.js';
+import type { IntegrationRenderer } from './orchestration/integration-renderer.js';
+/**
+ * Thin wrapper around one initialized integration renderer.
+ *
+ * @remarks
+ * This type exists so higher-level routing code can ask for a route renderer
+ * without depending on the full integration plugin lifecycle. It delegates all
+ * real work to the integration-specific renderer selected by the factory.
+ */
+export declare class RouteRenderer {
+    private renderer;
+    /**
+     * Creates a route renderer bound to one integration renderer instance.
+     */
+    constructor(renderer: IntegrationRenderer);
+    /**
+     * Executes the render pipeline for one matched route.
+     */
+    createRoute(options: RouteRendererOptions): Promise<RouteRenderResult>;
+}
+/**
+ * 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 declare class RouteRendererFactory {
+    private appConfig;
+    runtimeOrigin: string;
+    private rendererCache;
+    /**
+     * Creates the route-renderer factory for one app/runtime instance.
+     */
+    constructor({ appConfig, runtimeOrigin }: {
+        appConfig: EcoPagesAppConfig;
+        runtimeOrigin: string;
+    });
+    /**
+     * Returns a route renderer for the supplied route file.
+     */
+    createRenderer(filePath: string): RouteRenderer;
+    /**
+     * Get an integration renderer by its name.
+     * Used for explicit routing where views specify their integration via __eco.integration.
+     */
+    getRendererByIntegration(integrationName: string): IntegrationRenderer | null;
+    /**
+     * Resolves the integration plugin that owns a given route file.
+     */
+    getIntegrationPlugin(filePath: string): IntegrationPlugin;
+    /**
+     * Returns the cached renderer engine for the file's owning integration,
+     * creating it on first use.
+     */
+    private getRouteRendererEngine;
+}

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

@@ -0,0 +1,87 @@
+import { invariant } from "../utils/invariant.js";
+import { PathUtils } from "../utils/path-utils.module.js";
+class RouteRenderer {
+  renderer;
+  /**
+   * Creates a route renderer bound to one integration renderer instance.
+   */
+  constructor(renderer) {
+    this.renderer = renderer;
+  }
+  /**
+   * Executes the render pipeline for one matched route.
+   */
+  async createRoute(options) {
+    return this.renderer.execute(options);
+  }
+}
+class RouteRendererFactory {
+  appConfig;
+  runtimeOrigin;
+  rendererCache = /* @__PURE__ */ new Map();
+  /**
+   * Creates the route-renderer factory for one app/runtime instance.
+   */
+  constructor({ appConfig, runtimeOrigin }) {
+    this.appConfig = appConfig;
+    this.runtimeOrigin = runtimeOrigin;
+  }
+  /**
+   * Returns a route renderer for the supplied route file.
+   */
+  createRenderer(filePath) {
+    const integrationRenderer = this.getRouteRendererEngine(filePath);
+    invariant(!!integrationRenderer, `No integration renderer found for file: ${filePath}`);
+    return new RouteRenderer(integrationRenderer);
+  }
+  /**
+   * Get an integration renderer by its name.
+   * Used for explicit routing where views specify their integration via __eco.integration.
+   */
+  getRendererByIntegration(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();
+    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();
+    this.rendererCache.set(integrationPlugin.name, renderer);
+    return renderer;
+  }
+}
+export {
+  RouteRenderer,
+  RouteRendererFactory
+};

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

@@ -0,0 +1,34 @@
+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;
+    }
+  }
+  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 recoverPendingNavigationHref(intent, hasInFlightNavigation, now, maxAgeMs = 1e3) {
+  if (!intent || !hasInFlightNavigation) {
+    return null;
+  }
+  if (now - intent.timestamp > maxAgeMs) {
+    return null;
+  }
+  return intent.href;
+}
+export {
+  getAnchorFromNavigationEvent,
+  recoverPendingNavigationHref
+};

package/src/router/client/link-intent.test.browser.d.ts

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

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { getAnchorFromNavigationEvent, recoverPendingNavigationHref } from "./link-intent.js";
+describe("getAnchorFromNavigationEvent", () => {
+  it("returns the anchor when the event target is a text node inside it", () => {
+    const anchor = document.createElement("a");
+    anchor.href = "/fast";
+    anchor.setAttribute("data-eco-link", "true");
+    const textNode = document.createTextNode("fast-link");
+    anchor.append(textNode);
+    document.body.append(anchor);
+    const event = new MouseEvent("click", { bubbles: true, cancelable: true, composed: true });
+    Object.defineProperty(event, "target", {
+      configurable: true,
+      value: textNode
+    });
+    expect(getAnchorFromNavigationEvent(event, "a[data-eco-link]")).toBe(anchor);
+  });
+  it("returns the closest matching anchor for nested element targets", () => {
+    const anchor = document.createElement("a");
+    anchor.href = "/fast";
+    anchor.setAttribute("data-eco-link", "true");
+    const span = document.createElement("span");
+    span.textContent = "fast-link";
+    anchor.append(span);
+    document.body.append(anchor);
+    const event = new MouseEvent("click", { bubbles: true, cancelable: true, composed: true });
+    Object.defineProperty(event, "target", {
+      configurable: true,
+      value: span
+    });
+    expect(getAnchorFromNavigationEvent(event, "a[data-eco-link]")).toBe(anchor);
+  });
+});
+describe("recoverPendingNavigationHref", () => {
+  it("returns null for stale or missing pending intent state", () => {
+    expect(recoverPendingNavigationHref(null, true, 10)).toBeNull();
+    expect(recoverPendingNavigationHref({ href: "/fast", timestamp: 0 }, false, 10)).toBeNull();
+    expect(recoverPendingNavigationHref({ href: "/fast", timestamp: 0 }, true, 2e3, 1e3)).toBeNull();
+  });
+  it("returns the captured href while a navigation is still in flight", () => {
+    expect(recoverPendingNavigationHref({ href: "/fast", timestamp: 10 }, true, 20, 1e3)).toBe("/fast");
+  });
+});

package/src/router/client/navigation-coordinator.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared browser-side navigation coordinator.
+ *
+ * This module is the client runtime contract used by browser-router,
+ * react-router, and HMR code to coordinate ownership, cross-runtime handoff,
+ * current-page reloads, and stale-navigation cancellation.
+ *
+ * The coordinator stays framework-agnostic: browser runtimes register their
+ * capabilities here, and the coordinator arbitrates which runtime currently
+ * owns the document and which navigation transaction is still current.
+ *
+ * @module
+ */
+/** Logical owner name for a browser navigation runtime. */
+export type EcoNavigationOwner = 'none' | 'browser-router' | 'react-router' | (string & {});
+/** HTML attribute used to persist the rendered document owner across navigations. */
+export declare const ECO_DOCUMENT_OWNER_ATTRIBUTE = "data-eco-document-owner";
+/** High-level navigation direction understood by browser runtimes. */
+export type EcoNavigationDirection = 'forward' | 'back' | 'replace';
+/** Navigation request sent between browser runtimes. */
+export type EcoNavigationRequest = {
+    href: string;
+    direction?: EcoNavigationDirection;
+    source?: EcoNavigationOwner;
+};
+/** Navigation handoff request that includes a pre-fetched document. */
+export type EcoNavigationHandoffRequest = EcoNavigationRequest & {
+    finalHref?: string;
+    targetOwner: EcoNavigationOwner;
+    document: Document;
+    html?: string;
+    /**
+     * Reports whether the source runtime's original navigation has already been
+     * superseded.
+     *
+     * Target runtimes use this to ignore handoff work that arrives after a newer
+     * navigation has already claimed ownership.
+     */
+    isStaleSourceNavigation?: () => boolean;
+};
+/** Request to reload the current page through the active runtime. */
+export type EcoReloadRequest = {
+    clearCache?: boolean;
+    source?: EcoNavigationOwner;
+};
+/** Snapshot of the coordinator's current runtime ownership state. */
+export type EcoNavigationOwnerState = {
+    owner: EcoNavigationOwner;
+    canHandleSpaNavigation: boolean;
+};
+/**
+ * Coordinator-managed navigation transaction.
+ *
+ * Runtimes use this to determine whether async work has become stale and to
+ * cancel or complete the active navigation sequence.
+ */
+export type EcoNavigationTransaction = {
+    id: number;
+    signal: AbortSignal;
+    isCurrent: () => boolean;
+    cancel: () => void;
+    complete: () => void;
+};
+export type EcoNavigationRuntimeEvent = {
+    type: 'owner-change';
+    owner: EcoNavigationOwner;
+    previousOwner: EcoNavigationOwner;
+    reason: 'set' | 'claim' | 'release' | 'document' | 'unregister';
+} | {
+    type: 'registration-change';
+    owner: EcoNavigationOwner;
+    status: 'registered' | 'unregistered';
+};
+export type EcoNavigationRuntimeListener = (event: EcoNavigationRuntimeEvent) => void;
+export type EcoNavigationRuntimeRegistration = {
+    owner: EcoNavigationOwner;
+    navigate?: (request: EcoNavigationRequest) => Promise<boolean | void>;
+    handoffNavigation?: (request: EcoNavigationHandoffRequest) => Promise<boolean | void>;
+    reloadCurrentPage?: (request?: EcoReloadRequest) => Promise<void>;
+    /**
+     * Releases runtime-owned client state before another runtime commits a new
+     * document.
+     *
+     * This hook intentionally does not run as part of `requestHandoff()`. The
+     * accepting runtime decides when cleanup is safe so cross-runtime handoffs do
+     * not blank the current page before the incoming document is ready.
+     */
+    cleanupBeforeHandoff?: () => void | Promise<void>;
+};
+/** Public browser-side navigation coordinator interface. */
+export interface EcoNavigationRuntime {
+    /** Returns the currently active runtime owner and whether it can handle SPA navigation. */
+    getOwnerState(): EcoNavigationOwnerState;
+    /** Starts a new navigation transaction, invalidating the previously active one. */
+    beginNavigationTransaction(): EcoNavigationTransaction;
+    /** Reports whether a navigation transaction is still in flight. */
+    hasPendingNavigationTransaction(): boolean;
+    /** Cancels the active navigation transaction, if one exists. */
+    cancelCurrentNavigationTransaction(): void;
+    /** Forces the current owner value without checking registrations. */
+    setOwner(owner: EcoNavigationOwner): void;
+    /** Claims ownership for a runtime that is ready to drive SPA navigation. */
+    claimOwnership(owner: EcoNavigationOwner): void;
+    /** Releases ownership when the given runtime no longer controls the document. */
+    releaseOwnership(owner: EcoNavigationOwner): void;
+    /** Resolves document ownership from the rendered owner marker or fallback. */
+    resolveDocumentOwner(doc: Document, fallbackOwner?: EcoNavigationOwner): EcoNavigationOwner;
+    /** Reads and adopts the rendered document owner as the active runtime owner. */
+    adoptDocumentOwner(doc: Document, fallbackOwner?: EcoNavigationOwner): EcoNavigationOwner;
+    /** Returns whether the active owner is some runtime other than the given owner. */
+    isOwnedByAnotherRuntime(owner: EcoNavigationOwner): boolean;
+    /** Subscribes to ownership and registration change events. */
+    subscribe(listener: EcoNavigationRuntimeListener): () => void;
+    /** Registers a runtime implementation with the coordinator. */
+    register(runtime: EcoNavigationRuntimeRegistration): () => void;
+    /** Requests navigation through another eligible registered runtime. */
+    requestNavigation(request: EcoNavigationRequest): Promise<boolean>;
+    /**
+     * Hands a pre-fetched document to the target runtime.
+     *
+     * The coordinator delegates the document but does not clean up the current
+     * owner first. Cleanup timing belongs to the accepting runtime so a stale or
+     * superseded handoff cannot tear down the current page prematurely.
+     */
+    requestHandoff(request: EcoNavigationHandoffRequest): Promise<boolean>;
+    /** Requests the active runtime to reload the current page. */
+    reloadCurrentPage(request?: EcoReloadRequest): Promise<boolean>;
+    /** Runs a target runtime's cleanup hook before handoff. */
+    cleanupOwner(owner: EcoNavigationOwner): Promise<void>;
+    /** Runs cleanup for whichever runtime currently owns the document. */
+    cleanupCurrentOwner(): Promise<void>;
+}
+/**
+ * Reads the explicit browser document owner marker from a rendered HTML document.
+ *
+ * Documents without a marker return `null`, allowing runtimes to fall back to
+ * their local default behavior without scanning hydration scripts.
+ */
+export declare function getEcoDocumentOwner(doc: Document): EcoNavigationOwner | null;
+/**
+ * Returns the singleton browser-side navigation coordinator.
+ *
+ * The coordinator centralizes ownership, handoff, and current-page reload
+ * requests across browser runtimes through one internal protocol.
+ *
+ * @param windowObject - Window-like object that stores the singleton runtime.
+ * @returns The shared browser navigation coordinator.
+ */
+export declare function getEcoNavigationRuntime(windowObject?: Window & typeof globalThis): EcoNavigationRuntime;

package/src/router/client/navigation-coordinator.js

@@ -0,0 +1,215 @@
+const ECO_DOCUMENT_OWNER_ATTRIBUTE = "data-eco-document-owner";
+function getEcoDocumentOwner(doc) {
+  const owner = doc.documentElement.getAttribute(ECO_DOCUMENT_OWNER_ATTRIBUTE);
+  return owner && owner.length > 0 ? owner : null;
+}
+function getCandidateOwners(currentOwner, registrations, excludedOwner) {
+  const owners = [];
+  if (currentOwner !== "none" && currentOwner !== excludedOwner) {
+    owners.push(currentOwner);
+  }
+  for (const owner of registrations.keys()) {
+    if (owner === currentOwner || owner === excludedOwner) {
+      continue;
+    }
+    owners.push(owner);
+  }
+  return owners;
+}
+function createEcoNavigationRuntime(_windowObject) {
+  const registrations = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let owner = "none";
+  let navigationSequence = 0;
+  let navigationAbortController = null;
+  const emit = (event) => {
+    for (const listener of listeners) {
+      listener(event);
+    }
+  };
+  const updateOwner = (nextOwner, reason) => {
+    if (owner === nextOwner) {
+      return;
+    }
+    const previousOwner = owner;
+    owner = nextOwner;
+    emit({
+      type: "owner-change",
+      owner: nextOwner,
+      previousOwner,
+      reason
+    });
+  };
+  const cancelNavigationTransaction = (navigationId, abortController) => {
+    if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
+      return;
+    }
+    navigationSequence += 1;
+    navigationAbortController = null;
+    abortController.abort();
+  };
+  const completeNavigationTransaction = (navigationId, abortController) => {
+    if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
+      return;
+    }
+    navigationAbortController = null;
+  };
+  const runtime = {
+    getOwnerState() {
+      const activeRuntime = registrations.get(owner);
+      return {
+        owner,
+        canHandleSpaNavigation: typeof activeRuntime?.navigate === "function"
+      };
+    },
+    hasPendingNavigationTransaction() {
+      return navigationAbortController !== null;
+    },
+    beginNavigationTransaction() {
+      navigationAbortController?.abort();
+      const abortController = new AbortController();
+      const navigationId = ++navigationSequence;
+      navigationAbortController = abortController;
+      return {
+        id: navigationId,
+        signal: abortController.signal,
+        isCurrent: () => navigationSequence === navigationId && navigationAbortController === abortController,
+        cancel: () => {
+          cancelNavigationTransaction(navigationId, abortController);
+        },
+        complete: () => {
+          completeNavigationTransaction(navigationId, abortController);
+        }
+      };
+    },
+    cancelCurrentNavigationTransaction() {
+      if (!navigationAbortController) {
+        return;
+      }
+      cancelNavigationTransaction(navigationSequence, navigationAbortController);
+    },
+    setOwner(nextOwner) {
+      updateOwner(nextOwner, "set");
+    },
+    claimOwnership(nextOwner) {
+      updateOwner(nextOwner, "claim");
+    },
+    releaseOwnership(currentOwner) {
+      if (owner !== currentOwner) {
+        return;
+      }
+      updateOwner("none", "release");
+    },
+    resolveDocumentOwner(doc, fallbackOwner = "none") {
+      return getEcoDocumentOwner(doc) ?? fallbackOwner;
+    },
+    adoptDocumentOwner(doc, fallbackOwner = "none") {
+      const nextOwner = runtime.resolveDocumentOwner(doc, fallbackOwner);
+      updateOwner(nextOwner, "document");
+      return nextOwner;
+    },
+    isOwnedByAnotherRuntime(candidateOwner) {
+      return owner !== "none" && owner !== candidateOwner;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    register(registration) {
+      registrations.set(registration.owner, registration);
+      emit({
+        type: "registration-change",
+        owner: registration.owner,
+        status: "registered"
+      });
+      return () => {
+        const currentRegistration = registrations.get(registration.owner);
+        if (currentRegistration !== registration) {
+          return;
+        }
+        registrations.delete(registration.owner);
+        emit({
+          type: "registration-change",
+          owner: registration.owner,
+          status: "unregistered"
+        });
+        if (owner === registration.owner) {
+          updateOwner("none", "unregister");
+        }
+      };
+    },
+    async requestNavigation(request) {
+      for (const candidateOwner of getCandidateOwners(owner, registrations, request.source)) {
+        const registration = registrations.get(candidateOwner);
+        if (!registration?.navigate) {
+          continue;
+        }
+        const handled = await registration.navigate(request);
+        if (handled !== false) {
+          return true;
+        }
+      }
+      return false;
+    },
+    async requestHandoff(request) {
+      if (request.targetOwner === "none") {
+        return false;
+      }
+      if (request.isStaleSourceNavigation?.()) {
+        return true;
+      }
+      const registration = registrations.get(request.targetOwner);
+      if (!registration?.handoffNavigation) {
+        return false;
+      }
+      if (request.isStaleSourceNavigation?.()) {
+        return true;
+      }
+      const handled = await registration.handoffNavigation(request);
+      return handled !== false;
+    },
+    async reloadCurrentPage(request) {
+      for (const candidateOwner of getCandidateOwners(owner, registrations)) {
+        const registration = registrations.get(candidateOwner);
+        if (!registration?.reloadCurrentPage) {
+          continue;
+        }
+        await registration.reloadCurrentPage(request);
+        return true;
+      }
+      return false;
+    },
+    async cleanupOwner(targetOwner) {
+      if (targetOwner === "none") {
+        return;
+      }
+      const registration = registrations.get(targetOwner);
+      if (!registration?.cleanupBeforeHandoff) {
+        return;
+      }
+      await registration.cleanupBeforeHandoff();
+      if (owner === targetOwner) {
+        updateOwner("none", "release");
+      }
+    },
+    async cleanupCurrentOwner() {
+      await runtime.cleanupOwner(owner);
+    }
+  };
+  return runtime;
+}
+function getEcoNavigationRuntime(windowObject = window) {
+  const runtimeWindow = windowObject;
+  runtimeWindow.__ECO_PAGES__ = runtimeWindow.__ECO_PAGES__ || {};
+  if (!runtimeWindow.__ECO_PAGES__.navigation) {
+    runtimeWindow.__ECO_PAGES__.navigation = createEcoNavigationRuntime(runtimeWindow);
+  }
+  return runtimeWindow.__ECO_PAGES__.navigation;
+}
+export {
+  ECO_DOCUMENT_OWNER_ATTRIBUTE,
+  getEcoDocumentOwner,
+  getEcoNavigationRuntime
+};

package/src/router/server/fs-router-scanner.d.ts

@@ -0,0 +1,41 @@
+import type { EcoPagesAppConfig, Routes } from '../../internal-types.js';
+type FSRouterScannerOptions = {
+    buildMode: boolean;
+};
+/**
+ * @class FSRouterScanner
+ * @description
+ * This class is responsible for scanning the file system for routes.
+ * It uses the glob package to scan the file system for files with the specified file extensions.
+ * It then creates a map of the routes with the pathname as the key.
+ * The pathname is the route without the file extension.
+ * For example, if the file is "index.tsx", the pathname will be "/index".
+ * If the file is "blog/[slug].tsx", the pathname will be "/blog/[slug]".
+ * If the file is "blog/[...slug].tsx", the pathname will be "/blog/[...slug]".
+ */
+export declare class FSRouterScanner {
+    private dir;
+    private origin;
+    private templatesExt;
+    private options;
+    readonly appConfig: EcoPagesAppConfig;
+    routes: Routes;
+    private serverModuleTranspiler;
+    constructor({ dir, origin, templatesExt, options, appConfig, }: {
+        dir: string;
+        origin: string;
+        templatesExt: string[];
+        options: FSRouterScannerOptions;
+        appConfig: EcoPagesAppConfig;
+    });
+    private getRoutePath;
+    private getDynamicParamsNames;
+    private getStaticPathsFromDynamicRoute;
+    private createStaticRoutes;
+    private handleDynamicRouteCreation;
+    private importPageModule;
+    private createRoute;
+    private getRouteData;
+    scan(): Promise<Routes>;
+}
+export {};