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

package/src/route-renderer/orchestration/route-pipeline/route-render-orchestrator.js

@@ -0,0 +1,162 @@
+import { inspectUnresolvedMarkerArtifactHtml } from "./marker-artifact.utils.js";
+import {
+  OwnershipValidationService,
+  throwIfOwnershipInvalid
+} from "../ownership-graph/ownership-validation.service.js";
+import {
+  buildEagerSsrLazyAssetsFromGraph,
+  collectResolvedLazyTriggersFromGraph,
+  collectUsedIntegrationDependenciesFromGraph
+} from "../ownership-graph/component-graph-collectors.js";
+import { buildGlobalInjectorAssets } from "../page-browser-graph/global-injector-assets.service.js";
+import { PageBrowserGraphService } from "../page-browser-graph/page-browser-graph.service.js";
+import { buildPreparedRenderOptions } from "./route-prepared-options.builder.js";
+class RouteRenderOrchestrator {
+  appConfig;
+  assetProcessingService;
+  ownershipValidationService;
+  pageBrowserGraphService;
+  constructor(appConfig, assetProcessingService, dependencies = {}) {
+    this.appConfig = appConfig;
+    this.assetProcessingService = assetProcessingService;
+    this.ownershipValidationService = dependencies.ownershipValidationService ?? new OwnershipValidationService(appConfig);
+    this.pageBrowserGraphService = dependencies.pageBrowserGraphService ?? new PageBrowserGraphService(appConfig, assetProcessingService);
+  }
+  /**
+   * Builds normalized route render options before the integration render runs.
+   *
+   * This preparation step validates route-root ownership, resolves page data,
+   * collects processed assets, and produces the page package consumed by downstream
+   * HTML transformation.
+   */
+  async prepareRenderOptions(routeOptions, adapter) {
+    const resolvedInputs = await adapter.resolveRouteRenderInputs(routeOptions);
+    const { Page, HtmlTemplate, Layouts } = resolvedInputs;
+    const validationErrors = this.ownershipValidationService.validate({
+      currentIntegrationName: adapter.name,
+      roots: [
+        { component: HtmlTemplate, source: "html-template" },
+        ...Layouts.map((layout) => ({ component: layout, source: "layout" })),
+        { component: Page, source: "page" }
+      ]
+    });
+    throwIfOwnershipInvalid(validationErrors);
+    const componentsToResolve = [HtmlTemplate, ...Layouts, Page];
+    const [{ resolvedDependencies }, pageBrowserGraph] = await Promise.all([
+      adapter.resolveRouteDependencies({
+        components: componentsToResolve
+      }),
+      this.pageBrowserGraphService.resolvePageBrowserGraph({
+        routeFile: routeOptions.file,
+        integrationName: adapter.name,
+        collectContribution: async (routeFile) => await adapter.collectPageBrowserGraphContribution(routeFile)
+      })
+    ]);
+    const allDependencies = [
+      ...resolvedDependencies,
+      ...collectUsedIntegrationDependenciesFromGraph(this.appConfig, componentsToResolve, adapter.name)
+    ];
+    const triggers = collectResolvedLazyTriggersFromGraph(componentsToResolve, adapter.name);
+    const [globalAssets, eagerSsrLazyAssets] = await Promise.all([
+      triggers.length > 0 ? buildGlobalInjectorAssets(this.appConfig, this.assetProcessingService, triggers, adapter.name) : Promise.resolve([]),
+      buildEagerSsrLazyAssetsFromGraph(this.assetProcessingService, componentsToResolve, adapter.name)
+    ]);
+    allDependencies.push(...globalAssets, ...eagerSsrLazyAssets);
+    return buildPreparedRenderOptions({
+      routeOptions,
+      resolvedInputs,
+      resolvedDependencies,
+      allDependencies,
+      pageBrowserGraph,
+      appConfig: this.appConfig
+    });
+  }
+  async resolveDeclaredPageBrowserGraph(input) {
+    return await this.pageBrowserGraphService.resolvePageBrowserGraph(input);
+  }
+  /**
+   * Captures one route render body as HTML while preserving a replayable body value.
+   */
+  async captureHtmlRender(render) {
+    const renderedBody = await render();
+    const capturedRender = await this.captureRenderedBody(renderedBody);
+    return {
+      body: capturedRender.body,
+      html: capturedRender.html
+    };
+  }
+  /**
+   * Executes the full route-render flow and returns the final body plus cache strategy.
+   */
+  async execute(options, adapter) {
+    const renderOptions = await this.prepareRenderOptions(options, adapter);
+    return this.executePrepared(renderOptions, adapter);
+  }
+  /**
+   * Executes the route-render finalization path for already prepared render options.
+   */
+  async executePrepared(renderOptions, adapter) {
+    const renderExecution = await this.captureHtmlRender(async () => adapter.renderRouteBody(renderOptions));
+    const unresolvedArtifactInspection = inspectUnresolvedMarkerArtifactHtml(renderExecution.html);
+    const htmlFinalization = adapter.getRouteHtmlFinalization(renderOptions);
+    const hasUnresolvedMarkerHtml = unresolvedArtifactInspection.hasUnresolvedMarkerArtifacts;
+    if (hasUnresolvedMarkerHtml) {
+      throw new Error(
+        "[ecopages] Route render returned unresolved eco-marker artifact HTML. Full-route unresolved-marker fallback has been removed; resolve mixed foreign children inside renderComponentWithForeignChildren()."
+      );
+    }
+    const canReuseCapturedBody = !hasUnresolvedMarkerHtml && htmlFinalization.finalizeHtml === void 0;
+    if (canReuseCapturedBody) {
+      const body2 = await adapter.transformRouteResponse(
+        new Response(renderExecution.body, {
+          headers: {
+            "Content-Type": "text/html"
+          }
+        }),
+        htmlFinalization.htmlContributions,
+        renderOptions.pagePackage
+      );
+      return {
+        body: body2,
+        cacheStrategy: renderOptions.cacheStrategy
+      };
+    }
+    const finalization = htmlFinalization.finalizeHtml ? htmlFinalization.finalizeHtml(unresolvedArtifactInspection.normalizedHtml) : unresolvedArtifactInspection.normalizedHtml;
+    const body = await adapter.transformRouteResponse(
+      new Response(finalization, {
+        headers: {
+          "Content-Type": "text/html"
+        }
+      }),
+      htmlFinalization.htmlContributions,
+      renderOptions.pagePackage
+    );
+    return {
+      body,
+      cacheStrategy: renderOptions.cacheStrategy
+    };
+  }
+  async captureRenderedBody(body) {
+    const response = new Response(body);
+    if (typeof body === "string") {
+      return {
+        body,
+        html: await response.text()
+      };
+    }
+    if (!response.body) {
+      return {
+        body,
+        html: await response.text()
+      };
+    }
+    const [capturedBody, replayBody] = response.body.tee();
+    return {
+      body: replayBody,
+      html: await new Response(capturedBody).text()
+    };
+  }
+}
+export {
+  RouteRenderOrchestrator
+};

