@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/route-renderer/page-loading/page-dependency-bundling.js

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync } from "node:fs";
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { rapidhash } from "../../utils/hash.js";
+function hasOnlyExpectedAttributes(attributes, expected) {
+  const keys = Object.keys(attributes ?? {});
+  const expectedKeys = Object.keys(expected);
+  if (keys.length !== expectedKeys.length) {
+    return false;
+  }
+  return expectedKeys.every((key) => attributes?.[key] === expected[key]);
+}
+function isSafeBundledStylesheetReference(reference) {
+  return reference.startsWith("/") || reference.startsWith("data:") || reference.startsWith("http://") || reference.startsWith("https://") || reference.startsWith("#");
+}
+function normalizeCssReferenceToken(token) {
+  return token.trim().replace(/^['"]|['"]$/g, "");
+}
+function isSafeBundledStylesheetContent(content) {
+  for (const match of content.matchAll(/@import\s+(?:url\()?['"]?([^'")\s]+)['"]?\)?/g)) {
+    const reference = normalizeCssReferenceToken(match[1] ?? "");
+    if (reference && !isSafeBundledStylesheetReference(reference)) {
+      return false;
+    }
+  }
+  for (const match of content.matchAll(/url\(([^)]+)\)/g)) {
+    const reference = normalizeCssReferenceToken(match[1] ?? "");
+    if (reference && !isSafeBundledStylesheetReference(reference)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isBundleableFileStylesheetAsset(dependency) {
+  return dependency.kind === "stylesheet" && dependency.source === "file";
+}
+function isBundleableFileScriptAsset(dependency) {
+  return dependency.kind === "script" && dependency.source === "file";
+}
+function shouldBundlePageDependencies(integrationName) {
+  return integrationName === "react" || integrationName === "ecopages-jsx";
+}
+function createPageDependencyPackagingPlan(dependencies, integrationName) {
+  const shouldBundleDependencies = process.env.NODE_ENV === "production";
+  const bundleableStyles = dependencies.filter((dependency) => {
+    if (!shouldBundleDependencies) {
+      return false;
+    }
+    if (dependency.kind !== "stylesheet" || dependency.inline || dependency.position === "body") {
+      return false;
+    }
+    if (dependency.packageRole || !hasOnlyExpectedAttributes(dependency.attributes, { rel: "stylesheet" })) {
+      return false;
+    }
+    if (dependency.source === "content") {
+      return isSafeBundledStylesheetContent(dependency.content);
+    }
+    if (!existsSync(dependency.filepath)) {
+      return false;
+    }
+    return isSafeBundledStylesheetContent(readFileSync(dependency.filepath, "utf8"));
+  }).filter(isBundleableFileStylesheetAsset);
+  const bundleableScripts = dependencies.filter((dependency) => {
+    if (!shouldBundleDependencies) {
+      return false;
+    }
+    return dependency.kind === "script" && dependency.source === "file" && !dependency.inline && !dependency.excludeFromHtml && dependency.position !== "body" && !dependency.packageRole && dependency.bundle !== false && hasOnlyExpectedAttributes(dependency.attributes, { type: "module", defer: "" }) && existsSync(dependency.filepath);
+  }).filter(isBundleableFileScriptAsset);
+  const bundledStylesheet = bundleableStyles.length > 1 ? AssetFactory.createContentStylesheet({
+    content: bundleableStyles.map((dependency) => readFileSync(dependency.filepath, "utf8")).join("\n"),
+    position: "head",
+    attributes: { rel: "stylesheet" },
+    packageRole: "page-style",
+    bundledSourceFilepaths: bundleableStyles.map((dependency) => dependency.filepath)
+  }) : void 0;
+  const pageScriptImports = [...new Set(bundleableScripts.map((dependency) => dependency.filepath))];
+  const shouldBundlePageScript = pageScriptImports.length > 0 && bundleableScripts.length > 1;
+  const bundledScript = shouldBundlePageScript ? AssetFactory.createContentScript({
+    name: `${integrationName}-page-${rapidhash(pageScriptImports.join("|")).toString(16)}`,
+    content: pageScriptImports.map((filepath) => `import ${JSON.stringify(filepath)};`).join("\n"),
+    position: "head",
+    attributes: { type: "module", defer: "" },
+    packageRole: "page-script",
+    bundledSourceFilepaths: pageScriptImports
+  }) : void 0;
+  if (!bundledStylesheet && !bundledScript) {
+    return void 0;
+  }
+  return {
+    bundledStylesheet,
+    bundledScript,
+    bundleableStyleFilepaths: new Set(bundleableStyles.map((dependency) => dependency.filepath)),
+    bundleableScriptFilepaths: new Set(pageScriptImports)
+  };
+}
+function applyPageDependencyPackagingPlan(dependencies, plan) {
+  const unifiedDependencies = [];
+  let insertedStylesheet = false;
+  let insertedScript = false;
+  for (const dependency of dependencies) {
+    if (plan.bundledStylesheet && dependency.kind === "stylesheet" && dependency.source === "file" && plan.bundleableStyleFilepaths.has(dependency.filepath)) {
+      if (!insertedStylesheet) {
+        unifiedDependencies.push(plan.bundledStylesheet);
+        insertedStylesheet = true;
+      }
+      continue;
+    }
+    if (plan.bundledScript && dependency.kind === "script" && dependency.source === "file" && plan.bundleableScriptFilepaths.has(dependency.filepath)) {
+      if (!insertedScript) {
+        unifiedDependencies.push(plan.bundledScript);
+        insertedScript = true;
+      }
+      continue;
+    }
+    unifiedDependencies.push(dependency);
+  }
+  if (plan.bundledScript && !insertedScript) {
+    unifiedDependencies.push(plan.bundledScript);
+  }
+  if (plan.bundledStylesheet && !insertedStylesheet) {
+    unifiedDependencies.push(plan.bundledStylesheet);
+  }
+  return unifiedDependencies;
+}
+function packagePageDependencies(dependencies, integrationName) {
+  if (!shouldBundlePageDependencies(integrationName)) {
+    return dependencies;
+  }
+  const plan = createPageDependencyPackagingPlan(dependencies, integrationName);
+  if (!plan) {
+    return dependencies;
+  }
+  return applyPageDependencyPackagingPlan(dependencies, plan);
+}
+export {
+  packagePageDependencies,
+  shouldBundlePageDependencies
+};

package/src/route-renderer/page-loading/page-module-loader.d.ts

@@ -0,0 +1,90 @@
+import type { EcoPageFile, GetMetadata, GetMetadataContext, GetStaticProps, PageMetadataProps, RouteRendererOptions, EcoPageComponent } from '../../types/public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.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 declare class PageModuleLoaderService {
+    private appModuleLoader;
+    private appConfig;
+    private 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: EcoPagesAppConfig, runtimeOrigin: string);
+    /**
+     * 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.
+     */
+    importPageFile(file: string, options?: {
+        bypassCache?: boolean;
+        cacheScope?: string;
+    }): Promise<EcoPageFile>;
+    /**
+     * 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.
+     */
+    getStaticPropsForPage(options: {
+        getStaticProps?: GetStaticProps<Record<string, unknown>>;
+        params?: RouteRendererOptions['params'];
+    }): Promise<{
+        props: Record<string, unknown>;
+        metadata?: PageMetadataProps;
+    }>;
+    /**
+     * 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.
+     */
+    getMetadataPropsForPage(options: {
+        getMetadata: GetMetadata | undefined;
+        context: GetMetadataContext;
+    }): Promise<PageMetadataProps>;
+    /**
+     * Loads a page module and normalizes integration-facing exports.
+     * When both component static methods and module exports exist, component statics win.
+     */
+    resolvePageModule(options: {
+        file: string;
+        importPageFileFn?: (file: string) => Promise<EcoPageFile>;
+    }): Promise<{
+        Page: EcoPageFile['default'] | EcoPageComponent<any>;
+        getStaticProps?: GetStaticProps<Record<string, unknown>>;
+        getMetadata?: GetMetadata;
+        integrationSpecificProps: Record<string, unknown>;
+    }>;
+    /**
+     * 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.
+     */
+    resolvePageData(options: {
+        pageModule: {
+            getStaticProps?: GetStaticProps<Record<string, unknown>>;
+            getMetadata?: GetMetadata;
+        };
+        routeOptions: RouteRendererOptions;
+    }): Promise<{
+        props: Record<string, unknown>;
+        metadata: PageMetadataProps;
+    }>;
+}

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

@@ -1,22 +1,36 @@
-import { invariant } from "../utils/invariant.js";
-import { PageModuleImportService } from "../services/page-module-import.service.js";
+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.pageModuleImportService = new PageModuleImportService();
+    this.appModuleLoader = getAppModuleLoader(appConfig);
   }
-  pageModuleImportService;
   /**
-   * Imports a page module from source.
-   * Uses direct dynamic import in Bun and transpile+import fallback for other runtimes.
+   * 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) {
+  async importPageFile(file, options) {
     try {
-      return await this.pageModuleImportService.importModule({
+      return await this.appModuleLoader.importModule({
         filePath: file,
         rootDir: this.appConfig.rootDir,
-        outdir: `${this.appConfig.absolutePaths.distDir}/.server-modules`,
+        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}`
       });
@@ -25,8 +39,11 @@ class PageModuleLoaderService {
     }
   }
   /**
-   * Executes `getStaticProps` with Ecopages runtime context.
-   * Returns an empty props object when no static props function is defined.
+   * 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;
@@ -42,8 +59,11 @@ class PageModuleLoaderService {
     };
   }
   /**
-   * Builds final page metadata using app-level defaults as a baseline.
-   * If `getMetadata` exists, its result overlays defaults so page-level fields take precedence.
+   * 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;
@@ -79,7 +99,12 @@ class PageModuleLoaderService {
     };
   }
   /**
-   * Resolves render-time page data in order: static props first, then metadata derived from those props.
+   * 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({

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

@@ -1,26 +1,69 @@
-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 './integration-renderer.js';
-export declare class RouteRenderer {
-    private renderer;
-    constructor(renderer: IntegrationRenderer);
-    createRoute(options: RouteRendererOptions): Promise<RouteRenderResult>;
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { IntegrationRenderer } from './orchestration/integration-renderer.js';
+/**
+ * Narrow route-render contract exposed to higher-level routing code.
+ *
+ * @remarks
+ * Higher-level routing code only needs request execution and page-module
+ * loading. Returning this narrowed shape avoids a dedicated wrapper class while
+ * still keeping callers off the full integration renderer surface.
+ */
+export type PageRouteRenderer = Pick<IntegrationRenderer<unknown>, 'execute' | 'loadPageModule'>;
+/**
+ * Narrow explicit-view render contract exposed to static route handling.
+ *
+ * @remarks
+ * Explicit static routes only need `renderToResponse()`, so the factory can
+ * hide the broader integration renderer surface there as well.
+ */
+export type ExplicitViewRenderer = Pick<IntegrationRenderer<unknown>, 'renderToResponse'>;
+export interface PageRendererResolver {
+    getPageRenderer(filePath: string): PageRouteRenderer;
 }
+export interface ExplicitViewRendererResolver {
+    getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null;
+}
+/**
+ * Combined renderer-factory contract used by static generation.
+ */
+export type StaticGenerationRendererResolver = PageRendererResolver & ExplicitViewRendererResolver;
+/**
+ * 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 rendererModules?;
     private rendererCache;
-    constructor({ appConfig, runtimeOrigin }: {
+    /**
+     * Creates the route-renderer factory for one app/runtime instance.
+     */
+    constructor({ appConfig, rendererModules, runtimeOrigin, }: {
         appConfig: EcoPagesAppConfig;
+        rendererModules?: unknown;
         runtimeOrigin: string;
     });
-    createRenderer(filePath: string): RouteRenderer;
     /**
-     * Get an integration renderer by its name.
-     * Used for explicit routing where views specify their integration via __eco.integration.
+     * Returns a route renderer for the supplied route file.
+     */
+    getPageRenderer(filePath: string): PageRouteRenderer;
+    /**
+     * Returns a renderer for an explicit view integration.
+     */
+    getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null;
+    /**
+     * Resolves the integration plugin that owns a given route file.
+     */
+    getIntegrationPlugin(filePath: string): AnyIntegrationPlugin;
+    /**
+     * Returns the cached renderer engine for the file's owning integration,
+     * creating it on first use.
      */
-    getRendererByIntegration(integrationName: string): IntegrationRenderer | null;
-    getIntegrationPlugin(filePath: string): IntegrationPlugin;
     private getRouteRendererEngine;
 }

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

