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

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

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

package/src/router/README.md

@@ -22,6 +22,7 @@ router/
 │   └── route-registry.ts        # Owns template routes, request matching, static expansion, and reload
 └── client/                      # Browser-side navigation coordination
     ├── navigation-coordinator.ts # Singleton runtime coordinator
+    ├── navigation-lifecycle.ts   # Shared document lifecycle events
     └── link-intent.ts           # Shared anchor detection and intent recovery helpers
 ```
 
@@ -59,6 +60,14 @@ Match priority:
 
 ## `client/`
 
+### View transitions (`@ecopages/core/client/view-transitions`)
+
+Shared helpers used by `@ecopages/browser-router` and `@ecopages/react-router`:
+
+- `applyViewTransitionNames` / `clearViewTransitionNames` — named `data-view-transition` morph / fade styles (`eco-vt-dynamic-styles`).
+- `ensureRootViewTransitionStyles` — persisted CSS (`eco-vt-root-styles`, `data-eco-persist`) with `html { view-transition-name: none }` when VT is enabled.
+- `documentHasNamedViewTransitions` / `navigationHasNamedViewTransitions` — gate `startViewTransition` to pages with `data-view-transition` markup.
+
 ### Navigation Coordinator (`navigation-coordinator.ts`)
 
 A singleton browser-side runtime stored on `window.__ECO_PAGES__.navigation`.
@@ -79,6 +88,28 @@ The coordinator is framework-agnostic. Browser runtimes (e.g. `browser-router`,
 - **Reload** — `reloadCurrentPage` delegates to whichever runtime currently owns the document.
 - **Events** — `subscribe` lets runtimes react to `owner-change` and `registration-change` events.
 
+### Navigation Lifecycle (`navigation-lifecycle.ts`)
+
+Shared document lifecycle events emitted by browser runtimes after a client navigation commits.
+
+Access it with:
+
+```ts
+import {
+	completeNavigationLifecycle,
+	dispatchBeforeSwap,
+	type EcoNavigationEvent,
+} from '@ecopages/core/router/navigation-lifecycle';
+```
+
+`browser-router` and `react-router` call these helpers around their own commit implementations. Use `completeNavigationLifecycle` for the paired post-commit signals. Listeners use the DOM contract:
+
+- `eco:before-swap` — pre-commit hook with `newDocument` and `reload()`
+- `eco:after-swap` — post-commit signal after the runtime has applied the new page
+- `eco:page-load` — scheduled on the next animation frame after `eco:after-swap`
+
+This is separate from coordinator `subscribe()` events, which track runtime ownership rather than page lifecycle.
+
 ### Link Intent (`link-intent.ts`)
 
 Shared helpers for locating anchors and recovering stale navigation intent.

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

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

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

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,122 @@
+import { isStaticAssetHref } from './link-intent.js';
+/**
+ * Shared anchor/href checks for navigation interception and prefetch eligibility.
+ */
+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;
+}
+/**
+ * Returns whether an href only adds a hash fragment on the current page.
+ */
+export 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);
+}
+/**
+ * Decides whether a pointer or click on an anchor should be handled as SPA navigation.
+ */
+export 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 };
+}
+/**
+ * Returns the href when SPA navigation should intercept the click, otherwise `null`.
+ */
+export function getNavigableHrefFromClick(event, link, options) {
+    const decision = getLinkNavigationDecision(event, link, options);
+    return decision.shouldIntercept ? decision.href : null;
+}
+/**
+ * Returns whether a link is eligible for hover or viewport prefetch.
+ */
+export 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;
+    }
+}
+/**
+ * @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 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';
+}
+/**
+ * @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 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'}`);
+}

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

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