package/src/route-renderer/orchestration/string-markup-renderer.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.js';
+import { IntegrationRenderer, type RenderToResponseContext } from './integration-renderer.js';
+/**
+ * Base renderer for integrations whose page output is string HTML markup.
+ *
+ * @remarks
+ * Ghtml, KitaJS, and MDX share the same document-shell rendering path. Subclasses
+ * only need to set `name` and override hooks for integration-specific behavior.
+ */
+export declare abstract class StringMarkupRenderer extends IntegrationRenderer<EcoPagesElement> {
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
+    renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
+}

package/src/route-renderer/orchestration/string-markup-renderer.js

@@ -0,0 +1,55 @@
+import { IntegrationRenderer } from "./integration-renderer.js";
+import { resolveInnermostPageLayout } from "./document-shell/layout-shell-props.service.js";
+class StringMarkupRenderer extends IntegrationRenderer {
+  async renderComponent(input) {
+    if (typeof input.component !== "function") {
+      throw new TypeError(`${this.name} renderer expected a callable component.`);
+    }
+    return this.renderStringComponentWithQueuedForeignSubtrees(input, input.component);
+  }
+  async render({
+    params,
+    query,
+    props,
+    locals,
+    pageLocals,
+    metadata,
+    Page,
+    Layout,
+    HtmlTemplate,
+    pageProps
+  }) {
+    try {
+      return await this.renderPageWithDocumentShell({
+        page: {
+          component: Page,
+          props: { params, query, ...props, locals: pageLocals }
+        },
+        layout: Layout ? {
+          component: Layout,
+          props: locals ? { locals } : {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
+        metadata,
+        pageProps: pageProps ?? props ?? {}
+      });
+    } catch (error) {
+      throw this.createRenderError("Error rendering page", error);
+    }
+  }
+  async renderToResponse(view, props, ctx) {
+    try {
+      return await this.renderViewWithDocumentShell({
+        view,
+        props,
+        ctx,
+        layout: resolveInnermostPageLayout(view.config?.layouts)
+      });
+    } catch (error) {
+      throw this.createRenderError("Error rendering view", error);
+    }
+  }
+}
+export {
+  StringMarkupRenderer
+};

package/src/route-renderer/page-loading/component-dependency-collection.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { assertEcoDeclaredComponent } from "../../eco/eco-declared-component.js";
 import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
 import { extractEcopagesVirtualImports } from "./ecopages-virtual-imports.js";
 import { collectDeclaredAssetEntries } from "./declared-asset-collection.js";
@@ -103,9 +104,11 @@ function collectComponentDependencies(options) {
       });
       if (dependenciesConfig?.components) {
         for (const nestedComponent of dependenciesConfig.components) {
-          if (nestedComponent?.config) {
-            collect(nestedComponent.config);
+          if (!nestedComponent) {
+            continue;
           }
+          assertEcoDeclaredComponent(nestedComponent, { parentComponentFile: file });
+          collect(nestedComponent.config);
         }
       }
     };

package/src/route-renderer/page-loading/ecopages-virtual-imports.d.ts

@@ -2,6 +2,12 @@ export type EcopagesVirtualImport = {
     from: string;
     imports: string[] | undefined;
 };
+/**
+ * @remarks
+ * Content server modules static-import every MDX entry. They must never become
+ * browser module-script dependencies discovered from page or component sources.
+ */
+export declare function isBrowserEcopagesVirtualImport(specifier: string): boolean;
 /**
  * Extracts runtime `ecopages:` virtual-module imports from a component source file.
  *

package/src/route-renderer/page-loading/ecopages-virtual-imports.js

@@ -1,5 +1,9 @@
 import { readFileSync } from "node:fs";
 import { parseSync } from "oxc-parser";
+const CONTENT_SERVER_VIRTUAL_MODULE_PATTERN = /^ecopages:content\/[a-z][a-z0-9-]+\/server$/;
+function isBrowserEcopagesVirtualImport(specifier) {
+  return specifier.startsWith("ecopages:") && !CONTENT_SERVER_VIRTUAL_MODULE_PATTERN.test(specifier);
+}
 function extractEcopagesVirtualImports(file) {
   let source;
   try {
@@ -18,7 +22,7 @@ function extractEcopagesVirtualImports(file) {
     if (node.type !== "ImportDeclaration") continue;
     if (node.importKind === "type") continue;
     const specifier = node.source?.value ?? "";
-    if (!specifier.startsWith("ecopages:")) continue;
+    if (!isBrowserEcopagesVirtualImport(specifier)) continue;
     if (found.get(specifier) === null) {
       continue;
     }
@@ -53,5 +57,6 @@ function extractEcopagesVirtualImports(file) {
   }));
 }
 export {
-  extractEcopagesVirtualImports
+  extractEcopagesVirtualImports,
+  isBrowserEcopagesVirtualImport
 };

package/src/route-renderer/page-loading/module-declaration-aggregation.js

@@ -1,4 +1,5 @@
 import { normalizeModuleDeclarations } from "../../eco/module-dependencies.js";
+import { isBrowserEcopagesVirtualImport } from "./ecopages-virtual-imports.js";
 function getDeclaredModules(value) {
   if (!Array.isArray(value)) {
     return void 0;
@@ -22,6 +23,9 @@ function mergeModuleDeclaration(modulesMap, declaration) {
 }
 function collectModuleDeclarations(modulesMap, declaredModules, autoVirtualImports) {
   for (const declaration of normalizeModuleDeclarations(getDeclaredModules(declaredModules))) {
+    if (declaration.from.startsWith("ecopages:") && !isBrowserEcopagesVirtualImport(declaration.from)) {
+      continue;
+    }
     mergeModuleDeclaration(modulesMap, declaration);
   }
   for (const declaration of autoVirtualImports) {

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

@@ -15,8 +15,8 @@
  * Timestamped navigation intent captured from pointer or hover activity.
  */
 export type EcoPendingNavigationIntent = {
-	href: string;
-	timestamp: number;
+    href: string;
+    timestamp: number;
 };
 /**
  * Finds the nearest matching anchor within an event's composed path.
@@ -28,26 +28,16 @@ export type EcoPendingNavigationIntent = {
  * @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;
+export declare function getAnchorFromNavigationEvent(event: MouseEvent | PointerEvent, linkSelector: string): HTMLAnchorElement | null;
+/**
+ * Returns whether an href targets a static asset that should use a full document load.
+ */
+export declare function isStaticAssetHref(href: string): boolean;
 /**
  * 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`.
+ * @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 declare function recoverPendingNavigationHref(
-	intent: EcoPendingNavigationIntent | null,
-	hasInFlightNavigation: boolean,
-	now: number,
-	maxAgeMs?: number,
-): string | null;
+export declare function recoverPendingNavigationHref(intent: EcoPendingNavigationIntent | null, hasInFlightNavigation: boolean, now: number, maxAgeMs?: number): string | null;

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

@@ -1,3 +1,4 @@
+import { hasKnownStaticExtension } from "../../utils/static-file-extensions.js";
 function getAnchorFromNavigationEvent(event, linkSelector) {
   const eventTarget = event.target;
   if (eventTarget instanceof HTMLAnchorElement && eventTarget.matches(linkSelector)) {
@@ -19,6 +20,14 @@ function getAnchorFromNavigationEvent(event, linkSelector) {
     (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;
+  }
+}
 function recoverPendingNavigationHref(intent, hasInFlightNavigation, now, maxAgeMs = 1e3) {
   if (!intent || !hasInFlightNavigation) {
     return null;
@@ -30,5 +39,6 @@ function recoverPendingNavigationHref(intent, hasInFlightNavigation, now, maxAge
 }
 export {
   getAnchorFromNavigationEvent,
+  isStaticAssetHref,
   recoverPendingNavigationHref
 };

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { getAnchorFromNavigationEvent, recoverPendingNavigationHref } from "./link-intent.js";
+import { getAnchorFromNavigationEvent, isStaticAssetHref, 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");
@@ -31,6 +31,17 @@ describe("getAnchorFromNavigationEvent", () => {
     expect(getAnchorFromNavigationEvent(event, "a[data-eco-link]")).toBe(anchor);
   });
 });
+describe("isStaticAssetHref", () => {
+  it("returns true for known static asset paths", () => {
+    expect(isStaticAssetHref("/skill.txt")).toBe(true);
+    expect(isStaticAssetHref("/skill/reference/full-stack.md")).toBe(true);
+    expect(isStaticAssetHref("/assets/logo.png")).toBe(true);
+  });
+  it("returns false for application routes", () => {
+    expect(isStaticAssetHref("/docs/getting-started/introduction")).toBe(false);
+    expect(isStaticAssetHref("/")).toBe(false);
+  });
+});
 describe("recoverPendingNavigationHref", () => {
   it("returns null for stale or missing pending intent state", () => {
     expect(recoverPendingNavigationHref(null, true, 10)).toBeNull();

package/src/router/client/link-navigation-policy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical link interception, prefetch eligibility, and HTML fetch guards.
+ * @module
+ */
+export type LinkNavigationPolicyOptions = {
+    /** Attribute that forces a full document reload instead of SPA navigation. */
+    reloadAttribute?: string;
+    /** Attribute that opts a link out of prefetch. */
+    noPrefetchAttribute?: string;
+};
+export type LinkNavigationDecision = {
+    shouldIntercept: true;
+    href: string;
+} | {
+    shouldIntercept: false;
+    reason: 'modified-click' | 'non-left-click' | 'external-target' | 'explicit-reload' | 'download' | 'no-prefetch' | 'invalid-href' | 'cross-origin' | 'static-asset' | 'same-page-hash';
+};
+/**
+ * Returns whether an href only adds a hash fragment on the current page.
+ */
+export declare function isSamePageHashNavigationHref(href: string): boolean;
+/**
+ * Decides whether a pointer or click on an anchor should be handled as SPA navigation.
+ */
+export declare function getLinkNavigationDecision(event: MouseEvent | PointerEvent, link: HTMLAnchorElement, options: LinkNavigationPolicyOptions): LinkNavigationDecision;
+/**
+ * Returns the href when SPA navigation should intercept the click, otherwise `null`.
+ */
+export declare function getNavigableHrefFromClick(event: MouseEvent | PointerEvent, link: HTMLAnchorElement, options: LinkNavigationPolicyOptions): string | null;
+/**
+ * Returns whether a link is eligible for hover or viewport prefetch.
+ */
+export declare function shouldPrefetchLink(link: HTMLAnchorElement, options: LinkNavigationPolicyOptions): boolean;
+/**
+ * @remarks
+ * Prefetch and SPA fetches request HTML. Only explicit `text/html` and
+ * `application/xhtml+xml` responses are accepted; missing or asset types are rejected.
+ */
+export declare function isHtmlPageResponse(response: Response): boolean;
+/**
+ * @remarks
+ * Servers should send `text/html`. When the type is missing or the runtime
+ * defaults to `text/plain` (common in tests), a document-shaped body is accepted.
+ */
+export declare function assertHtmlPageResponse(response: Response): Promise<void>;

package/src/router/client/link-navigation-policy.js

@@ -0,0 +1,101 @@
+import { isStaticAssetHref } from "./link-intent.js";
+function getLinkIneligibilityReason(link, options) {
+  if (options.noPrefetchAttribute && link.hasAttribute(options.noPrefetchAttribute)) {
+    return "no-prefetch";
+  }
+  if (options.reloadAttribute && link.hasAttribute(options.reloadAttribute)) {
+    return "explicit-reload";
+  }
+  if (link.hasAttribute("download")) {
+    return "download";
+  }
+  const href = link.getAttribute("href");
+  if (!href || href.startsWith("#") || href.startsWith("javascript:")) {
+    return "invalid-href";
+  }
+  const url = new URL(href, window.location.origin);
+  if (url.origin !== window.location.origin) {
+    return "cross-origin";
+  }
+  if (isStaticAssetHref(href)) {
+    return "static-asset";
+  }
+  return null;
+}
+function isSamePageHashNavigationHref(href) {
+  if (!href) {
+    return false;
+  }
+  const currentUrl = new URL(window.location.href);
+  const targetUrl = new URL(href, currentUrl);
+  return targetUrl.origin === currentUrl.origin && targetUrl.hash.length > 0 && targetUrl.pathname === currentUrl.pathname && targetUrl.search === currentUrl.search;
+}
+function getLinkNavigationDecision(event, link, options) {
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+    return { shouldIntercept: false, reason: "modified-click" };
+  }
+  if (event.button !== 0) {
+    return { shouldIntercept: false, reason: "non-left-click" };
+  }
+  const target = link.getAttribute("target");
+  if (target && target !== "_self") {
+    return { shouldIntercept: false, reason: "external-target" };
+  }
+  const ineligibility = getLinkIneligibilityReason(link, options);
+  if (ineligibility) {
+    return { shouldIntercept: false, reason: ineligibility };
+  }
+  const href = link.getAttribute("href");
+  if (isSamePageHashNavigationHref(href)) {
+    return { shouldIntercept: false, reason: "same-page-hash" };
+  }
+  return { shouldIntercept: true, href };
+}
+function getNavigableHrefFromClick(event, link, options) {
+  const decision = getLinkNavigationDecision(event, link, options);
+  return decision.shouldIntercept ? decision.href : null;
+}
+function shouldPrefetchLink(link, options) {
+  if (getLinkIneligibilityReason(link, options)) {
+    return false;
+  }
+  const href = link.getAttribute("href");
+  try {
+    const url = new URL(href, window.location.origin);
+    const currentPath = window.location.pathname + window.location.search;
+    const targetPath = url.pathname + url.search;
+    return currentPath !== targetPath;
+  } catch {
+    return false;
+  }
+}
+function isHtmlPageResponse(response) {
+  const contentType = response.headers.get("Content-Type");
+  if (!contentType) {
+    return false;
+  }
+  const normalized = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return normalized === "text/html" || normalized === "application/xhtml+xml";
+}
+async function assertHtmlPageResponse(response) {
+  if (isHtmlPageResponse(response)) {
+    return;
+  }
+  const contentType = response.headers.get("Content-Type");
+  const normalized = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
+  if (normalized === "text/plain" || normalized === "") {
+    const sample = (await response.clone().text()).trimStart();
+    if (sample.startsWith("<")) {
+      return;
+    }
+  }
+  throw new Error(`Expected HTML page response, received ${contentType ?? "unknown content type"}`);
+}
+export {
+  assertHtmlPageResponse,
+  getLinkNavigationDecision,
+  getNavigableHrefFromClick,
+  isHtmlPageResponse,
+  isSamePageHashNavigationHref,
+  shouldPrefetchLink
+};

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

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

