@ecopages/core 0.2.0-beta.15 → 0.2.0-beta.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.15",
+  "version": "0.2.0-beta.17",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.15",
+    "@ecopages/file-system": "0.2.0-beta.17",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -74,6 +74,22 @@
       "types": "./src/router/client/link-intent.d.ts",
       "default": "./src/router/client/link-intent.js"
     },
+    "./router/link-navigation-policy": {
+      "types": "./src/router/client/link-navigation-policy.d.ts",
+      "default": "./src/router/client/link-navigation-policy.js"
+    },
+    "./client/scroll": {
+      "types": "./src/client/scroll.d.ts",
+      "default": "./src/client/scroll.js"
+    },
+    "./client/view-transitions": {
+      "types": "./src/client/view-transitions.d.ts",
+      "default": "./src/client/view-transitions.js"
+    },
+    "./client/navigation-scripts": {
+      "types": "./src/client/navigation-scripts/index.d.ts",
+      "default": "./src/client/navigation-scripts/index.js"
+    },
     "./eco": {
       "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",
@@ -263,6 +279,22 @@
       "types": "./src/router/client/link-intent.d.ts",
       "default": "./src/router/client/link-intent.js"
     },
+    "./router/link-navigation-policy.ts": {
+      "types": "./src/router/client/link-navigation-policy.d.ts",
+      "default": "./src/router/client/link-navigation-policy.js"
+    },
+    "./client/scroll.ts": {
+      "types": "./src/client/scroll.d.ts",
+      "default": "./src/client/scroll.js"
+    },
+    "./client/view-transitions.ts": {
+      "types": "./src/client/view-transitions.d.ts",
+      "default": "./src/client/view-transitions.js"
+    },
+    "./client/navigation-scripts.ts": {
+      "types": "./src/client/navigation-scripts/index.d.ts",
+      "default": "./src/client/navigation-scripts/index.js"
+    },
     "./eco.ts": {
       "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",

package/src/adapters/shared/fs-server-response-matcher.js

@@ -37,7 +37,7 @@ class FileSystemResponseMatcher {
    * @returns Static file response or rendered 404 response.
    */
   async handleNoMatch(requestUrl) {
-    const isStaticFileRequest = ServerUtils.hasKnownExtension(requestUrl);
+    const isStaticFileRequest = ServerUtils.hasKnownStaticExtension(requestUrl);
     if (!isStaticFileRequest) {
       return this.renderCustomNotFoundResponseOrServerError(requestUrl);
     }

package/src/client/navigation-scripts/classification.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Classifies head scripts for navigation-time persistence and execution.
+ * @module
+ */
+/**
+ * Returns whether a script tag carries non-executable data (for example JSON-LD).
+ */
+export declare function isNonExecutableHeadScript(element: Element): boolean;
+/**
+ * Returns whether an identified inline head script should survive head diffing.
+ */
+export declare function shouldPersistExecutableInlineHeadScript(element: Element): boolean;
+/**
+ * Returns whether a script is queued for rerun after navigation commit.
+ */
+export declare function isRerunScript(element: Element): element is HTMLScriptElement;

package/src/client/navigation-scripts/classification.js

@@ -0,0 +1,41 @@
+const EXECUTABLE_SCRIPT_TYPES = /* @__PURE__ */ new Set([
+  "application/javascript",
+  "application/ecmascript",
+  "module",
+  "text/ecmascript",
+  "text/javascript"
+]);
+function isNonExecutableHeadScript(element) {
+  if (element.tagName !== "SCRIPT") {
+    return false;
+  }
+  const type = (element.getAttribute("type") ?? "").trim().toLowerCase();
+  if (!type) {
+    return false;
+  }
+  return !EXECUTABLE_SCRIPT_TYPES.has(type);
+}
+function shouldPersistExecutableInlineHeadScript(element) {
+  if (element.tagName !== "SCRIPT") {
+    return false;
+  }
+  const scriptId = element.getAttribute("data-eco-script-id") || element.getAttribute("id");
+  if (!scriptId) {
+    return false;
+  }
+  if (element.hasAttribute("data-eco-rerun")) {
+    return false;
+  }
+  if (element.src) {
+    return false;
+  }
+  return !isNonExecutableHeadScript(element);
+}
+function isRerunScript(element) {
+  return element.tagName === "SCRIPT" && element.hasAttribute("data-eco-rerun");
+}
+export {
+  isNonExecutableHeadScript,
+  isRerunScript,
+  shouldPersistExecutableInlineHeadScript
+};

package/src/client/navigation-scripts/index.d.ts

@@ -0,0 +1,3 @@
+export { isNonExecutableHeadScript, isRerunScript, shouldPersistExecutableInlineHeadScript } from './classification.js';
+export { RERUN_SRC_ATTR, getRegisteredRerunScript, type RerunScriptCallback } from './registry.js';
+export { collectRerunScripts, createRerunScriptUrl, findExistingRerunScript, flushPendingRerunScripts, isExternalModuleRerunScript, resetRerunNonceForTests, type PendingRerunScript, } from './rerun-queue.js';

package/src/client/navigation-scripts/index.js

@@ -0,0 +1,23 @@
+import { isNonExecutableHeadScript, isRerunScript, shouldPersistExecutableInlineHeadScript } from "./classification.js";
+import { RERUN_SRC_ATTR, getRegisteredRerunScript } from "./registry.js";
+import {
+  collectRerunScripts,
+  createRerunScriptUrl,
+  findExistingRerunScript,
+  flushPendingRerunScripts,
+  isExternalModuleRerunScript,
+  resetRerunNonceForTests
+} from "./rerun-queue.js";
+export {
+  RERUN_SRC_ATTR,
+  collectRerunScripts,
+  createRerunScriptUrl,
+  findExistingRerunScript,
+  flushPendingRerunScripts,
+  getRegisteredRerunScript,
+  isExternalModuleRerunScript,
+  isNonExecutableHeadScript,
+  isRerunScript,
+  resetRerunNonceForTests,
+  shouldPersistExecutableInlineHeadScript
+};

package/src/client/navigation-scripts/navigation-scripts.test.browser.d.ts

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

package/src/client/navigation-scripts/navigation-scripts.test.browser.js

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { isNonExecutableHeadScript } from "./classification.js";
+import {
+  collectRerunScripts,
+  createRerunScriptUrl,
+  flushPendingRerunScripts,
+  resetRerunNonceForTests
+} from "./rerun-queue.js";
+import { RERUN_SRC_ATTR } from "./registry.js";
+describe("isNonExecutableHeadScript", () => {
+  it("treats JSON-LD scripts as non-executable", () => {
+    const script = document.createElement("script");
+    script.type = "application/ld+json";
+    expect(isNonExecutableHeadScript(script)).toBe(true);
+  });
+  it("treats untyped scripts as executable", () => {
+    const script = document.createElement("script");
+    expect(isNonExecutableHeadScript(script)).toBe(false);
+  });
+});
+describe("collectRerunScripts and flushPendingRerunScripts", () => {
+  afterEach(() => {
+    document.head.replaceChildren();
+    document.body.replaceChildren();
+    resetRerunNonceForTests();
+  });
+  it("replays registered rerun callbacks without duplicating script tags", () => {
+    const callback = vi.fn();
+    window.__ECO_PAGES__ = {
+      rerunScripts: { "eco-test": callback }
+    };
+    try {
+      flushPendingRerunScripts([
+        {
+          parent: "head",
+          attributes: [
+            ["data-eco-rerun", ""],
+            ["data-eco-script-id", "eco-test"]
+          ],
+          textContent: "",
+          src: null,
+          scriptId: "eco-test"
+        }
+      ]);
+      expect(callback).toHaveBeenCalledOnce();
+      expect(document.head.querySelector('script[data-eco-script-id="eco-test"]')).toBeNull();
+    } finally {
+      delete window.__ECO_PAGES__;
+    }
+  });
+  it("cache-busts external module rerun scripts", () => {
+    const html = '<html><head><script data-eco-rerun src="/app.js" type="module"><\/script></head></html>';
+    const parsed = new DOMParser().parseFromString(html, "text/html");
+    const scripts = collectRerunScripts(parsed);
+    flushPendingRerunScripts(scripts);
+    const inserted = document.head.querySelector(`script[${RERUN_SRC_ATTR}]`);
+    expect(inserted?.getAttribute("src")).toMatch(/__eco_rerun=1/);
+    expect(inserted?.getAttribute(RERUN_SRC_ATTR)).toBe("/app.js");
+  });
+  it("appends a unique nonce on each module rerun url", () => {
+    const first = createRerunScriptUrl("/app.js");
+    const second = createRerunScriptUrl("/app.js");
+    expect(first).not.toBe(second);
+  });
+});

package/src/client/navigation-scripts/registry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `__ECO_PAGES__.rerunScripts` registry access for navigation reruns.
+ * @module
+ */
+export type RerunScriptCallback = () => void;
+/** Attribute storing the original module `src` after cache-busting. */
+export declare const RERUN_SRC_ATTR = "data-eco-rerun-src";
+/**
+ * Returns a registered in-memory rerun callback for the given script id.
+ */
+export declare function getRegisteredRerunScript(scriptId: string | null): RerunScriptCallback | null;

package/src/client/navigation-scripts/registry.js

@@ -0,0 +1,12 @@
+const RERUN_SRC_ATTR = "data-eco-rerun-src";
+function getRegisteredRerunScript(scriptId) {
+  if (!scriptId) {
+    return null;
+  }
+  const runtimeWindow = window;
+  return runtimeWindow.__ECO_PAGES__?.rerunScripts?.[scriptId] ?? null;
+}
+export {
+  RERUN_SRC_ATTR,
+  getRegisteredRerunScript
+};

package/src/client/navigation-scripts/rerun-queue.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Queueing and replay of `data-eco-rerun` scripts after navigation.
+ * @module
+ */
+export type PendingRerunScript = {
+    parent: 'head' | 'body';
+    attributes: Array<[string, string]>;
+    textContent: string;
+    src: string | null;
+    scriptId: string | null;
+};
+/**
+ * Collects rerun scripts from an incoming document.
+ */
+export declare function collectRerunScripts(document: Document, filter?: (script: HTMLScriptElement) => boolean): PendingRerunScript[];
+/**
+ * Returns whether a rerun script is an external ES module that needs cache busting.
+ */
+export declare function isExternalModuleRerunScript(script: PendingRerunScript): boolean;
+/**
+ * Finds an existing rerun script in `root` by id or by src and inline content.
+ */
+export declare function findExistingRerunScript(root: ParentNode, script: PendingRerunScript): HTMLScriptElement | null;
+/**
+ * Appends a nonce query parameter so module scripts re-execute after navigation.
+ */
+export declare function createRerunScriptUrl(src: string): string;
+/**
+ * Replays queued rerun scripts after the incoming page body is in place.
+ *
+ * @remarks
+ * Flushed elements keep `data-eco-rerun` so head cleanup does not treat them
+ * as persistable inline scripts on the next navigation.
+ */
+export declare function flushPendingRerunScripts(scripts: readonly PendingRerunScript[]): void;
+/** @remarks Test-only reset for nonce sequencing. */
+export declare function resetRerunNonceForTests(): void;

package/src/client/navigation-scripts/rerun-queue.js

@@ -0,0 +1,73 @@
+import { RERUN_SRC_ATTR, getRegisteredRerunScript } from "./registry.js";
+let rerunNonce = 0;
+function collectRerunScripts(document2, filter) {
+  return Array.from(document2.querySelectorAll("script[data-eco-rerun]")).filter((script) => filter ? filter(script) : true).map((script) => ({
+    parent: script.closest("body") ? "body" : "head",
+    attributes: Array.from(script.attributes).map((attribute) => [attribute.name, attribute.value]),
+    textContent: script.textContent ?? "",
+    src: script.getAttribute("src"),
+    scriptId: script.getAttribute("data-eco-script-id")
+  }));
+}
+function isExternalModuleRerunScript(script) {
+  if (!script.src) {
+    return false;
+  }
+  return script.attributes.some(([name, value]) => name === "type" && value === "module");
+}
+function findExistingRerunScript(root, script) {
+  const scripts = Array.from(root.querySelectorAll("script"));
+  if (script.scriptId) {
+    return scripts.find((candidate) => candidate.getAttribute("data-eco-script-id") === script.scriptId) ?? null;
+  }
+  return scripts.find(
+    (candidate) => (candidate.getAttribute(RERUN_SRC_ATTR) ?? candidate.getAttribute("src")) === script.src && (candidate.textContent ?? "") === script.textContent
+  ) ?? null;
+}
+function createRerunScriptUrl(src) {
+  const url = new URL(src, document.baseURI);
+  url.searchParams.set("__eco_rerun", String(++rerunNonce));
+  return url.toString();
+}
+function flushPendingRerunScripts(scripts) {
+  for (const script of scripts) {
+    const targetParent = script.parent === "body" ? document.body : document.head;
+    const registeredRerun = getRegisteredRerunScript(script.scriptId);
+    const replacement = document.createElement("script");
+    const shouldBustModuleSrc = isExternalModuleRerunScript(script) && !registeredRerun;
+    for (const [name, value] of script.attributes) {
+      if (name === "src" && shouldBustModuleSrc) {
+        replacement.setAttribute(RERUN_SRC_ATTR, value);
+        replacement.setAttribute("src", createRerunScriptUrl(value));
+        continue;
+      }
+      replacement.setAttribute(name, value);
+    }
+    replacement.textContent = script.textContent;
+    const existingScript = findExistingRerunScript(targetParent, script);
+    if (registeredRerun) {
+      const needsScriptElement = isExternalModuleRerunScript(script);
+      if (!existingScript && needsScriptElement) {
+        targetParent.appendChild(replacement);
+      }
+      registeredRerun();
+      continue;
+    }
+    if (existingScript) {
+      existingScript.replaceWith(replacement);
+      continue;
+    }
+    targetParent.appendChild(replacement);
+  }
+}
+function resetRerunNonceForTests() {
+  rerunNonce = 0;
+}
+export {
+  collectRerunScripts,
+  createRerunScriptUrl,
+  findExistingRerunScript,
+  flushPendingRerunScripts,
+  isExternalModuleRerunScript,
+  resetRerunNonceForTests
+};

package/src/client/scroll.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Window scroll behavior during client-side navigations.
+ * @module
+ */
+export type WindowScrollBehavior = 'top' | 'preserve' | 'auto';
+export type ManageWindowScrollOptions = {
+    scrollBehavior: WindowScrollBehavior;
+    smoothScroll: boolean;
+};
+/**
+ * Updates window scroll position after a navigation commit.
+ *
+ * @remarks
+ * Hash navigations always scroll to the target element and ignore `scrollBehavior`.
+ * Fragment targets are resolved by element id (`#section` → `getElementById('section')`).
+ */
+export declare function manageWindowScroll(newUrl: URL, previousUrl: URL, options: ManageWindowScrollOptions): void;

package/src/client/scroll.js

@@ -0,0 +1,25 @@
+function manageWindowScroll(newUrl, previousUrl, options) {
+  const { scrollBehavior, smoothScroll } = options;
+  if (newUrl.hash) {
+    const target = document.getElementById(newUrl.hash.slice(1));
+    target?.scrollIntoView({ behavior: smoothScroll ? "smooth" : "instant" });
+    return;
+  }
+  const behavior = smoothScroll ? "smooth" : "instant";
+  switch (scrollBehavior) {
+    case "preserve":
+      break;
+    case "auto":
+      if (newUrl.pathname !== previousUrl.pathname) {
+        window.scrollTo({ top: 0, left: 0, behavior });
+      }
+      break;
+    case "top":
+    default:
+      window.scrollTo({ top: 0, left: 0, behavior });
+      break;
+  }
+}
+export {
+  manageWindowScroll
+};

package/src/client/scroll.test.browser.d.ts

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

package/src/client/scroll.test.browser.js

@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { manageWindowScroll } from "./scroll.js";
+const options = { scrollBehavior: "top", smoothScroll: false };
+describe("manageWindowScroll", () => {
+  afterEach(() => {
+    history.replaceState({}, "", "/");
+    document.body.replaceChildren();
+    vi.restoreAllMocks();
+  });
+  it("scrolls to top by default", () => {
+    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {
+    });
+    manageWindowScroll(new URL("/next", window.location.origin), new URL("/prev", window.location.origin), options);
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, left: 0, behavior: "instant" });
+  });
+  it("preserves scroll when scrollBehavior is preserve", () => {
+    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {
+    });
+    manageWindowScroll(new URL("/next", window.location.origin), new URL("/prev", window.location.origin), {
+      ...options,
+      scrollBehavior: "preserve"
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it("scrolls to hash target by element id", () => {
+    const section = document.createElement("section");
+    section.id = "section";
+    section.scrollIntoView = vi.fn();
+    document.body.append(section);
+    manageWindowScroll(
+      new URL("/page#section", window.location.origin),
+      new URL("/page", window.location.origin),
+      options
+    );
+    expect(section.scrollIntoView).toHaveBeenCalledWith({ behavior: "instant" });
+  });
+});

package/src/client/view-transitions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * View Transition API helpers for `data-view-transition` markup.
+ * @module
+ */
+/**
+ * Assigns `view-transition-name` from `data-view-transition` and injects morph styles.
+ *
+ * @remarks
+ * Elements without `data-view-transition-animate="fade"` get a geometric morph:
+ * the old snapshot is hidden so cross-fade ghosting does not appear.
+ */
+export declare function applyViewTransitionNames(): void;
+/**
+ * Clears inline transition names and dynamic morph styles after a transition ends.
+ */
+export declare function clearViewTransitionNames(): void;

package/src/client/view-transitions.js

@@ -0,0 +1,63 @@
+const VIEW_TRANSITION_ATTR = "data-view-transition";
+const VIEW_TRANSITION_ANIMATE_ATTR = "data-view-transition-animate";
+const VIEW_TRANSITION_DURATION_ATTR = "data-view-transition-duration";
+const DYNAMIC_STYLES_ID = "eco-vt-dynamic-styles";
+function applyViewTransitionNames() {
+  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+  const morphNames = [];
+  const customDurations = [];
+  elements.forEach((el) => {
+    const name = el.getAttribute(VIEW_TRANSITION_ATTR);
+    if (!name) {
+      return;
+    }
+    el.style.viewTransitionName = name;
+    const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
+    if (animate !== "fade") {
+      morphNames.push(name);
+    }
+    const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
+    if (duration) {
+      customDurations.push({ name, duration });
+    }
+  });
+  if (morphNames.length > 0 || customDurations.length > 0) {
+    injectDynamicStyles(morphNames, customDurations);
+  }
+}
+function clearViewTransitionNames() {
+  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+  elements.forEach((el) => {
+    el.style.viewTransitionName = "";
+  });
+  const styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+  if (styleEl) {
+    styleEl.textContent = "";
+  }
+}
+function injectDynamicStyles(morphNames, customDurations) {
+  let styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+  if (!styleEl) {
+    styleEl = document.createElement("style");
+    styleEl.id = DYNAMIC_STYLES_ID;
+    styleEl.setAttribute("data-eco-persist", "");
+    document.head.append(styleEl);
+  }
+  const morphCss = morphNames.map(
+    (name) => `
+		::view-transition-old(${name}) { display: none !important; }
+		::view-transition-new(${name}) { animation: none !important; opacity: 1 !important; }
+	`
+  ).join("\n");
+  const durationCss = customDurations.map(
+    ({ name, duration }) => `
+		::view-transition-group(${name}) { animation-duration: ${duration} !important; }
+	`
+  ).join("\n");
+  styleEl.textContent = `${morphCss}
+${durationCss}`;
+}
+export {
+  applyViewTransitionNames,
+  clearViewTransitionNames
+};

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,39 @@
+/**
+ * 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;

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

@@ -0,0 +1,86 @@
+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";
+}
+export {
+  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/utils/server-utils.module.d.ts

@@ -1,3 +1,4 @@
+import { hasKnownStaticExtension } from './static-file-extensions.js';
 /**
  * Get the content type of a file based on its extension.
  * @param file - The file name.
@@ -9,11 +10,11 @@ export declare const getContentType: (file: string) => string;
  * @param file - The file name or path.
  * @returns true if the extension is recognized.
  */
-export declare const hasKnownExtension: (file: string) => boolean;
+export { hasKnownStaticExtension } from './static-file-extensions.js';
 /**
  * A module for server utilities.
  */
 export declare const ServerUtils: {
     getContentType: (file: string) => string;
-    hasKnownExtension: (file: string) => boolean;
+    hasKnownStaticExtension: typeof hasKnownStaticExtension;
 };

package/src/utils/server-utils.module.js

@@ -1,3 +1,4 @@
+import { hasKnownStaticExtension } from "./static-file-extensions.js";
 const ContentTypeMap = /* @__PURE__ */ new Map([
   ["jpg", "image/jpeg"],
   ["jpeg", "image/jpeg"],
@@ -42,16 +43,13 @@ const getContentType = (file) => {
   const extension = file.split(".").pop() || "txt";
   return ContentTypeMap.get(extension) || "text/plain";
 };
-const hasKnownExtension = (file) => {
-  const extension = file.split(".").pop();
-  return extension !== void 0 && ContentTypeMap.has(extension);
-};
+import { hasKnownStaticExtension as hasKnownStaticExtension2 } from "./static-file-extensions.js";
 const ServerUtils = {
   getContentType,
-  hasKnownExtension
+  hasKnownStaticExtension
 };
 export {
   ServerUtils,
   getContentType,
-  hasKnownExtension
+  hasKnownStaticExtension2 as hasKnownStaticExtension
 };

package/src/utils/static-file-extensions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Known static asset extensions served directly from disk.
+ *
+ * @remarks
+ * Keep this list aligned with server static-file handling and client routers
+ * that must bypass SPA navigation for same-origin asset links.
+ */
+export declare const STATIC_FILE_EXTENSIONS: Set<string>;
+/**
+ * Returns whether a path or filename ends with a known static asset extension.
+ */
+export declare function hasKnownStaticExtension(fileOrPath: string): boolean;

package/src/utils/static-file-extensions.js

@@ -0,0 +1,48 @@
+const STATIC_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "jpg",
+  "jpeg",
+  "png",
+  "gif",
+  "bmp",
+  "svg",
+  "tiff",
+  "webp",
+  "avif",
+  "ico",
+  "mp3",
+  "ogg",
+  "wav",
+  "mp4",
+  "webm",
+  "ogv",
+  "mov",
+  "txt",
+  "md",
+  "html",
+  "css",
+  "js",
+  "mjs",
+  "json",
+  "map",
+  "xml",
+  "webmanifest",
+  "wasm",
+  "csv",
+  "ttf",
+  "woff",
+  "woff2",
+  "otf",
+  "eot",
+  "gz",
+  "zip",
+  "pdf",
+  "doc"
+]);
+function hasKnownStaticExtension(fileOrPath) {
+  const extension = fileOrPath.split(".").pop();
+  return extension !== void 0 && STATIC_FILE_EXTENSIONS.has(extension);
+}
+export {
+  STATIC_FILE_EXTENSIONS,
+  hasKnownStaticExtension
+};