@@ -1,32 +1,34 @@
 import { invariant } from "../utils/invariant.js";
 import { PathUtils } from "../utils/path-utils.module.js";
-class RouteRenderer {
-  renderer;
-  constructor(renderer) {
-    this.renderer = renderer;
-  }
-  async createRoute(options) {
-    return this.renderer.execute(options);
-  }
-}
 class RouteRendererFactory {
   appConfig;
   runtimeOrigin;
+  rendererModules;
   rendererCache = /* @__PURE__ */ new Map();
-  constructor({ appConfig, runtimeOrigin }) {
+  /**
+   * Creates the route-renderer factory for one app/runtime instance.
+   */
+  constructor({
+    appConfig,
+    rendererModules,
+    runtimeOrigin
+  }) {
     this.appConfig = appConfig;
+    this.rendererModules = rendererModules;
     this.runtimeOrigin = runtimeOrigin;
   }
-  createRenderer(filePath) {
+  /**
+   * 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 new RouteRenderer(integrationRenderer);
+    return integrationRenderer;
   }
   /**
-   * Get an integration renderer by its name.
-   * Used for explicit routing where views specify their integration via __eco.integration.
+   * Returns a renderer for an explicit view integration.
    */
-  getRendererByIntegration(integrationName) {
+  getExplicitViewRenderer(integrationName) {
     const integrationPlugin = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
     if (!integrationPlugin) {
       return null;
@@ -35,10 +37,15 @@ class RouteRendererFactory {
     if (cached) {
       return cached;
     }
-    const renderer = integrationPlugin.initializeRenderer();
+    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) => {
@@ -51,18 +58,23 @@ class RouteRendererFactory {
     );
     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();
+    const renderer = integrationPlugin.initializeRenderer({
+      rendererModules: this.rendererModules
+    });
     this.rendererCache.set(integrationPlugin.name, renderer);
     return renderer;
   }
 }
 export {
-  RouteRenderer,
   RouteRendererFactory
 };

package/src/router/README.md

@@ -0,0 +1,94 @@
+# Router Layer
+
+This directory contains route discovery, matching, and browser-side navigation infrastructure.
+
+## Purpose
+
+The router layer determines what route is being handled and how the client runtime coordinates navigation.
+
+It is responsible for:
+
+- filesystem route discovery and classification (`exact`, `dynamic`, `catch-all`)
+- matching incoming request URLs to canonical template routes
+- server-side static-path expansion for dynamic template routes
+- client-side navigation ownership and cross-runtime handoff
+- keeping route discovery separate from rendering execution
+
+## Directory Structure
+
+```
+router/
+├── server/                      # Server-side route discovery and matching
+│   └── route-registry.ts        # Owns template routes, request matching, static expansion, and reload
+└── client/                      # Browser-side navigation coordination
+    ├── navigation-coordinator.ts # Singleton runtime coordinator
+    └── link-intent.ts           # Shared anchor detection and intent recovery helpers
+```
+
+## `server/`
+
+### `RouteRegistry`
+
+Owns the canonical set of filesystem-discovered template routes for one application.
+
+File patterns determine route kind:
+
+| Pattern         | Kind        | Example           |
+| --------------- | ----------- | ----------------- |
+| `page.tsx`      | `exact`     | `/about`          |
+| `[slug].tsx`    | `dynamic`   | `/blog/[slug]`    |
+| `[...slug].tsx` | `catch-all` | `/docs/[...slug]` |
+
+The registry stores canonical template routes only. It compiles request-time matching metadata during `init()` and `reload()`, but it does not execute `staticPaths()` during discovery.
+
+Build-time static expansion is a separate operation. The registry invokes `staticPaths()` lazily through an injected page-module adapter and returns concrete static path expansions for the static generator.
+
+The public interface is intentionally small:
+
+- `templateRoutes` — ordered readonly template routes
+- `init()` / `reload()` — rebuild discovery state and match metadata
+- `matchRequest(requestUrl)` — request-time matching result with requested pathname, matched template route, params, and query
+- `listStaticPathExpansions()` — build-time expansion for dynamic routes
+- `listStaticGenerationRoutes()` — build-time route planning for static generation across exact and expanded routes
+
+Match priority:
+
+1. `exact` — the pathname must equal the route pathname exactly.
+2. `dynamic` — the clean (bracket-stripped) prefix must appear in the pathname, and the segment counts must match.
+3. `catch-all` — the clean prefix must appear in the pathname.
+
+## `client/`
+
+### Navigation Coordinator (`navigation-coordinator.ts`)
+
+A singleton browser-side runtime stored on `window.__ECO_PAGES__.navigation`.
+
+Access it with:
+
+```ts
+import { getEcoNavigationRuntime } from '@ecopages/core/router/navigation-coordinator';
+const runtime = getEcoNavigationRuntime();
+```
+
+The coordinator is framework-agnostic. Browser runtimes (e.g. `browser-router`, `react-router`) register themselves and the coordinator arbitrates:
+
+- **Ownership** — which runtime currently drives SPA navigation (`claimOwnership`, `releaseOwnership`, `setOwner`).
+- **Document owner marker** — an HTML attribute (`data-eco-document-owner`) written into rendered markup so the coordinator can `adoptDocumentOwner` on the incoming page.
+- **Navigation transactions** — each navigation begins a transaction with an `AbortSignal`; superseded navigations are automatically cancelled.
+- **Cross-runtime handoff** — `requestHandoff` passes a pre-fetched `Document` to the target runtime without tearing down the current page prematurely.
+- **Reload** — `reloadCurrentPage` delegates to whichever runtime currently owns the document.
+- **Events** — `subscribe` lets runtimes react to `owner-change` and `registration-change` events.
+
+### Link Intent (`link-intent.ts`)
+
+Shared helpers for locating anchors and recovering stale navigation intent.
+
+- `getAnchorFromNavigationEvent(event, linkSelector)` — finds the nearest matching anchor in the event's composed path, including across Shadow DOM boundaries.
+- `recoverPendingNavigationHref(intent, hasInFlightNavigation, now, maxAgeMs?)` — resolves a previously captured pointer or hover target when the DOM changes before the click lands. Intents expire after `maxAgeMs` (default 1000 ms).
+
+## Relationship To Rendering
+
+The router layer answers **which route should run**.
+The route-renderer layer answers **how that route gets rendered**.
+
+Keeping those seams separate avoids mixing route ownership, module loading, and component orchestration into one service.

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

@@ -0,0 +1,53 @@
+/**
+ * Shared client-side navigation intent helpers.
+ *
+ * Browser runtimes use the same low-level mechanics to:
+ * - locate the anchor associated with a click, pointer, or hover event,
+ * - persist the last valid pointer or hover target while a navigation is in flight,
+ * - recover the final intended href when the DOM changes before the click lands.
+ *
+ * Keeping those mechanics here lets browser-router and react-router share one
+ * implementation while preserving their router-specific interception rules.
+ *
+ * @module
+ */
+/**
+ * Timestamped navigation intent captured from pointer or hover activity.
+ */
+export type EcoPendingNavigationIntent = {
+	href: string;
+	timestamp: number;
+};
+/**
+ * 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 declare function getAnchorFromNavigationEvent(
+	event: MouseEvent | PointerEvent,
+	linkSelector: string,
+): HTMLAnchorElement | null;
+/**
+ * Resolves a previously captured intent while a navigation is still in flight.
+ *
+ * Pending intents expire quickly because they are only meant to bridge the gap
+ * between pointer or hover capture and the later click event when the DOM or
+ * active runtime changes during a rapid navigation sequence.
+ *
+ * @param intent - Previously captured pointer or hover intent.
+ * @param hasInFlightNavigation - Whether a router navigation is still active.
+ * @param now - Current monotonic timestamp, usually from `performance.now()`.
+ * @param maxAgeMs - Maximum allowed age for the recovered intent.
+ * @returns The intended href when still valid, otherwise `null`.
+ */
+export declare function recoverPendingNavigationHref(
+	intent: EcoPendingNavigationIntent | null,
+	hasInFlightNavigation: boolean,
+	now: number,
+	maxAgeMs?: number,
+): string | null;

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 {};