package/src/router/client/link-navigation-policy.test.browser.js

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+  getLinkNavigationDecision,
+  getNavigableHrefFromClick,
+  isHtmlPageResponse,
+  isSamePageHashNavigationHref,
+  shouldPrefetchLink
+} from "./link-navigation-policy.js";
+function createLink(href, attributes = {}) {
+  const link = document.createElement("a");
+  link.href = href;
+  for (const [key, value] of Object.entries(attributes)) {
+    link.setAttribute(key, value);
+  }
+  document.body.append(link);
+  return link;
+}
+function createMouseEvent(button = 0, modifiers = {}) {
+  return new MouseEvent("click", { bubbles: true, cancelable: true, button, ...modifiers });
+}
+const policy = { reloadAttribute: "data-eco-reload", noPrefetchAttribute: "data-eco-no-prefetch" };
+describe("isSamePageHashNavigationHref", () => {
+  it("returns true for same pathname with a new hash", () => {
+    history.replaceState({}, "", "/docs/page");
+    expect(isSamePageHashNavigationHref("/docs/page#section")).toBe(true);
+  });
+});
+describe("getLinkNavigationDecision", () => {
+  it("allows same-origin page links", () => {
+    const link = createLink("/page");
+    const decision = getLinkNavigationDecision(createMouseEvent(), link, policy);
+    expect(decision).toEqual({ shouldIntercept: true, href: "/page" });
+  });
+  it("rejects static asset links", () => {
+    const link = createLink("/skill.txt");
+    expect(getLinkNavigationDecision(createMouseEvent(), link, policy)).toEqual({
+      shouldIntercept: false,
+      reason: "static-asset"
+    });
+  });
+  it("rejects explicit reload links", () => {
+    const link = createLink("/logout", { "data-eco-reload": "" });
+    expect(getLinkNavigationDecision(createMouseEvent(), link, policy)).toEqual({
+      shouldIntercept: false,
+      reason: "explicit-reload"
+    });
+  });
+});
+describe("getNavigableHrefFromClick", () => {
+  it("returns href when navigation should be intercepted", () => {
+    const link = createLink("/page");
+    expect(getNavigableHrefFromClick(createMouseEvent(), link, policy)).toBe("/page");
+  });
+  it("returns null for static assets", () => {
+    const link = createLink("/llms.txt");
+    expect(getNavigableHrefFromClick(createMouseEvent(), link, policy)).toBeNull();
+  });
+});
+describe("shouldPrefetchLink", () => {
+  it("prefetches internal page links", () => {
+    history.replaceState({}, "", "/");
+    const link = createLink("/docs/intro");
+    expect(shouldPrefetchLink(link, policy)).toBe(true);
+  });
+  it("skips static assets and opt-outs", () => {
+    history.replaceState({}, "", "/");
+    expect(shouldPrefetchLink(createLink("/skill.txt"), policy)).toBe(false);
+    expect(shouldPrefetchLink(createLink("/page", { "data-eco-no-prefetch": "" }), policy)).toBe(false);
+  });
+});
+describe("isHtmlPageResponse", () => {
+  it("accepts html content types", () => {
+    expect(isHtmlPageResponse(new Response("", { headers: { "Content-Type": "text/html; charset=utf-8" } }))).toBe(
+      true
+    );
+  });
+  it("rejects plain text responses", () => {
+    expect(isHtmlPageResponse(new Response("", { headers: { "Content-Type": "text/plain" } }))).toBe(false);
+  });
+});
+describe("isHtmlPageResponse", () => {
+  it("accepts html and xhtml content types", () => {
+    expect(isHtmlPageResponse(new Response("", { headers: { "Content-Type": "text/html" } }))).toBe(true);
+    expect(isHtmlPageResponse(new Response("", { headers: { "Content-Type": "application/xhtml+xml" } }))).toBe(
+      true
+    );
+  });
+  it("rejects plain text and markdown responses", () => {
+    expect(isHtmlPageResponse(new Response("text", { headers: { "Content-Type": "text/plain" } }))).toBe(false);
+    expect(isHtmlPageResponse(new Response("# doc", { headers: { "Content-Type": "text/markdown" } }))).toBe(false);
+  });
+});

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

@@ -96,7 +96,7 @@ export type EcoNavigationRuntimeRegistration = {
      * Implementations may honor `request.moduleUrl` to force a specific page entry
      * and `request.clearCache` to discard persisted runtime state before reloading.
      */
-    reloadCurrentPage?: (request?: EcoReloadRequest) => Promise<void>;
+    reloadCurrentPage?: (request?: EcoReloadRequest) => Promise<boolean | void>;
     /**
      * Releases runtime-owned client state before another runtime commits a new
      * document.